oauth2-proxyでログインなしのアプリにSSOを追加する方法
ログイン機能のないアプリをOIDCで保護する方法を解説します。NginxやTraefikへのoauth2-proxy接続、202と401の判定、Cookieとリダイレクトの落とし穴を確認できます。
Forward auth: ログイン機能のないアプリケーションで SSO を実現する方法
oauth2-proxy を使うと、独自のログイン機能を持たないアプリケーションでもシングルサインオンを利用できます。アプリケーションの前段にあるリバースプロキシがすべてのリクエストを停止し、oauth2-proxy に有効なセッションが含まれているかを問い合わせます。応答が肯定の場合だけ、リクエストを上流へ転送します。アプリケーションはこの確認を認識しないため、コードを変更する必要はありません。
確認には、追加の HTTP リクエストを 1 回使用します。プロキシは受信したリクエストヘッダーのコピーを /oauth2/auth に送り、ステータスコードを確認します。202 の場合は確認に成功したため、プロキシは元のリクエストをアプリケーションへ転送します。401 の場合は有効なセッションがないため、プロキシはブラウザーを /oauth2/sign_in へ転送します。/oauth2/sign_in はデフォルトでログインページを表示します。/oauth2/start は ID プロバイダーで OpenID Connect (OIDC) のログインを開始します。skip_provider_button = true を使うと、/oauth2/sign_in が自動的にログインを開始します。OIDC は OAuth 2.0 の上に構築された認証情報レイヤーです。プロバイダーには、すでにログインに使用しているものを指定します。
この方式には、各リバースプロキシで固有の名称があります。Nginx ではディレクティブ auth_request と呼びます。Traefik ではミドルウェア forwardAuth と呼びます。Caddy では forward_auth と表記します。サブリクエストに応答するサービスも交換可能です。oauth2-proxy が一般的に選ばれるのは、標準的な OIDC に対応し、独自のデータベースを必要としないためです。
設定を書く前に信頼境界を定義する
チェックが正常に完了すると、oauth2-proxy はレスポンスヘッダーとして ID を返し、リバースプロキシがそれを upstream へのリクエストにコピーします。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 では、app service の ports: マッピングを削除し、内部ネットワーク上にのみ接続させます。これにより、接続できるのは proxy container だけになります。bare host では、アプリケーションを 0.0.0.0:3000 ではなく 127.0.0.1:3000 に bind します。そのうえで、実際に公開されている内容を確認します。
sudo ss -tlnp | grep 30000.0.0.0:3000 と表示される行がある場合、アプリケーションは public IP で応答しており、認証ゲートは見かけだけのものです。必要なのは 127.0.0.1:3000 です。ファイアウォールルールは有効な追加防御ですが、別のツールによってルールセットが flush された後も有効なのは bind address です。
oauth2-proxy のインストール
2026 年 10 月時点の最新リリースは v7.15.5 で、2026 年 10 月 1 日に公開されています。2 件の重大なセキュリティアドバイザリに対応しており、そのうち 1 件は v7.5.0 より後のすべてのリリースに影響する skip_auth_routes のバイパスです。そのため、これより古いバージョンはインストールしないでください。バイナリをインストールし、ダウンロードを検証します。
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 が暗号鍵です。暗号鍵は AES (advanced encryption standard) の鍵として使用されるため、長さを 16、24、または 32 bytes のいずれかにする必要があります。oauth2-proxy は、デコード後の長さがこれらのいずれかになる URL-safe base64 値、またはこれらの長さの raw secret を受け付けます。それ以外の場合は起動せず、cookie secret に関する起動エラーを出力します。以下のコマンドは、32-byte の鍵をエンコードした 44 文字の値を生成します。
openssl rand -base64 32 | tr -- '+/' '-_'tr は見た目を整えるためのものではありません。standard base64 を、oauth2-proxy が secret のデコード時に使用する URL-safe alphabet に変換します。
この値には 2 つのルールがあります。デプロイメントごとに異なる secret を使用してください。また、同じドメインの背後で複数の oauth2-proxy インスタンスを実行する場合は、すべてに同じ secret を設定してください。あるインスタンスが暗号化した Cookie を、他のインスタンスが読み取る必要があるためです。
oauth2-proxy の設定を記述する
長いコマンドラインではなくファイルに設定を保存します。これにより、クライアントシークレットが 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 に対して、前段のプロキシから渡される X-Forwarded-* ヘッダーを信頼するよう指示します。これを設定しない場合、oauth2-proxy はプロキシ自身のアドレスをクライアントアドレスとして扱います。そのため、リクエストが HTTPS 経由で到達したかどうかを誤って判定することがあります。
trusted_proxy_ips は、これらのヘッダーを送信できる接続元を制限します。デフォルトではすべての接続元を信頼します。この構成で安全なのは、http_address によって oauth2-proxy が 127.0.0.1 上だけで待ち受ける場合に限られます。oauth2-proxy が Docker ネットワーク上で待ち受ける場合は、リバースプロキシのアドレスを指定します。
upstreams = ["static://202"] を設定すると、oauth2-proxy は認証済みリクエストに対して 202 を返し、プロキシ処理を行いません。リバースプロキシがプロキシ処理を担当するため、これは forward auth に適した動作です。もう 1 つの構成では、upstreams = ["http://127.0.0.1:3000"] を使って oauth2-proxy をリクエスト経路に直接配置し、auth_request は一切使用しません。単一のアプリにはこちらのほうが簡単ですが、10 個のアプリには対応できません。
email_domains = ["*"] は、プロバイダーが認証を許可するすべてのアドレスを受け入れます。自分のドメインだけに絞り込みます。より適切なのは、プロバイダーでグループバインディングを設定してアクセスを制限する方法です。ユーザー管理はすでにプロバイダーで行っているためです。
専用ユーザーで 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 自身のヘルスエンドポイントであり、セッションを要求しません。何も応答しない場合は journalctl -u oauth2-proxy -n 50 を確認します。issuer URL の誤りと長さが正しくない cookie secret は、どちらも起動時に失敗し、その旨をログに出力します。
プロバイダーにリダイレクト URI を登録する
プロバイダーで OIDC アプリケーションを作成し、リダイレクト URI を設定ファイルの redirect_url と完全に一致させます: https://app.example.com/oauth2/callback。完全な一致とは、スキーム、ホスト、ポート、パスのすべてが 1 文字単位で一致することです。末尾のスラッシュがあると、別の URI になります。
これは構成全体で最も多い失敗であり、oauth2-proxy が関与する前に発生します。プロバイダーが認可リクエストを拒否して独自のエラーページを表示するため、oauth2-proxy のログには何も記録されません。確認の手掛かりはアドレスバーです。ブラウザーがまだプロバイダーのドメイン上にあり、クエリ文字列に error=invalid_request が含まれているか、ページに redirect_uri が直接表示されています。その場合は、proxy の設定ではなく、プロバイダーのアプリケーション登録を修正します。
issuer URL は手入力せず、プロバイダーからコピーします。oauth2-proxy は oidc_issuer_url に /.well-known/openid-configuration を追加し、起動時にその discovery ドキュメントを取得します。まず自分で確認します。
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400authorization_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 つあります。空の Content-Length を指定した proxy_pass_request_body off により、nginx がリクエストボディを認証エンドポイントへ転送しなくなります。認証エンドポイントが必要とするのはヘッダーだけです。
auth_request_set $auth_cookie と add_header Set-Cookie の組み合わせにより、更新されたセッション Cookie がブラウザーへ返されます。これを省略すると、nginx はサブリクエストの Set-Cookie を破棄するため、cookie_refresh は何もせずに終了します。ブラウザーはセッションの有効期限が切れるまで古い値を保持します。この組み合わせで処理できる Cookie は 1 つです。セッション Cookie を分割している場合は、残りの部分に対する追加処理が必要です。または、Redis にセッションを保存します。
error_page 401 = @oauth2_signin によって、認証チェックの失敗をログイン処理に変換します。これがないと、未認証の訪問者には単純な 401 Authorization Required ページだけが表示され、先へ進む手段がありません。
必ず、再読み込みの前にテストします。
sudo nginx -t && sudo systemctl reload nginx周囲のディレクティブに不慣れな場合は、nginx リバースプロキシ設定の構成要素で、この設定の下位レイヤーを確認できます。
Traefik: forwardAuth middleware
Traefik では、同じ処理に2つの middleware が必要です。1つはチェックを実行します。もう1つは、チェックに失敗したときにログインページを返します。
# 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 に設定し、その 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 ドキュメントでは非推奨です。そのホストも対象に含めるよう whitelist_domains を設定してください。設定しない場合、oauth2-proxy はオープンリダイレクトのリスクがあるとして rd パラメーターを破棄し、ログイン後に全員が / に移動します。通常、Traefik を実行するホストは複数のアプリの前段に置かれます。複数の Docker Compose アプリを1つの Traefik インスタンス経由でルーティングするでは、この構成に組み込む 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 によって ID が upstream リクエストに引き継がれます。ただし、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 を使用していることを確認します。
失われた Cookie が、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 は cross-site request forgery を意味します。この Cookie は、callback を開始元のログインと関連付けるために存在します。ブラウザーには、次の内容を含む 403 error page が表示されます。
Login Failed: Unable to find a valid CSRF token. Please try again.Cookie が見つからない場合は、以下の最初の 3 つの原因が共通しています。検証失敗の別の原因として、clock drift もあります。次の 4 項目を順番に確認します。
- ブラウザーが plain HTTP でサイトにアクセスしているのに
cookie_secure = trueが設定されている。localhost を除き、ブラウザーはhttp://origin のSecureCookie を保存しないため、Cookie が送り返されません。TLS (transport layer security) を正しく終端するか、localhost でのテスト時だけcookie_secure = falseを設定します。 - アドレスバーの hostname を対象範囲に含まない
cookie_domainsの値。.example.comはapp.example.comを対象にしますが、app.example.netにはまったく作用しません。 - ブラウザーが Cookie を破棄している。厳格なプライバシー拡張機能や third-party cookie のブロックにより、送信側のリダイレクトから callback までの間に
_oauth2_proxy_csrfが削除されることがあります。その後、session cookie が削除される場合もあります。 - Clock drift。サーバーの時計がプロバイダーより大幅に進んでいると、ID token が期限切れと判定され、検証に失敗することがあります。
timedatectlにはSystem clock synchronized: yesが表示されるはずです。
設定に問題がなくても、CSRF エラーが発生する原因がもう 1 つあります。oauth2-proxy はデフォルトで 1 つの CSRF Cookie を保持するため、2 つのタブが同時にログインを開始すると、互いの Cookie を上書きします。cookie_csrf_per_request = true を使用すると、ログインごとに専用の Cookie が割り当てられます。
推測せず、サーバー側から発生状況を確認します。
sudo journalctl -u oauth2-proxy -fプライベートウィンドウでアプリを開きます。すべてのリクエストが status とともに記録されるため、callback の直後に再びログインへリダイレクトされていれば、それがログですぐに確認できるループです。
ログインをスキップする必要があるパス: API、webhook、websocket
Forward auth は、ブラウザーが cookie を保持していることを前提とします。ブラウザーを使わない呼び出し元では問題が発生します。
Authorization: Bearer <token> を送信する API クライアントには cookie がありません。そのため、bearer-token 認証を有効にしない限り、上記のプロキシ設定では oauth2-proxy のログインページに転送されます。対処方法は 2 つあります。skip_jwt_bearer_tokens = true を設定すると、oauth2-proxy は、設定した issuer が発行し、このクライアントで受け入れられる audience を持つ有効な JWT (JSON web token) bearer token を受け付けます。API クライアントがプロバイダーから適切な token をすでに取得している場合に適しています。token の aud は client_id、または extra_jwt_issuers で設定した audience と一致する必要があります。それ以外の場合は、そのパスを除外します。
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]各値は、クエリパラメーターを除いたデコード済みのパスに対して照合する正規表現です。HTTP メソッドと = を先頭に付けることもできます。POST=^/webhook/ により、webhook receiver は POST を受け付けたままにできます。一方、認証リクエストで元のメソッドが維持される場合、同じパスへブラウザーからアクセスしたユーザーにはログインが要求されます。Nginx auth_request と Caddy forward_auth は GET のチェックを行うため、これらの構成でメソッド固有の除外を使うには、reverse proxy 側で別の routing が必要です。各エントリは認証ゲートの穴になります。そのため、正規表現を ^ でアンカーし、呼び出し元が許容する範囲でできるだけ限定してください。
これらに依存する前に、v7.15.5 以降を使用してください。v7.5.0 より後の以前の release では、dot segment、先頭スラッシュの二重化、または semicolon を含むリクエストによって、保護されたパスを誤って除外させられる可能性がありました (advisory GHSA-63jm-59jj-478j)。正規表現をアンカーしても防げませんでした。修正済みの release では、このような曖昧なパスの除外を拒否します。アップグレード後に公開 route が引き続き一致することを確認してください。
Websocket は、誤解されやすいケースです。upgrade リクエストは、他のリクエストと同じ cookie を含む通常の HTTP GET です。そのため、通常どおりチェックを通過し、除外は必要ありません。問題になるのは、その前後の proxy 処理です。保護対象の location に Upgrade と Connection の header がない場合、upgrade は完了しません。アプリのクライアントは、ブラウザーの console に WebSocket connection ... failed メッセージを表示して再試行し続けます。この場合、パスを除外しても解決しません。リクエストはすでに認証済みだからです。
実際の制限も 1 つあります。チェックは upgrade 時に 1 回だけ実行されます。数時間開いたままの websocket は再チェックされません。そのため、プロバイダーでユーザーを削除しても、そのユーザーがすでに保持している socket は閉じません。接続中のセッションを切断するには、アプリを再起動してください。
セッションストレージと、大きくなりすぎるCookie
デフォルトでは、セッション全体がcookie_secretで暗号化され、Cookie内に保存されます。これにより、oauth2-proxyはステートレスに動作し、追加のサービスも必要ありません。ただし、ブラウザーがCookieのサイズを約4 KBに制限するため、上限があります。ID tokenに多数のgroup claimが含まれている場合、oauth2-proxyはセッションを_oauth2_proxy_0、_oauth2_proxy_1以降に分割します。分割数が数個を超えると、リクエストヘッダーが大きくなり、アプリがリクエストを受け取る前にnginxが400 Request Header Or Cookie Too Largeを返すことがあります。
この場合は、セッションをサーバー側に移します。
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"ブラウザーが保持するのは短いチケットになり、暗号化されたセッションはRedisに保存されます。その代わり、Redisを稼働させ続ける必要があります。Redisが停止すると、oauth2-proxyはセッションを読み込めません。保存されたセッションデータを失うと、全員が再度ログインする必要があります。Cookie storeにも固有の問題があります。同じセッションを更新する2つのリクエストが同時に発生すると競合し、再ログインが必要になることがあります。
Forward auth で得られないもの
これは入口のゲートです。アプリケーション内部の認可ではありません。この違いによって、この方式が適しているかどうかが決まります。
ユーザーが通過すると、アプリケーションから見える情報は従来と変わりません。アプリに独自のロールがあっても、forward auth がそれを設定するわけではありません。ただし、アプリがヘッダーベースの認証に対応し、ヘッダーをアカウントにマッピングする場合は例外です。Grafana は auth.proxy 設定を通じてこれに対応しています。ほとんどの self-hosted アプリは対応していないため、ゲートを通過したユーザーは全員、アプリケーションからは同じ単一の ID として扱われます。その ID は admin であることがよくあります。
アプリケーション独自の API トークンも保護されません。アプリが発行した personal access token は oauth2-proxy ではなくアプリケーションに対して認証するため、ゲートを前段に置いた時点でそのトークンは機能しなくなります。API パスを除外してトークンを再び使えるようにすると、そのパスを守るものはトークンだけになります。1 つのサービス上で 2 つの認証システムを運用することになり、SSO が適用されるのはそのうち 1 つだけです。
3 つ目の不足は、失効処理です。プロバイダーでユーザーを削除すると新しいログインは停止しますが、oauth2-proxy は cookie_refresh の期限が来るまで、既存のセッションをプロバイダーに照会しません。refresh を無効にすると、セッション Cookie は有効期限まで残ります。cookie_expire のデフォルトは 168 hours なので、削除したユーザーがさらに 1 週間アクセスできる場合があります。cookie_refresh は 1 hour など、短い値に設定してください。ユーザーの refresh token が無効になったためにプロバイダーが refresh を拒否すると、oauth2-proxy はセッションを削除し、refresh を試みる次のリクエストで新しいログインを要求します。すべてのプロバイダーが refresh に対応しているわけではないため、使用するプロバイダーでテストしてください。
監査証跡もゲートで止まります。oauth2-proxy は誰がいつ通過したかをログに記録します。一方、アプリケーションには名前のないセッションが記録されます。誰が設定を変更したかを確認する必要がある場合、アプリケーションでヘッダーの ID を扱うことが最低限必要です。ユーザーごとの実アカウントを用意することが、正しい対応です。
SSO のコストを負担する方が適切な場合
アプリにログイン機能がまったくない場合や、共有パスワードしかない場合に、利用者の追加と削除を一元管理したいなら、Forward auth が適しています。導入には半日と追加のプロセス 1 つが必要ですが、HTTP に対応するアプリであれば利用できます。
同じアプリ内で利用者ごとに異なる権限が必要な場合、Forward auth は適していません。ゲートウェイだけでは、「Ana はダッシュボードを編集でき、Bo は閲覧だけできる」という権限を表現できないためです。ベンダーが SSO プランを提供している場合、実際に購入しているのは通常、グループからロールへのマッピングです。これをヘッダーとプロキシルールで再構築するより、料金を支払う方が堅牢です。どちらを選ぶか決める前に、SSO プランの背後にある料金体系を確認してください。
ブラウザー Cookie を保持しないモバイルまたはデスクトップクライアントを備えたアプリでは、すべてのリクエストでゲートウェイとの競合が発生します。
FAQ
フォワード認証とは何ですか?
フォワード認証は、リバースプロキシが受信した各リクエストを上流へ転送する前に、別の認証サービスへ確認する方式です。プロキシはリクエストヘッダーを /oauth2/auth などのエンドポイントへ送信し、ステータスコードを確認します。202 は許可を示すため、元のリクエストはアプリケーションへ到達します。401 は有効なセッションがないことを示すため、プロキシはブラウザーをログイン画面へリダイレクトします。Nginx では auth_request ディレクティブ、Traefik では forwardAuth ミドルウェア、Caddy では forward_auth を使って実装します。
oauth2-proxy がログインページへ何度もリダイレクトするのはなぜですか?
セッション Cookie が存在しないか、検証に失敗しています。そのため、すべての確認で有効なセッションがないと判定され、ログイン画面へ戻されます。異なる Cookie secret を使うインスタンス同士では、相手が発行した Cookie が拒否されます。別の原因として、ブラウザーが平文 HTTP でアクセスしたサイトに cookie_secure = true が設定されている場合があります。localhost 以外では、ブラウザーは http:// オリジン上の 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 が1つも届いていない場合、ログには No cookies were found in OAuth callback. と記録されます。
API クライアントや webhook を oauth2-proxy 経由で通すにはどうすればよいですか?
skip_auth_routes を、アンカー付きの正規表現とともに使用します。必要に応じて1つの HTTP メソッドに限定できます。例: POST=^/webhook/。また、これらの例外処理に存在した重大なバイパスを修正した v7.15.5 以降を使用してください。メソッド単位の例外には、認証リクエストが元のメソッドを保持する必要があります。nginx と Caddy の例では GET の確認を行うため、これらの例外はリバースプロキシのルーティングで処理してください。API クライアントが、設定済みプロバイダーによって発行された有効な JWT をすでに保持しており、audience も受け入れ可能であれば、skip_jwt_bearer_tokens = true は Cookie の代わりにそのトークンを受け付け、パスの保護を維持します。audience は client_id と一致するか、extra_jwt_issuers で設定した audience と一致する必要があります。skip_auth_routes に列挙した対象はすべて認証なしでアクセスできるため、各式は呼び出し元が必要とする範囲に限定してください。
oauth2-proxy はアプリケーションにユーザー単位の権限を渡しますか?
いいえ。oauth2-proxy は認証ゲートであり、認可システムではありません。誰がアプリケーションへ到達できるかを決めますが、到達したユーザーは、アプリケーションが identity header を読み取ってアカウントへ割り当てない限り、アプリケーションからは同じように見えます。Grafana では auth.proxy の設定によってこれを実行できます。ほとんどの self-hosted アプリケーションは対応していないため、ゲートを通過した全員が、アプリケーションの実行に使われている単一の identity を共有します。
identity header を自分で設定すると、oauth2-proxy をバイパスできますか?
はい。アプリケーションへ直接到達できる場合は可能です。identity は X-Auth-Request-Email のような平文のヘッダーで渡され、アプリケーションは受け取った値をそのまま信頼します。アプリケーションのポートへ接続できる人は誰でも、そのヘッダーを送信して任意のユーザーになりすませます。アプリケーションを 127.0.0.1 に bind するか、公開ポートのない内部 Docker ネットワーク上で実行し、sudo ss -tlnp で確認してください。