IAM 网关 oauth2-proxy 深度介绍 | IDaaS Book

什么是 oauth2-proxy？#

oauth2-proxy 是一个开源的、轻量级的身份感知反向代理。它的工作很简单：拦在应用前面，检查每个 HTTP 请求是否带着有效会话；没有的话，把用户导向 OAuth2/OIDC Provider（比如 Keycloak、GitHub、Google、Dex）去登录，登录成功后再放行。

它不存储用户、不管理密码、不签发 Token——这些都是 Provider 的事。oauth2-proxy 只做一件事：把没有身份的人挡在门外，把有身份的人放进来，并把用户信息（邮箱、用户名、组）通过 HTTP Header 传给后端应用。

为什么需要它？#

在 IDaaS 体系里，认证和授权是 IDP 的事，但你的应用可能根本没写登录逻辑。oauth2-proxy 的价值在于：

• 零代码改造：给老应用、静态站点、容器化服务加 OIDC 登录，不用改一行业务代码。
• 入口层统一：Ingress/反向代理层统一拦截，不用每个服务自己实现 OAuth 回调、Token 刷新、Session 管理。
• Provider 无关：同一个 oauth2-proxy 可以对接 Keycloak、Azure AD、GitHub、Google、Dex 等几十种 Provider，切换 Provider 不影响后端。

边界同样要说清楚：认证通过只代表「允许进门」，不代表后端要求的角色、scope、资源权限已经验证（pass_access_token 默认关闭，见下文）。应用若自带 OIDC 客户端且有自己的授权模型，就该直连 IdP，而不是在它前面再叠一层代理——例如 MinIO 的控制台从 ID token 的 policy claim 里读策略名，多前置一个认证代理只会多出两套会话和两个回调地址，排错成本远高于收益，见 MinIO 接入 Keycloak OIDC：IAM 策略映射与 SSO 排错。

架构概览#

  sequenceDiagram
    participant Browser as 浏览器
    participant Ingress as Nginx Ingress/Traefik
    participant O2P as oauth2-proxy
    participant App as 后端应用
    participant IDP as Keycloak (IDP)

    Browser->>Ingress: GET /app
    Ingress->>O2P: GET /oauth2/auth (auth_request)
    
    alt 无有效 Session Cookie
        O2P-->>Ingress: 401 → /oauth2/start
        Ingress-->>Browser: 302 /oauth2/start
        Browser->>O2P: GET /oauth2/start
        O2P-->>Browser: 302 → IDP 登录页
        Browser->>IDP: 登录
        IDP-->>Browser: 302 /oauth2/callback?code=...
        Browser->>O2P: GET /oauth2/callback
        O2P->>IDP: 用 code 换 token
        IDP-->>O2P: access_token + id_token
        O2P-->>Browser: Set-Cookie + 302 回到 /app
        Browser->>Ingress: GET /app (带 Cookie)
        Ingress->>O2P: GET /oauth2/auth (auth_request)
    end

    O2P-->>Ingress: 202 Accepted
    Note over O2P,Ingress: X-Auth-Request-User<br/>X-Auth-Request-Email<br/>X-Auth-Request-Groups
    Ingress->>App: GET /app + 用户身份 Header
    App-->>Browser: 200 OK

流程要点：

1. 所有请求先经过 oauth2-proxy 的 /oauth2/auth 端点校验 Session Cookie。
2. 没有有效 Cookie → 302 跳 /oauth2/start → 302 跳 IDP 登录页。
3. 登录成功后回到 /oauth2/callback，oauth2-proxy 用授权码换 Token，写入 Session Cookie。
4. 后续请求携带 Cookie，oauth2-proxy 校验通过后返回 202，并在响应头中注入 X-Auth-Request-User、X-Auth-Request-Email、X-Auth-Request-Groups 等身份信息。
5. Nginx Ingress（通过 auth_request）或 Traefik（通过 ForwardAuth）透传这些响应头到后端。

认证响应头不是自动传到业务后端的#

这是 auth-url 集成里最容易被误判的边界：--set-xauthrequest=true 只让 oauth2-proxy 在 /oauth2/auth 的响应中生成 X-Auth-Request-*；它不会替业务 Ingress 把 Header 复制到最终请求。以 ingress-nginx 为例，必须同时配置认证 URL、401 跳转和允许复制的响应头：

metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-url: "https://$host/oauth2/auth"
    nginx.ingress.kubernetes.io/auth-signin: "https://$host/oauth2/start?rd=$escaped_request_uri"
    nginx.ingress.kubernetes.io/auth-response-headers: >-
      X-Auth-Request-User,X-Auth-Request-Email,X-Auth-Request-Groups

只列出后端确实需要的 Header。X-Auth-Request-* 不是客户端可自行声明的身份凭证：入口必须覆盖或清理客户端同名 Header，后端 Service 也应只允许来自入口的流量，否则用户可以直接伪造 X-Auth-Request-Groups。如果后端要验证 OAuth access token，另行开启 --pass-access-token=true 并透传 X-Auth-Request-Access-Token；不要把 --pass-authorization-header 产生的 ID Token 当成资源服务器的 access token。

验证时分两段看，避免把“认证成功”误认为“身份已到达业务：

# 认证代理：确认生成认证响应头的开关
kubectl get deploy -n auth oauth2-proxy -o jsonpath='{.spec.template.spec.containers[0].args}' \
  | jq -r '.[]' | grep -E 'set-xauthrequest|pass-access-token|pass-authorization-header'

# 入口：确认 auth-url、跳转和响应头复制均存在
kubectl get ingress -n app internal-app -o yaml \
  | grep -E 'auth-url|auth-signin|auth-response-headers'

依据： oauth2-proxy Header Options 和 ingress-nginx 外部认证示例。

这套注解来自 ingress-nginx，而该控制器已于 2026 年 3 月退役、仓库归档、不再有安全补丁；同时 auth-url / auth-signin / auth-response-headers 都不在 ingress2gateway 的转换范围内，换入口控制器时必须手工重建这三处。替代路线（Traefik 注解兼容 provider、Gateway API + extAuth、网关原生 OIDC）各自的头注入字段、未认证跳转缺口与验证方法见 IAM 入口迁移：ingress-nginx 退役后的认证网关落地。

核心概念#

Provider#

oauth2-proxy 不自己实现认证，而是委托给上游 Provider。它支持的 Provider 包括：

Session 与 Cookie#

oauth2-proxy 的会话管理完全基于 Cookie：

• Session Cookie（默认 _oauth2_proxy）：存储加密后的 access token、ID token、refresh token 和过期时间。
• CSRF Cookie（默认 _oauth2_proxy_csrf）：防止跨站请求伪造，登录流程中校验 state 与 CSRF token 的一致性。

配置来源的优先级是 命令行参数 > 环境变量 > 配置文件。这条规则在 Kubernetes 中很容易被 Helm values 和 Secret 覆盖：排查“配置看起来正确但进程行为不对”时，先检查最终容器参数和环境变量，不要只看挂载的配置文件。

Cookie Secret 必须是解码后 16、24 或 32 字节的值。生产环境优先使用官方文档给出的 URL-safe Base64 生成方式，避免把普通 Base64 的 +、/ 或换行直接复制进 Secret：

python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'

Cookie 关键配置项：

默认 cookie Session Store 并不要求单副本或会话亲和性：多副本只要共享相同的 --cookie-secret 即可解密会话。切换到 redis 后，Cookie 通常只携带服务端 Session ID，但 Redis 的 TLS、凭据、容量、故障切换和恢复演练就成为 IAM 网关的生产前置条件。选择 Redis 的理由应是 Cookie 体积、服务端撤销或集中会话管理，而不是“副本多了就必须上 Redis”。详见 IAM 网关 oauth2-proxy 常见错误排错。

会话 Cookie 的体积上限由 oauth2-proxy 自己决定：内部常量是 4000 字节（浏览器普遍上限 4096，留了余量），超过后不会报错，而是拆分成 _oauth2_proxy_0、_1 分片。claims 裁剪、轻量 access token 与 Redis 票据格式的取舍见 IAM Token 体积治理。

Upstream#

oauth2-proxy 本身不处理业务流量，它有两个端口：

部署模式#

模式 1：Sidecar（推荐）#

每个应用 Pod 旁挂一个 oauth2-proxy sidecar 容器，与业务容器共享 localhost 网络：

# Deployment 摘录
spec:
  containers:
  - name: app
    image: my-app:latest
    ports:
    - containerPort: 8080
  - name: oauth2-proxy
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
    args:
    - --http-address=0.0.0.0:4180
    - --upstream=http://localhost:8080
    - --provider=keycloak-oidc
    - --oidc-issuer-url=https://sso.example.test/realms/internal
    - --client-id=my-app
    - --client-secret=***  # 建议通过 Secret 环境变量注入
    - --cookie-secret=***  # 同上
    - --email-domain=*
    - --cookie-secure=true
    - --reverse-proxy=true
    ports:
    - containerPort: 4180

优点：生命周期与应用一致，端口不暴露到集群外。缺点：每个应用一个 oauth2-proxy，资源碎片化。

模式 2：独立 Service（多应用共享）#

一个 oauth2-proxy Deployment/Service 保护多个应用：

# oauth2-proxy 配置片段
--upstream=static://200  # 不代理具体 upstream，仅做 auth_request 校验
--skip-auth-route=GET=^/healthz  # 健康检查跳过认证

多个 Ingress 都指向同一个 auth-url: http://oauth2-proxy.platform.svc/oauth2/auth。

优点：资源集中，管理方便。缺点：所有应用复用同一个 Provider 和 Client，授权粒度受限；需要按应用设置 --allowed-group 时必须用不同实例。

模式 3：全代理模式（不推荐生产）#

oauth2-proxy 同时做认证和流量代理：用户浏览器 → oauth2-proxy:4180 → 后端应用。适合测试环境，生产环境缺少 Ingress 的 TLS 终结、限流、WAF 等能力。

与 Keycloak 对接的关键细节#

oauth2-proxy 和 Keycloak 是最常见组合，但有几个容易踩坑的点：

Audience（aud claim）#

Keycloak 默认不把 Client ID 写入 access token 的 aud 字段。oauth2-proxy 的 Keycloak OIDC Provider 会校验 aud，并要求其中包含 --client-id 或 --oidc-extra-audience 配置的值；不匹配时返回：

{"error": "invalid_token", "error_description": "expected audience \"oauth2-proxy\" got [\"account\"]"}

解决方案：在 Keycloak Client 的 Client Scopes 里添加 Audience mapper，把 Included Client Audience 设为目标 Client ID。

Issuer URL（iss claim）#

oauth2-proxy 的 --oidc-issuer-url 必须与 Keycloak 实际签发 Token 的 iss 完全一致：

不一致时，oauth2-proxy 会拒绝 Token："issuer mismatch"。

Groups vs Roles#

oauth2-proxy 的 --allowed-group 可以限制哪些用户组能访问应用。Keycloak 端的组信息需要通过 Group Membership mapper（放在 Client Scope 或 Client 的 Dedicated Scope）写入 Token 的 groups claim。

如果使用 realm roles 控制访问，可以用 --allowed-role，但这种方式在跨 Client 共享时容易混淆，推荐优先用 groups。

Redirect URL 与 Cookie Domain#

• redirect URL：--redirect-url 必须与 Keycloak Client 的 Valid Redirect URIs 完全一致，通常不显式设置，让 oauth2-proxy 自动推导。
• Cookie domain：如果 Keycloak 和业务应用不在同一个子域，注意 Cookie 作用域。--cookie-domain=.example.test 可以让 app.example.test 和 sso.example.test 共享 Cookie（安全严格环境中不推荐）。

安全加固#

Cookie Secret 管理#

Cookie 内容用 AES 加密，密钥通过 --cookie-secret 传入。生产环境：

• 至少 32 字节随机值：openssl rand -base64 32
• 所有 oauth2-proxy 实例共用同一个 secret（否则无法解密彼此的 Cookie）
• 通过 Kubernetes Secret 挂载环境变量，不写入配置文件
• 轮换流程：生成新 secret → 同时用新 secret 重启所有实例 → 所有用户需重新登录

超时与刷新#

--cookie-expire=8h          # Session Cookie 有效期
--cookie-refresh=1h         # Token 刷新间隔
--session-store-type=cookie # Session 存储在 Cookie 中（默认，无需 Redis）

cookie-refresh 小于 cookie-expire 时，oauth2-proxy 会在接近过期时自动用 refresh token 续期，用户无感。

白名单路径#

健康检查、静态资源、公开页面需要跳过认证：

--skip-auth-route=GET=^/healthz
--skip-auth-route=GET=^/metrics
--skip-auth-route=GET=^/public/.*

安全修复（v7.11.0）：skip_auth_routes 的正则此前匹配完整请求 URI（路径 + 查询参数），可被构造为 /api/private/sensitive?path=/status 绕过认证。v7.11.0 修正为只匹配路径部分。如果你的白名单规则依赖查询参数匹配，升级前必须审查所有 skip_auth_routes 条目。旧参数 --skip-auth-regex 已标记为废弃，建议迁移到 --skip-auth-route。

GAP-Signature 请求签名#

当前 oauth2-proxy 配置文档把 --signature-key 定义为 GAP-Signature request signature key，参数格式为 algorithm:secretkey。它不是“给所有 X-Auth-Request-* Header 自动加 HMAC”的通用开关；后端是否能验证签名，必须按实际使用的 GAP 接入协议实现并做联调。不要把它当成替代网络隔离、Ingress 清理客户端同名 Header 或后端授权校验的捷径。

--set-authorization-header=true    # 把 Bearer token 透传到后端；仅在确有需要时开启
--set-xauthrequest=true            # 注入 X-Auth-Request-* 响应 Header
--signature-key=sha256:<secret>    # GAP-Signature 密钥；算法和格式按版本文档确认

--set-xauthrequest 的职责只是生成认证响应头；--pass-access-token 会额外产生 X-Auth-Request-Access-Token。如果后端不需要 Token，就不要打开透传，减少凭据传播面。后端仍必须只接受来自受信任 Ingress 的请求，并独立验证自己消费的 Token 的 iss、aud、签名、过期时间和权限。

版本演进与安全更新（v7.9 → v7.15.5）#

oauth2-proxy 从 v7.8.2（2025-03）到 v7.15.5（2026-10）经历了多个版本，包含若干安全审计修复和配置行为变更。下表按版本列出影响生产部署的关键变更，升级前应逐条核对。

--trusted-proxy-ip：转发头信任边界#

v7.15.2 引入 --trusted-proxy-ip，用于显式指定允许发送 X-Forwarded-* 头的反向代理 IP 或 CIDR 范围。未设置时 oauth2-proxy 保留向后兼容行为（信任所有来源 0.0.0.0/0），并在启动时记录告警。

--reverse-proxy=true
--trusted-proxy-ip=10.0.0.0/8     # 只信任集群内网代理
--trusted-proxy-ip=172.16.0.0/12  # 可多次指定

生产部署中如果客户端能绕过 Ingress 直连 oauth2-proxy Service，未设置此参数意味着攻击者可以伪造 X-Forwarded-Uri 等头绕过认证——这正是 v7.15.2 修复的 Critical 漏洞（ GHSA-7x63-xv5r-3p2x）的利用路径。

v7.15.5：--trusted-ip 豁免的传输对端校验（Critical，升级本身不是修复）#

v7.15.2 收紧的是 X-Forwarded-Uri 一类的转发头，没有覆盖 --trusted-ip 这条判定路径。同时配置 --trusted-ip 与 --reverse-proxy=true 的部署在 ≥6.1.0 ≤7.15.3 上存在两个独立缺陷（ GHSA-wr5q-7wxw-x568）：

• 不校验传输对端：读取 --real-client-ip-header 指定的头之前，没有先确认连接对端是可信代理。攻击者能直连 oauth2-proxy 时，直接提交一个豁免地址即可被判定为来自可信 IP，跳过认证（包括 auth-only 端点）。此时已经配置了 --trusted-proxy-ip 也不保护这条路径——这是最容易被忽略的一点。
• X-Forwarded-For 取值方向错误：配置 --real-client-ip-header=X-Forwarded-For 时取最左地址。合法代理在链尾追加真实客户端地址后，攻击者自己填写的豁免地址仍然留在最左端，因此这条路在"直连已被阻断"的部署里同样可利用。

v7.15.5 的修复是先校验传输对端，再从右向左遍历 X-Forwarded-For：跳过 --trusted-proxy-ip 中的代理跳，遇到第一个不可信地址即认定其为客户端；畸形的中间跳不再授予豁免。

升级本身不等于修复：兼容性默认仍然信任所有来源，有效链仍保留最左取值行为。要真正关闭这个绕过，必须显式配置范围足够窄的 --trusted-proxy-ip，并把直连代理和每一个可信中间跳都包含进去：

--reverse-proxy=true
--real-client-ip-header=X-Forwarded-For
--trusted-proxy-ip=10.0.4.0/24     # 直连 oauth2-proxy 的 Ingress
--trusted-proxy-ip=10.0.0.0/16     # 中间一跳 LB——漏掉这一跳等于没配

漏配一跳时，“看起来配了"比"完全没配"更难排查：日志里的客户端地址落在可信网段内，但豁免判定仍可能落在攻击者可控的值上。如果无法确定完整代理链，官方给出的替代方案是删除 --trusted-ip / trusted_ips 豁免，让这些请求走正常认证流程。

v7.15.5：skip-auth 路径语义第二次收紧（含兼容性破坏）#

--skip-auth-route / --skip-auth-regex 在 v7.11.0 已经收紧过一次（从匹配完整 URI 改为只匹配路径）。v7.15.5 修的是另一层问题：oauth2-proxy 与下游代理/应用对同一路径的解释不一致，攻击者可以构造一个"命中豁免但下游解析为受保护资源"的路径（ GHSA-63jm-59jj-478j）：

修复方式是在任何正则求值之前按 HTTP request-target 语义解析路径，对非法或歧义路径直接拒绝授予豁免——否定的正则规则同样不生效。

升级前必须核对的行为变化：含点段、重复斜杠（含前导 //）、分号、反斜杠、类 fragment 内容、被解码的问号、控制字符（含其编码形式）的路径不再能获得豁免。/public/file;version=1、/public//file 这类看着正常的路径升级后会转为需要认证；# 与 %23 也不再在匹配前被静默剥离。另外，可信来源提供的 X-Forwarded-Uri 必须是 origin form（/path?query），不能是完整 URL。

# 1) 列出当前全部豁免规则
grep -n "skip-auth-route\|skip-auth-regex" /etc/oauth2-proxy.cfg
# 2) 用歧义路径验证：v7.15.5 下必须回到认证流程
curl -sS -o /dev/null -w '%{http_code}\n' "https://app.example.com/public/file;version=1"
# 期望 302 跳登录页；旧版本会返回 200

回滚到更早的镜像 tag 只会恢复宽松匹配、把两个认证绕过一起留在线上，因此不作为备选。确实需要公开的路径，应当与受保护路由在入口层分开暴露（独立域名或独立 Ingress 路由），而不是把 --skip-auth-route 放宽。proxyRawPath=false 只覆盖"编码点段 + 直连代理"这一种情形，不能替代另外两个向量的处理。

v7.15.5：回调错误日志不再打印完整请求（日志格式变更）#

GHSA-hhqp-vx7f-5c6m（Moderate，影响 ≥7.3.0）：当 OAuth 回调携带缺失、过期或无效的 CSRF Cookie 时，有五处诊断代码打印的是完整 HTTP 请求，里面可能包含 session Cookie、回调端点的其他 Cookie，以及 Authorization: Basic/Bearer。能读到日志（含集中式日志平台）的人可以重放仍然有效的凭据；回调本身仍会被 CSRF 校验拒绝，所以这不是匿名的远程 Cookie 读取漏洞。

v7.15.5 把这五处诊断替换为认证日志事件：只记录失败原因和 Cookie 名称，不再输出 Cookie 值与 Authorization 头，并去掉了失败消息中的 state 值。副作用是这些日志改由 --auth-logging / --auth-logging-format 控制，不再跟随标准日志设置——依赖旧日志格式做解析或告警的团队需要同步更新规则。无法立即升级时可临时 --standard-logging=false 兜底，但它会连带压掉其他标准运维日志，只适合短期过渡。

CSRF Cookie 过期行为变更（v7.15.0）#

v7.15.0 之前，CSRF Cookie 的过期校验错误地使用了 Expire（Session Cookie 有效期）而非 CSRFExpire。如果你的 CSRF Cookie 寿命与 Session Cookie 不同（例如 Session 8h、CSRF 1h），升级后 CSRF 校验会按 --cookie-csrf-expire 独立判断。未显式设置 --cookie-csrf-expire 时使用默认值 12h。

--config-test：配置预检（v7.15.0）#

v7.15.0 新增 --config-test 标志，在 CI/CD 流水线中可先验证配置再部署：

oauth2-proxy --config=/etc/oauth2-proxy.cfg --config-test && echo "config OK"

退出码 0 表示配置有效，非 0 表示有错误。适合在 Helm hook 或 pre-deploy 阶段拦截配置问题。

与替代方案对比#

关键区别：Traefik ForwardAuth 和 Nginx auth_request 是协议（不是产品），它们本身不做认证，需要指向一个认证后端——而 oauth2-proxy 正好是最常用的认证后端实现。

生产上线检查清单#

• --cookie-secret 已配置，值为解码后 16/24/32 字节的 URL-safe Base64，所有实例一致。
• 配置来源已核对：命令行参数 > 环境变量 > 配置文件，未被 Helm 或 Secret 中的同名值覆盖。
• --cookie-secure=true（HTTPS 环境）。
• --cookie-httponly=true，未关闭。
• --cookie-samesite 已根据部署拓扑设置（子域共享 Cookie 时注意）。
• Keycloak Client 已配置 Audience mapper，Token aud 包含 oauth2-proxy Client ID。
• --oidc-issuer-url 与实际 Token iss 完全一致（无尾斜杠，无 /auth 差异）。
• groups/roles claim 已映射，--allowed-group 按应用粒度生效。
• --skip-auth-route 已配置健康检查和白名单路径。
• --skip-auth-route 规则不依赖查询参数匹配（v7.11.0 修复后只匹配路径）。
• 白名单路径不含点段、重复斜杠、分号、反斜杠、类 fragment 内容或控制字符；需要公开的路径已与受保护路由在入口层分开暴露（v7.15.5 起歧义路径一律不授予豁免）。
• 启用 --reverse-proxy 时已设置 --trusted-proxy-ip，并覆盖直连代理与每一个可信中间跳（v7.15.2+ 生产必选项）。
• 保留 --trusted-ip 豁免时，已按 v7.15.5 校验传输对端与 X-Forwarded-For 取值方向；无法确定完整代理链时该豁免已删除。
• /oauth2 路径已路由到 oauth2-proxy（不是只配了 /oauth2/auth）。
• 若启用 --signature-key，已按实际 GAP-Signature 协议完成后端验签联调；没有该需求时不启用。
• 镜像版本不低于 v7.15.5（截至 2026-10-01 的最新 release；v7.15.5 修复两个 Critical 认证绕过与一处凭据日志泄露，并对 skip-auth 与 --trusted-ip 行为有兼容性影响）。
• 依赖日志格式的解析器与告警规则已同步（v7.15.5 起 OAuth 回调失败诊断改由 --auth-logging / --auth-logging-format 控制）。
• 若使用 Alpha Config，Header 注入配置已迁移到 v7.14.0+ 的嵌套格式。
• 回滚方案：删除 Ingress 上的 auth-url/auth-signin 注解或 Traefik ForwardAuth middleware 引用，保留 oauth2-proxy 实例以便事后复盘。

IAM FAQ#

oauth2-proxy 是 IAM 还是应用网关？#

它是 IAM 链路中的入口认证代理，不是完整 IAM 平台。Keycloak、Dex 等 Provider 负责身份认证和 Token 签发；oauth2-proxy 负责浏览器会话、入口放行和认证结果传递。用户、组、MFA、生命周期和审计策略不能只靠 oauth2-proxy 管理。

X-Auth-Request-User 能直接当授权依据吗？#

不能。它是认证代理输出的 Header，不是后端资源授权证明。Ingress 必须清理客户端伪造的同名 Header，后端还要根据自身的 Token、scope、role 或资源关系做授权；高风险操作还要单独判断认证强度和实时会话状态。

多副本 oauth2-proxy 是否必须使用 Redis？#

不必须。默认 Cookie Session Store 下，多副本共享同一个 --cookie-secret 即可读取会话。只有 Cookie 过大、需要服务端集中撤销或不希望 Token 留在 Cookie 中时，再引入 Redis；引入后要增加 TLS、凭据、容量、监控、故障和回滚验证。

升级到 v7.15.5 后必须做什么？#

三件事，缺一件都不算完成：

1. 审查全部路径豁免：--skip-auth-route / --skip-auth-regex 里含点段、重复斜杠、分号、反斜杠、类 fragment 内容或控制字符的规则，在 v7.15.5 后不再放行。确实需要公开的路径，移到受保护路由边界之外，而不是放宽正则。
2. 补齐 --trusted-proxy-ip：这是唯一需要强调"只升级无效"的项。v7.15.5 修好了 --trusted-ip 豁免的判定逻辑，但兼容性默认仍信任所有来源，必须显式配置覆盖直连代理与每一个可信中间跳的 CIDR；无法确定完整代理链时，直接删除 --trusted-ip 豁免。
3. 同步日志解析器：回调失败诊断在 v7.15.5 起改由 --auth-logging / --auth-logging-format 控制，输出内容也改成只记 Cookie 名称。

此外，X-Forwarded-Uri 必须是 origin form（/path?query）而非完整 URL。v7.15.2 与 v7.15.5 各修复了多个 Critical 认证绕过，v7.15.3 / v7.15.4 不应继续作为新部署基线。

参考与延伸阅读#

• oauth2-proxy 配置总览（配置优先级、Cookie Secret 生成、config-test）： https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/
• oauth2-proxy v7.15.5 发行说明（Go 1.26.8、CVE 列表、Bitbucket provider 变更）： https://github.com/oauth2-proxy/oauth2-proxy/releases/tag/v7.15.5
• GHSA-63jm-59jj-478j（skip-auth 路径豁免绕过，含三个路径歧义向量与兼容性说明）： https://github.com/oauth2-proxy/oauth2-proxy/security/advisories/GHSA-63jm-59jj-478j
• GHSA-wr5q-7wxw-x568（伪造客户端 IP 头绕过 --trusted-ip，含 XFF 遍历方向与 --trusted-proxy-ip 配置要求）： https://github.com/oauth2-proxy/oauth2-proxy/security/advisories/GHSA-wr5q-7wxw-x568
• GHSA-hhqp-vx7f-5c6m（OAuth 回调错误日志泄露凭据，含日志开关变更）： https://github.com/oauth2-proxy/oauth2-proxy/security/advisories/GHSA-hhqp-vx7f-5c6m
• oauth2-proxy v7.15.2 安全公告（认证绕过修复与 --trusted-proxy-ip 引入）： https://github.com/oauth2-proxy/oauth2-proxy/releases/tag/v7.15.2
• oauth2-proxy v7.15.4 发行说明（依赖升级与安全修复）： https://github.com/oauth2-proxy/oauth2-proxy/releases/tag/v7.15.4
• oauth2-proxy v7.15.0 发行说明（CSRF Cookie、--config-test、OIDC signing algorithm）： https://github.com/oauth2-proxy/oauth2-proxy/releases/tag/v7.15.0
• oauth2-proxy v7.11.0 发行说明（skip_auth_routes 路径匹配修复）： https://github.com/oauth2-proxy/oauth2-proxy/releases/tag/v7.11.0
• oauth2-proxy 源码配置定义（signature-key）： https://github.com/oauth2-proxy/oauth2-proxy/blob/master/pkg/apis/options/options.go
• Keycloak OIDC Provider 配置： https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc/
• 本站解决方案博客： Keycloak + oauth2-proxy 集成指南
• 本站 Traefik 方案： Traefik ForwardAuth + Keycloak + oauth2-proxy
• 本站排错指南： Keycloak 重定向循环与 401 排错
• 本站排错速查： IAM 网关 oauth2-proxy 常见错误排错
• 本站 Keycloak 架构： Keycloak 架构深度解析
• 本站 K8s 生产部署： Keycloak Kubernetes 生产环境部署