oauth2-proxy Forward auth 設定 SSO
用 oauth2-proxy 讓沒有登入功能的應用程式接上 OIDC SSO,了解 Nginx、Traefik 設定,以及 cookie、redirect 與公開連接埠的常見陷阱。
轉送驗證:沒有登入功能的應用程式如何取得 SSO
oauth2-proxy 能為沒有內建登入功能的應用程式提供單一登入。其運作方式是,應用程式前方的反向代理攔截每個請求,詢問 oauth2-proxy 該請求是否包含有效工作階段,只有收到肯定回應時才將請求轉送至上游。應用程式程式碼不需要修改,因為應用程式本身不會看到這項檢查。
這項檢查會額外發出 1 個 HTTP 請求。代理會將傳入請求標頭的副本傳送至 /oauth2/auth,並讀取狀態碼。202 表示檢查通過,因此代理會將原始請求轉送至應用程式。401 表示沒有有效工作階段,因此代理會將瀏覽器導向 /oauth2/sign_in;該頁面預設會顯示登入頁面。/oauth2/start 會在身分識別提供者上啟動 OpenID Connect (OIDC) 登入;skip_provider_button = true 會讓 /oauth2/sign_in 自動啟動登入流程。OIDC 是建構在 OAuth 2.0 之上的身分識別層,而提供者就是你目前用於登入的服務。
每種反向代理都有對應的名稱來實作這種模式。Nginx 將此指令稱為 auth_request。Traefik 將此 middleware 稱為 forwardAuth。Caddy 將其寫作 forward_auth。負責回應子請求的服務也可以替換。oauth2-proxy 是常見選擇,因為它支援標準 OIDC,且不需要自有資料庫。
在撰寫任何設定前,先劃定信任邊界
完成檢查後,oauth2-proxy 會以回應標頭傳回身分識別資訊,反向代理再將這些標頭複製到傳給上游的請求。啟用 set_xauthrequest 後,會取得 X-Auth-Request-User 與 X-Auth-Request-Email。應用程式讀取這些標頭,並信任其中的內容。
這就是完整的安全模型,因此必須明確說明其後果。任何能對應用程式連接埠建立 TCP 連線的對象,都能自行設定這些標頭,並冒充任何使用者。只要單一 curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ 能直接連到應用程式,就足以完全繞過驗證。
因此,應用程式只能透過代理存取。在 Docker Compose 中,從應用程式服務刪除 ports: 對映,並讓服務留在內部網路上,這樣只有代理容器能連線到它。在裸機主機上,將應用程式繫結至 127.0.0.1:3000,不要繫結至 0.0.0.0:3000。接著檢查實際暴露的內容:
sudo ss -tlnp | grep 3000若看到 0.0.0.0:3000,表示應用程式會在公開 IP 上接受請求,驗證閘道形同虛設。127.0.0.1:3000 才是正確結果。防火牆規則可作為第二層防護,但繫結位址才不會因其他工具清除規則集而失效。
安裝 oauth2-proxy
截至 2026 年 10 月,目前版本為 v7.15.5,發布日期為 1 October 2026。此版本修正 2 個重大安全性公告,其中 1 個是可繞過 skip_auth_routes 的問題,會影響 v7.5.0 之後的所有版本,因此不要安裝更早的版本。安裝二進位檔並驗證下載內容:
cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --versionsha256sum -c 必須輸出以 OK 結尾的行。如果輸出 FAILED,請停止操作並重新下載,不要執行該二進位檔。
在 Docker 中,映像檔為 quay.io/oauth2-proxy/oauth2-proxy,且應固定標籤:quay.io/oauth2-proxy/oauth2-proxy:v7.15.5。若保留為 latest,例行的 docker compose pull 就可能變成非預期升級,進而影響這台主機上保護所有應用程式的唯一程序。
產生 cookie secret
工作階段 cookie 已加密,而 cookie_secret 是加密金鑰。加密金鑰必須正好為 16、24 或 32 bytes,因為它會成為 AES(advanced encryption standard)金鑰。oauth2-proxy 接受 URL-safe base64 值;該值解碼後必須是上述其中一種長度。它也接受上述其中一種長度的原始 secret。否則 oauth2-proxy 會拒絕啟動,並在啟動錯誤中指出 cookie secret。以下命令會產生一個 44 字元的值,用來編碼 32-byte 金鑰。
openssl rand -base64 32 | tr -- '+/' '-_'tr 並非僅供顯示。它會將標準 base64 轉換為 oauth2-proxy 解碼 secret 時使用的 URL-safe 字元集。
此值有兩項規則。每個部署都必須使用不同的 secret。如果在同一個網域後方執行多個 oauth2-proxy instance,所有 instance 都必須使用相同的 secret,因為其中一個 instance 加密的 cookie 必須能由其他 instance 讀取。
撰寫 oauth2-proxy 設定
將設定放在檔案中,不要使用過長的命令列,這樣 client secret 就不會出現在 ps 輸出中。
# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true
provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"
redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]
email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]reverse_proxy = true 會告訴 oauth2-proxy 信任前方 proxy 傳入的 X-Forwarded-* 標頭。未設定時,oauth2-proxy 會將 proxy 自身的位址視為 client 位址,因此可能錯誤判斷請求是否透過 HTTPS 傳入。
trusted_proxy_ips 會限制哪些對等端可以提供這些標頭。預設值會信任所有來源;這裡之所以安全,是因為 http_address 會讓 oauth2-proxy 僅在 127.0.0.1 上監聽。如果 oauth2-proxy 改在 Docker network 上監聽,請將其設為 reverse proxy 的位址。
upstreams = ["static://202"] 會讓 oauth2-proxy 對已驗證的請求回應 202,且不轉送任何內容。這正是 forward auth 所需的行為,因為實際轉送請求的是 reverse proxy。另一種部署方式是使用 upstreams = ["http://127.0.0.1:3000"],讓 oauth2-proxy 直接位於請求路徑中,完全不使用 auth_request。這種方式適合單一應用程式,但無法擴展到 ten 個應用程式。
email_domains = ["*"] 會允許 provider 驗證的所有位址。請將範圍縮小至自己的網域;更好的方式是在 provider 中使用群組繫結限制存取,因為人員管理本來就已在 provider 中進行。
使用專用使用者以 systemd 執行:
# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target
[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true
[Install]
WantedBy=multi-user.targetsudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/ping/ping 顯示 OK,表示程序已啟動並載入設定。這是 oauth2-proxy 自己的健康檢查端點,不會要求 session。若沒有任何回應,請查看 journalctl -u oauth2-proxy -n 50,因為錯誤的 issuer URL 和長度不正確的 cookie secret 都會在啟動時失敗,且日誌會明確指出原因。
註冊提供者的重新導向 URI
在提供者中建立 OIDC 應用程式,並將其重新導向 URI 設為與設定中的 redirect_url 完全相同:https://app.example.com/oauth2/callback。所謂完全相同,是指配置、主機、連接埠與路徑都必須逐字元一致。結尾的斜線會使其成為不同的 URI。
這是整個設定中最常見的失敗原因,而且會在 oauth2-proxy 介入之前就發生。提供者會拒絕授權請求並顯示自己的錯誤頁面,因此 oauth2-proxy 日誌中不會出現任何內容。判斷依據是瀏覽器的網址列:瀏覽器仍停留在提供者的網域,且查詢字串包含 error=invalid_request,或頁面直接顯示 redirect_uri。看到這種情況時,請修正提供者中的應用程式記錄,而不是代理伺服器設定。
請直接從提供者複製 issuer URL,不要手動輸入。oauth2-proxy 會將 /.well-known/openid-configuration 附加至 oidc_issuer_url,並在啟動時擷取該探索文件。請先自行檢查:
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400包含 authorization_endpoint 索引鍵的 JSON 是第一項檢查內容;此外,文件中的 issuer 也必須與 oidc_issuer_url 完全相同。收到 404 或 HTML 錯誤頁面表示設定錯誤,而 oauth2-proxy 也會因為相同的 404 而無法啟動。若尚未選定提供者,Keycloak、Authentik 與 Zitadel 的比較說明了各項取捨,而將 Authentik 執行為自有的 SSO 伺服器則示範此設定中提供者端的完整流程。
Nginx:auth_request
Nginx 透過 auth_request 執行轉送驗證。此指令會發出內部子請求,並根據其狀態碼分支處理。
# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name app.example.com;
location /oauth2/ {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Auth-Request-Redirect $request_uri;
}
location = /oauth2/auth {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header Content-Length "";
proxy_pass_request_body off;
}
location / {
auth_request /oauth2/auth;
error_page 401 = @oauth2_signin;
auth_request_set $user $upstream_http_x_auth_request_user;
auth_request_set $email $upstream_http_x_auth_request_email;
proxy_set_header X-User $user;
proxy_set_header X-Email $email;
auth_request_set $auth_cookie $upstream_http_set_cookie;
add_header Set-Cookie $auth_cookie;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location @oauth2_signin {
return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}
}其中有 3 個細節不可省略。proxy_pass_request_body off 搭配空白的 Content-Length,可避免 nginx 將請求本文轉送至驗證端點,因為該端點只需要標頭。
auth_request_set $auth_cookie 與 add_header Set-Cookie 的組合會將更新後的 session cookie 傳回瀏覽器。省略這組設定時,cookie_refresh 會靜默失效,因為 nginx 會捨棄子請求的 Set-Cookie,瀏覽器也會持續使用舊值,直到 session 過期。這組設定只能處理 1 個 cookie。若 session cookie 分成多個部分,必須另外處理其餘部分,或改用 Redis session storage。
error_page 401 = @oauth2_signin 會將驗證失敗轉換為登入流程。若沒有這項設定,未驗證的訪客只會看到空白的 401 Authorization Required 頁面,沒有繼續操作的方法。
重新載入前一律先測試:
sudo nginx -t && sudo systemctl reload nginx如果你不熟悉周圍的指令,nginx reverse proxy 設定檔的結構說明了這一層以下的配置。
Traefik:forwardAuth 中介軟體
Traefik 需要兩個中介軟體來完成相同工作。其中一個執行檢查。另一個在檢查失敗時提供登入頁面。
# dynamic configuration
http:
middlewares:
oauth-auth:
forwardAuth:
address: https://oauth.example.com/oauth2/auth
trustForwardHeader: true
oauth-errors:
errors:
status:
- "401-403"
service: oauth-backend
query: "/oauth2/sign_in?rd={url}"將兩者都附加至位於應用程式前方的 router,並讓 oauth-errors 排在 oauth-auth 前面;另外,將 oauth2-proxy 發布在 oauth.example.com 的獨立 router 上,因為瀏覽器必須在未經檢查的情況下存取 /oauth2/sign_in 和 /oauth2/callback。對於這個獨立的登入主機,將 redirect_url 設為 https://oauth.example.com/oauth2/callback,並向 provider 註冊該 URI。
使用上述 oauth2-proxy 設定時,/oauth2/sign_in 會顯示登入頁面。若要改用自動重新導向,請在 oauth2-proxy 中設定 skip_provider_button = true,並在 Traefik 的 errors 設定下加入 statusRewrites: {"401": 302}。若沒有這項 rewrite,Traefik 會以 401 狀態回傳自動重新導向,而瀏覽器不會跟隨該重新導向。單獨加入 rewrite 不會啟動登入流程。
trustForwardHeader: true 會信任傳入的 X-Forwarded-* 標頭;Traefik 會將原始 host 和 URI 提供給 oauth2-proxy。目前 Traefik 文件已將此選項標示為 deprecated。請將 whitelist_domains 設定為涵蓋該主機,否則 oauth2-proxy 會因為開放重新導向風險而捨棄 rd 參數,所有人在登入後都會前往 /。Traefik 主機通常會同時代理多個應用程式,而 透過單一 Traefik instance 路由多個 Docker Compose 應用程式 說明了此設定所接入的 router 配置。
Caddy:forward_auth
app.example.com {
handle /oauth2/* {
reverse_proxy 127.0.0.1:4180 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Uri {uri}
}
}
handle {
forward_auth 127.0.0.1:4180 {
uri /oauth2/auth
header_up X-Real-IP {remote_host}
copy_headers X-Auth-Request-User X-Auth-Request-Email
@error status 401
handle_response @error {
redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
}
}
reverse_proxy 127.0.0.1:3000
}
}順序很重要。/oauth2/* 區塊必須放在前面,且不含 forward_auth,因為尚未登入的訪客必須能夠存取登入與回呼路徑。若將檢查放在這些路徑之前,登入要求就會不斷重新導向至自身,直到瀏覽器放棄為止。
copy_headers 會將身分資訊帶入上游請求,而只有在 oauth2-proxy 搭配 set_xauthrequest = true 執行時,才會產生這些值。如何在各代理伺服器之間選擇是另一個問題,nginx、Caddy 與 Traefik 的比較會進一步說明。
為什麼登入會一直回到登入頁面?
您在身分提供者完成登入後,身分提供者將您導回,oauth2-proxy 卻又將您導回登入頁面。這表示 oauth2-proxy 在下一個請求中未接受有效的工作階段。工作階段 cookie 可能遺失,也可能存在但驗證失敗,例如各執行個體使用不同的 cookie secret。開啟瀏覽器的開發人員工具,找到身分提供者重新導回後送往 /oauth2/callback 的請求,並讀取其 Set-Cookie response header。若該處設定了 cookie,但下一個請求未帶上,表示瀏覽器拒絕傳送該 cookie。若 cookie 確實存在,請檢查伺服器日誌中的驗證錯誤,例如 cookie signature not valid,並確認所有執行個體使用相同的 secret。
如果遺失的是 oauth2-proxy 在導向登入時設定的 CSRF cookie,流程不會形成迴圈,而是停在 callback,日誌會指出原因:
No cookies were found in OAuth callback.或在其他 cookie 已成功傳送,但正確的 cookie 未傳送時:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF 是跨網站請求偽造。此 cookie 用來確認 callback 對應到啟動該次登入的請求。瀏覽器會顯示帶有以下內容的 403 錯誤頁面:
Login Failed: Unable to find a valid CSRF token. Please try again.cookie 遺失通常有以下前 3 個原因;時鐘偏移則是驗證失敗的另一個原因。請依序檢查這 4 項。
cookie_secure = true,但瀏覽器是透過純 HTTP 存取網站。除 localhost 外,瀏覽器不會在http://origin 上儲存標記為Secure的 cookie,因此之後不會傳回該 cookie。請正確終止 TLS (transport layer security),或僅在 localhost 測試時設定cookie_secure = false。cookie_domains值未涵蓋網址列中的主機名稱。.example.com涵蓋app.example.com,對app.example.net完全不起作用。- 瀏覽器正在捨棄 cookie。嚴格的隱私擴充功能或第三方 cookie 封鎖功能,可能會在導向離開與 callback 之間移除
_oauth2_proxy_csrf,也可能移除之後的工作階段 cookie。 - 時鐘偏移。如果伺服器時鐘大幅超前身分提供者的時鐘,ID token 可能被判定為已過期,導致驗證失敗。
timedatectl應回報System clock synchronized: yes。
另一個原因也會產生 CSRF 錯誤,但設定本身沒有問題。oauth2-proxy 預設只保留單一 CSRF cookie,因此兩個分頁同時啟動登入時,會互相覆寫 cookie。cookie_csrf_per_request = true 會為每次登入建立專用的 cookie。
請從伺服器端觀察實際情況,不要只靠猜測:
sudo journalctl -u oauth2-proxy -f在私密視窗中載入應用程式。每個請求都會記錄其狀態,因此 callback 後立即再次重新導向至登入頁面時,日誌會清楚顯示這個迴圈。
必須略過登入的路徑:API、webhook 與 websocket
Forward auth 假設瀏覽器持有 cookie。沒有瀏覽器的呼叫端會失敗。
傳送 Authorization: Bearer <token> 的 API 用戶端沒有 cookie,因此除非啟用 bearer-token 驗證,否則上述代理設定會將其導向 oauth2-proxy 的登入頁面。有兩種簡潔的處理方式。設定 skip_jwt_bearer_tokens = true 後,oauth2-proxy 會接受由已設定 issuer 簽發、且 audience 符合此用戶端的有效 JWT(JSON Web Token)bearer token。若 API 用戶端已從該 provider 取得適用的 token,這是正確的做法。Token 的 aud 必須符合 client_id,或符合透過 extra_jwt_issuers 設定的 audience。否則,請將該路徑排除:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]每個值都是正規表示式,會比對解碼後且不含 query parameters 的路徑;也可以在前面加上 HTTP method 與 =。POST=^/webhook/ 會讓 webhook receiver 開放 POST,同時人員以瀏覽器存取相同路徑時仍會進入登入流程,前提是 authentication request 保留原始 method。Nginx auth_request 與 Caddy forward_auth 會執行 GET 檢查,因此在這些設定中,指定 method 的排除規則必須由 reverse proxy 進行額外的路由。每個項目都是驗證閘門上的一個缺口,因此請使用 ^ 錨定正規表示式,並將範圍限制在呼叫端所需的最小程度。
在依賴這些功能前,請執行 v7.15.5 或更新版本。v7.5.0 之後的早期版本可能遭利用:攻擊者透過包含 dot segments、重複開頭斜線或分號的 request,讓受保護的路徑被錯誤排除(公告 GHSA-63jm-59jj-478j);即使將正規表示式錨定,也無法避免此問題。修正版會拒絕排除這類有歧義的路徑,因此升級後請確認公開路由仍能正確比對。
Websocket 是最容易設定錯誤的情況。Upgrade request 是一般的 HTTP GET,並攜帶與其他 request 相同的 cookie,因此會正常通過檢查,不需要排除。真正會失敗的是周邊的代理設定。受保護的 location 若沒有 Upgrade 與 Connection 標頭,upgrade 就無法完成,應用程式的用戶端會持續重試,並在瀏覽器主控台顯示 WebSocket connection ... failed 訊息。排除該路徑無法解決問題,因為該 request 原本就已完成授權。
確實存在一項限制。檢查只會在 upgrade 時執行一次。持續開啟數小時的 websocket 不會再次接受檢查,因此即使從 provider 移除使用者,也不會關閉該使用者已持有的 socket。請重新啟動應用程式,以中斷現有連線。
工作階段儲存,以及過大的 cookie
預設情況下,整個工作階段都會儲存在 cookie 中,並使用你的 cookie_secret 加密。這能讓 oauth2-proxy 維持無狀態,且不需要額外的服務。這種方式也有上限,因為瀏覽器會將 cookie 限制在約 4 KB。當 ID token 包含很長的群組宣告清單時,oauth2-proxy 會將工作階段拆分到 _oauth2_proxy_0、_oauth2_proxy_1 及後續的 cookie 中。當拆分成數個部分後,請求標頭可能會變得過大,導致 nginx 在應用程式收到請求前就回應 400 Request Header Or Cookie Too Large。
發生這種情況時,請將工作階段移至伺服器端:
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"此時瀏覽器只會保存一個簡短的 ticket,加密後的工作階段則儲存在 Redis 中。代價是必須維持一項持續運作的服務:如果 Redis 停止運作,oauth2-proxy 就無法載入工作階段;如果儲存的工作階段資料遺失,所有人都必須重新登入。cookie store 也有自身的代價:兩個同時更新相同工作階段的請求可能互相衝突,導致使用者必須重新登入。
Forward auth 無法提供的功能
這是門口的閘門。它不是應用程式內部的授權機制,而這項差異會決定這種做法是否適合你的情境。
使用者通過後,應用程式看到的內容與原本相同。如果應用程式有自己的角色設定,forward auth 不會自動填入,除非應用程式支援以標頭進行驗證,並將標頭對應至帳號。Grafana 可透過其 auth.proxy 設定做到這點。大多數自架應用程式不支援,因此所有通過閘門的人,對應用程式而言都是同一個身分,而該身分通常是管理員。
它也不會保護應用程式自己的 API token。應用程式簽發的個人存取 token 是向應用程式進行驗證,不是向 oauth2-proxy 進行驗證。因此,當閘門置於 API 前方時,該 token 會立即失效。若要恢復使用,便必須排除 API 路徑;但此時該 token 就成為保護這個路徑的唯一機制。你會在同一項服務上執行兩套驗證系統,而 SSO 只涵蓋其中一套。
撤銷權限是第三個缺口。在身分提供者中刪除使用者會阻止新的登入,但 oauth2-proxy 不會向身分提供者檢查現有工作階段,直到 cookie_refresh 到期為止。停用 refresh 時,工作階段 cookie 會持續有效,直到到期;而 cookie_expire 的預設值是 168 小時。這可能讓你剛移除的使用者繼續存取一週。請將 cookie_refresh 設為較短的時間,例如 1 小時。當身分提供者因使用者的 refresh token 已失效而拒絕該次 refresh 時,oauth2-proxy 會清除工作階段,並在下一個嘗試執行 refresh 的請求中強制重新登入。並非所有身分提供者都支援 refresh,因此請針對你的提供者進行測試。
稽核軌跡也只到閘門為止。oauth2-proxy 會記錄誰通過閘門以及通過時間。應用程式只會記錄未命名的工作階段。如果你必須回答誰變更了某項設定,應用程式中的標頭身分是最低要求,而真正的每位使用者帳號才是合理的做法。
支付 SSO 費用是較佳選擇的情況
當應用程式完全沒有登入功能,或所有人共用一組密碼,而你希望在單一位置新增及移除使用者時,forward auth 是合適的工具。設定需要一個下午,並會多增加一個處理程序;只要應用程式支援 HTTP,就能使用。
當同一個應用程式內的不同使用者需要不同權限時,forward auth 就不適合。閘道無法表達「Ana 可以編輯儀表板,而 Bo 只能讀取」。如果廠商提供 SSO 方案,群組對應角色通常才是你真正購買的功能;使用標頭與代理規則自行重建這項功能,比直接付費更容易出錯。決定前,值得先閱讀SSO 方案背後的定價模式。
任何提供行動或桌面用戶端、且用戶端不會攜帶瀏覽器 cookie 的應用程式,都會在每次請求時與這個閘道產生衝突。
FAQ
什麼是 forward auth?
forward auth 是一種架構模式。反向代理會在將每個傳入請求轉送至上游之前,先向獨立的驗證服務查詢。代理會將請求標頭傳送至例如 /oauth2/auth 的端點,並讀取狀態碼。202 表示允許,因此原始請求會繼續傳送至應用程式。401 表示沒有有效的工作階段,因此代理會將瀏覽器重新導向至登入頁面。Nginx 使用 auth_request 指令實作,Traefik 使用 forwardAuth middleware,而 Caddy 使用 forward_auth。
為什麼 oauth2-proxy 會將我重導回登入頁面,形成迴圈?
工作階段 cookie 遺失或驗證失敗,因此每次檢查都找不到有效工作階段,並將你導回登入頁面。使用不同 cookie secret 的執行個體會拒絕彼此的 cookie。另一個原因是,在瀏覽器透過純 HTTP 開啟的網站上設定了 cookie_secure = true;除 localhost 外,瀏覽器不會在 http:// origin 上儲存 Secure cookie。也請檢查 cookie_domains 值是否涵蓋網址列中的主機名稱。在瀏覽器的開發人員工具中,查看 /oauth2/callback 回應上的 Set-Cookie 標頭,以確認哪個 cookie 遺失。如果有回傳 cookie,請檢查伺服器日誌中的驗證錯誤。如果遺失的是 CSRF cookie,你會看到顯示 Login Failed: Unable to find a valid CSRF token. Please try again. 的 403 頁面,而不是形成迴圈;沒有收到任何 cookie 時,日誌會顯示 No cookies were found in OAuth callback.。
如何讓 API client 或 webhook 通過 oauth2-proxy?
使用 skip_auth_routes 搭配錨定的正規表示式,也可以限定為單一 HTTP method,例如 POST=^/webhook/;並執行 v7.15.5 或更新版本,因為該版本修正了這些豁免規則中的重大繞過漏洞。限定 method 的豁免要求驗證請求保留原始 method;Nginx 與 Caddy 範例會執行 GET 檢查,因此請在反向代理的路由中處理這些豁免。如果 API client 已持有由已設定 provider 核發、且 audience 符合要求的有效 JWT,skip_jwt_bearer_tokens = true 會接受這些 token 取代 cookie,並維持該路徑的保護。audience 必須符合 client_id,或符合透過 extra_jwt_issuers 設定的 audience。列在 skip_auth_routes 中的任何項目都不需要驗證,因此每個表示式都應限制在呼叫端所需的最小範圍。
oauth2-proxy 會為應用程式提供每位使用者的權限嗎?
不會。它是存取閘門,不是授權系統。它只決定誰能到達應用程式;除非應用程式讀取 identity header 並將其對應至帳戶,否則所有通過閘門的人對應用程式而言都完全相同。Grafana 可透過其 auth.proxy 設定做到這點。大多數自架應用程式無法做到,因此通過閘門的每個人都共用應用程式執行時使用的單一身分。
使用者可以自行設定 identity header,繞過 oauth2-proxy 嗎?
可以,前提是他們能直接連線至應用程式。身分資訊會以例如 X-Auth-Request-Email 的純文字標頭傳遞,而應用程式會信任收到的內容。任何能連線至應用程式連接埠的人,都能傳送該標頭並冒用任何使用者。請將應用程式繫結至 127.0.0.1,或讓它留在沒有公開連接埠的內部 Docker network 中,並使用 sudo ss -tlnp 確認設定。