oauth2-proxy 前向认证:为任意应用接入 SSO
使用 oauth2-proxy 和 OIDC 为无登录功能的应用接入 SSO,配置 Nginx 或 Traefik 前向认证,并避开 Cookie、重定向及直接暴露端口的常见陷阱。
转发认证:如何为无登录功能的应用程序实现 SSO
oauth2-proxy 可为自身不具备登录功能的应用程序提供单点登录(SSO)。其原理在于:位于应用程序前端的反向代理会拦截所有请求,向 oauth2-proxy 询问该请求是否携带有效会话;只有在得到肯定答复后,代理才会将请求转发至后端。由于应用程序感知不到该检查过程,因此无需修改任何代码。
该检查仅涉及一次额外的 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 将其称为 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,于 2026 年 10 月 1 日发布。该版本修复了 2 个严重安全公告,其中一个是可绕过 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 密钥
会话 Cookie 经过加密,而 cookie_secret 即为加密密钥。该密钥长度必须精确为 16、24 或 32 字节,因为它将作为 AES(高级加密标准)密钥使用。oauth2-proxy 接受一个解码后符合上述长度的 URL 安全 base64 字符串,或直接使用该长度的原始密钥;否则程序将拒绝启动,并在启动错误中指出 Cookie 密钥问题。以下命令可生成一个 44 字符的值,对应 32 字节的密钥。
openssl rand -base64 32 | tr -- '+/' '-_'tr 的作用并非修饰。它将标准 base64 转换为 oauth2-proxy 解码密钥时所使用的 URL 安全字符集。
此值需遵循两条规则。每个部署环境必须使用不同的密钥。若在同一域名下运行多个 oauth2-proxy 实例,则必须为它们配置相同的密钥,因为由一个实例加密的 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 所需的行为,因为代理工作由反向代理完成。另一种部署方式是使用 upstreams = ["http://127.0.0.1:3000"],让 oauth2-proxy 直接位于请求路径中,并且完全不使用 auth_request。这种方式适合单个应用,但无法扩展到 ten 个应用。
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。完全一致意味着协议、主机、端口和路径必须逐字符匹配。末尾的斜杠会使其成为不同的 URI。
这是整个配置过程中最常见的故障点,且故障发生在 oauth2-proxy 介入之前。身份提供商会拒绝授权请求并显示其自身的错误页面,因此 oauth2-proxy 日志中不会有任何记录。判断依据是地址栏:浏览器仍停留在身份提供商的域名下,且查询字符串中直接带有 error=invalid_request 或页面名称 redirect_uri。出现此情况时,请修改身份提供商处的应用记录,而非代理配置。
请直接从身份提供商处复制颁发者 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;
}
}其中有三个细节至关重要。使用空的 Content-Length 配置 proxy_pass_request_body off,可以防止 Nginx 将请求体转发至认证端点,因为该端点仅需读取请求头。
auth_request_set $auth_cookie 和 add_header Set-Cookie 这对指令用于将刷新后的会话 Cookie 返回给浏览器。若不配置此项,cookie_refresh 将不会执行任何操作,因为 Nginx 会丢弃子请求的 Set-Cookie,导致浏览器在会话过期前始终保留旧值。此配置仅处理单个 Cookie;若涉及拆分式会话 Cookie,则需针对其他部分进行额外处理,或使用 Redis 进行会话存储。
error_page 401 = @oauth2_signin 指令负责将认证失败的请求重定向至登录页面。若缺少此项,未认证的访问者将仅看到一个空白的 401 Authorization Required 页面,且无法进行后续操作。
在重载配置前,务必执行测试:
sudo nginx -t && sudo systemctl reload nginx若您对相关的指令尚不熟悉,Nginx 反向代理配置结构解析 一文涵盖了此层级之下的基础知识。
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}"将这两个中间件附加到前端应用路由上,并确保 oauth-errors 位于 oauth-auth 之前。同时,将 oauth2-proxy 发布在独立的路由 oauth.example.com 上,因为浏览器必须在不经过检查的情况下访问 /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}。若不进行此重写,Traefik 会返回带有 401 状态码的自动重定向,而浏览器不会自动跳转。仅靠重写无法启动登录流程。
trustForwardHeader: true 会信任传入的 X-Forwarded-* 标头;Traefik 会将原始主机和 URI 提供给 oauth2-proxy。该选项在当前的 Traefik 文档中已被弃用。请将 whitelist_domains 设置为同时涵盖该主机,否则 oauth2-proxy 会因开放重定向风险而丢弃 rd 参数,导致用户在登录后跳转至 /。Traefik 服务器通常同时代理多个应用,通过一个 Traefik 实例路由多个 Docker Compose 应用 展示了此配置所嵌入的路由布局。
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 响应头。如果某个 Cookie 在此处已设置,但在后续请求中丢失,说明该 Cookie 被浏览器拒绝了。如果 Cookie 存在,请检查服务器日志中是否有类似 cookie signature not valid 的验证错误,并确认所有实例使用了相同的 secret。
当丢失的是 oauth2-proxy 在发出请求时设置的 CSRF Cookie 时,流程不会循环,而是会停在回调阶段,日志会指出具体原因:
No cookies were found in OAuth callback.或者,当其他 Cookie 成功送达但正确的 Cookie 未送达时:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF 指跨站请求伪造,该 Cookie 的存在是为了将回调与发起登录的请求关联起来。浏览器会收到一个 403 错误页面,内容如下:
Login Failed: Unable to find a valid CSRF token. Please try again.Cookie 丢失通常由以下前三个原因导致;时钟偏差是导致验证失败的另一个原因。请按顺序检查这四项。
cookie_secure = true:浏览器通过普通 HTTP 访问站点。除 localhost 外,浏览器不会存储标记为Secure的 Cookie(如果源是http://),因此它永远不会被发送回服务器。请正确配置 TLS (传输层安全) 终止,或者仅在 localhost 测试时设置cookie_secure = false。cookie_domains值未覆盖地址栏中的主机名。.example.com仅覆盖app.example.com,对app.example.net不起任何作用。- 浏览器丢弃了 Cookie。严格的隐私插件或第三方 Cookie 拦截功能可能会在出站重定向和回调之间移除
_oauth2_proxy_csrf,或者在之后移除会话 Cookie。 - 时钟偏差。如果服务器时钟比身份提供商的时钟快很多,ID token 可能会显示为已过期并导致验证失败。
timedatectl应当会报告System clock synchronized: yes。
还有一个原因会导致 CSRF 错误,且并非配置错误。默认情况下,oauth2-proxy 仅保留一个 CSRF Cookie,因此同时在两个标签页发起登录会导致它们相互覆盖。cookie_csrf_per_request = true 可以为每次登录分配独立的 Cookie。
与其猜测,不如从服务端监控这一过程:
sudo journalctl -u oauth2-proxy -f在隐私窗口中加载应用。每个请求及其状态都会被记录,因此如果回调后紧接着又重定向到登录页,日志中就会记录下该循环。
必须跳过登录的路径:API、Webhook 和 Websocket
转发认证(Forward auth)假设浏览器中存有 Cookie。没有浏览器的调用方会因此中断。
发送 Authorization: Bearer <token> 的 API 客户端没有 Cookie,因此上述代理配置会将其重定向到 oauth2-proxy 的登录页面,除非启用了 Bearer Token 认证。有两种简洁的解决方案。设置 skip_jwt_bearer_tokens = true 可使 oauth2-proxy 接受来自已配置颁发者且受该客户端信任的有效 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 接收端通过 POST 请求访问,同时人类用户在浏览同一路径时仍会触发登录,前提是认证请求保留了原始方法。Nginx auth_request 和 Caddy forward_auth 执行的是 GET 检查,因此在这些设置中,针对特定方法的豁免需要在反向代理层进行单独路由。每一项豁免都是安全防线上的一个缺口,因此请使用 ^ 锚定表达式,并尽可能缩小其匹配范围。
在依赖这些功能前,请确保运行 v7.15.5 或更高版本。v7.5.0 之后的早期版本可能被包含点段(dot segments)、双斜杠或分号的请求欺骗,从而豁免受保护的路径(安全公告 GHSA-63jm-59jj-478j),且锚定表达式无法防止此类攻击。修复后的版本会拒绝豁免此类歧义路径,因此升级后请检查您的公共路由是否仍能正常匹配。
Websocket 是最容易出错的情况。升级请求是一个普通的 HTTP GET 请求,携带与其他请求相同的 Cookie,因此它能正常通过检查,无需豁免。真正的问题在于代理配置。如果受保护的 location 缺少 Upgrade 和 Connection 请求头,升级将无法完成,应用客户端会不断重试,并在浏览器控制台中显示 WebSocket connection ... failed 错误。此时豁免路径无效,因为请求本身已经过认证。
确实存在一个限制。检查仅在升级时运行一次。保持连接数小时的 Websocket 不会再次检查,因此在提供商处删除用户并不会关闭其已持有的连接。请重启应用以切断实时连接。
会话存储与过大的 Cookie
默认情况下,整个会话存储在 Cookie 中,并使用 cookie_secret 进行加密。这使 oauth2-proxy 保持无状态,无需额外服务。但它存在上限,因为浏览器将 Cookie 大小限制在 4 KB 左右。当 ID 令牌包含大量组声明时,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 宕机,oauth2-proxy 将无法加载会话;丢失存储的会话数据会强制所有用户重新登录。Cookie 存储方式也有其代价,即两个请求在同一时刻刷新同一个会话时可能会发生冲突,从而强制用户重新登录。
前向认证无法提供的功能
这只是门口的守卫。它并非应用内部的授权机制,这种区别决定了该方案是否适用于您的场景。
一旦用户通过验证,应用看到的仍是它原本看到的内容。如果应用有自己的角色体系,前向认证无法自动填充这些角色,除非应用支持基于请求头的认证并将请求头映射到账户。Grafana 通过其 auth.proxy 设置可以实现这一点。大多数自托管应用不支持此功能,因此所有通过网关的用户在应用看来都是同一个身份,且该身份通常是管理员。
它也无法保护应用自身的 API 令牌。应用签发的个人访问令牌是针对应用本身的认证,而非针对 oauth2-proxy,因此一旦在应用前部署网关,该令牌就会失效。若要恢复其功能,需将 API 路径排除在认证之外,但这样一来,该令牌就成了保护该路径的唯一防线。此时您在同一个服务上运行了两套认证系统,且 SSO 仅覆盖其中之一。
撤销权限是第三个缺口。在身份提供商中删除用户会阻止新的登录,但 oauth2-proxy 直到 cookie_refresh 到期前都不会向提供商校验现有会话。如果关闭了刷新功能,会话 Cookie 将保持有效直到过期,而 cookie_expire 的默认值为 168 小时,这意味着您刚移除的用户可能仍有一周的访问权限。请将 cookie_refresh 设置为一个较短的时间,例如一小时。当提供商因为用户的刷新令牌不再有效而拒绝刷新请求时,oauth2-proxy 会清除会话,并在下一次尝试刷新时强制用户重新登录。并非所有提供商都支持刷新功能,请务必针对您的提供商进行测试。
审计追踪也止步于网关。oauth2-proxy 会记录谁在何时通过了验证,但应用记录的却是一个未命名的会话。如果您需要追溯是谁更改了设置,应用内的请求头身份标识是最低要求,而真正的用户级账户才是最可靠的方案。
何时支付 SSO 费用是更好的选择
当应用完全没有登录功能,或者仅使用共享密码,且你需要一个统一的入口来管理用户增删时,转发认证(Forward auth)是合适的工具。这只需花费一个下午的时间并增加一个进程,且适用于任何支持 HTTP 的应用。
当同一应用内的不同用户需要不同权限时,该方案并不适用。网关无法实现“Ana 可以编辑仪表板,而 Bo 只能查看”这类逻辑。如果供应商提供了 SSO 版本,你实际购买的通常是“组到角色”的映射功能;通过请求头和代理规则去重建该功能,其脆弱性远高于直接付费。在做出决定前,建议阅读 这些 SSO 版本的定价模式。
任何不携带浏览器 Cookie 的移动端或桌面端应用,在每次请求时都会与网关产生冲突。
FAQ
什么是前向认证 (forward auth)?
前向认证是一种模式:反向代理在将请求转发给后端应用前,会先向独立的认证服务查询每个传入请求。代理将请求头发送至类似 /oauth2/auth 的端点并读取状态码。202 表示允许,原始请求将继续发送至应用。401 表示会话无效,代理会将浏览器重定向至登录页面。Nginx 通过 auth_request 指令实现该功能,Traefik 使用 forwardAuth 中间件,Caddy 则使用 forward_auth。
为什么 oauth2-proxy 会让我陷入登录页面的重定向循环?
会话 Cookie 缺失或验证失败,导致每次检查都无法找到有效会话,从而将你送回登录页。使用不同 Cookie 密钥的实例会拒绝彼此的 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,日志会显示 No cookies were found in OAuth callback.。
如何让 API 客户端或 Webhook 通过 oauth2-proxy?
使用带有锚定正则表达式的 skip_auth_routes,并可选择限定 HTTP 方法(例如 POST=^/webhook/)。请确保运行 v7.15.5 或更高版本,该版本修复了一个针对这些豁免项的关键绕过漏洞。特定方法的豁免要求认证请求保留原始方法;Nginx 和 Caddy 的示例执行的是 GET 检查,因此请在反向代理的路由中处理这些豁免。如果你的 API 客户端已持有由配置的提供商签发且受信任的 JWT,skip_jwt_bearer_tokens = true 可以接受这些令牌以替代 Cookie,并保持路径受保护。受众 (audience) 必须匹配 client_id 或通过 extra_jwt_issuers 配置的受众。skip_auth_routes 中列出的任何内容对所有人均不进行认证,因此请确保每个表达式的范围尽可能窄。
oauth2-proxy 能否为应用提供用户级权限?
不能。它是一个网关,而非授权系统。它决定谁能访问应用,但除非应用读取身份头并将其映射到账户,否则所有通过网关的用户在应用看来都是相同的。Grafana 可以通过其 auth.proxy 设置实现此功能。大多数自托管应用无法做到这一点,因此所有通过网关的人员都共享应用运行所使用的单一身份。
有人可以通过自行设置身份头来绕过 oauth2-proxy 吗?
可以,如果他们能直接访问应用。身份信息以类似 X-Auth-Request-Email 的明文请求头形式到达,应用会信任它收到的任何内容。任何能连接到应用端口的人都可以发送该请求头并伪装成任意用户。请将应用绑定到 127.0.0.1,或将其保留在没有发布端口的内部 Docker 网络中,并使用 sudo ss -tlnp 进行确认。