oauth2-proxy

OAuth2/OIDC 反向代理接入

补充说明

oauth2-proxy 在应用前面做 OIDC/OAuth2 登录，认证通过后把用户信息通过 header 传给后端。它适合给没有内置认证的内部服务加统一登录。

常用示例

oauth2-proxy --config /etc/oauth2-proxy.cfg
oauth2-proxy \
  --provider=oidc \
  --oidc-issuer-url=https://auth.example.com/realms/app \
  --email-domain=example.com \
  --upstream=http://127.0.0.1:8080 \
  --http-address=0.0.0.0:4180 \
  --cookie-secret="$COOKIE_SECRET"

oauth2-proxy.cfg：

provider = "oidc"
oidc_issuer_url = "https://auth.example.com/realms/app"
email_domains = ["example.com"]
upstreams = ["http://127.0.0.1:8080"]
http_address = "0.0.0.0:4180"
cookie_secret = "32-byte-random-string"
reverse_proxy = true

易错点与排错

• cookie_secret 必须是足够长的随机值；太短会启动失败或会话不安全。
• 回调地址要和身份提供方配置完全一致（协议、域名、端口、路径）。
• reverse_proxy=true 时才信任 X-Forwarded-*；不要无条件信任外部头。
• 后端只能信任来自 oauth2-proxy 的 header；否则可被伪造身份。
• 会话存储默认在 cookie；多实例要配置 Redis 等共享存储。
• CSRF、SameSite 和 TLS 配置影响登录和回调。
• 放行健康检查/静态资源时用 skip_auth_routes，不要绕过整个站点。

相关命令

• keycloak — OIDC 提供方
• nginx — 前置反向代理
• redis-server — 会话存储

读完自测

合上页面，先回答，再展开对照。

1. 多实例部署后登录态频繁丢失，为什么？
2. 后端如何避免有人伪造身份 header？
3. reverse_proxy=true 的作用和风险是什么？