这是「Docker 好项目」系列的第 25 期。前 24 期我写了 Uptime Kuma(服务在不在)、Gitea/Miniflux/Paperless-ngx/linkding 这些自托管服务,也写了第 20 期 Pocket ID(把登录搬回自己服务器)。但有个绕不开的尴尬:这些服务里有一大半默认是裸奔的——Scrutiny(第 24 期)、Dozzle(第 22 期)、Homepage(第 18 期)、Kopia(第 21 期)、ntfy(第 13 期)装好打开就是界面,没有任何登录。要么塞进内网/VPN,要么给每个都单独配一套鉴权,都很麻烦。这期介绍 oauth2-proxy:一个反向代理/认证中间件,给任何没有登录的服务,套一层 OAuth / OIDC 统一登录。它可以和第 20 期的 Pocket ID 直接配合——Pocket ID 当 IdP,oauth2-proxy 当守门员。

oauth2-proxy 效果图

痛点开场

先看你现在的自托管服务是怎么"被保护"的:

  • 默认裸奔:绝大多数自托管项目(上面点名的那几个)源码里压根没有鉴权中间件。装完公网一开,谁拿到地址谁就能看、能操作。Scrutiny 连硬盘序列号都给你亮出来
  • 内网/VPN 不是银弹:家里 NAS 的服务走 Tailscale 确实省事,但凡是需要在外网给家人/同事用的(比如记账本 Actual Budget 第 16 期、RSS 阅读器 Miniflux 第 12 期),就卡在"要么裸奔要么自己写登录"上
  • 每个服务单独配 OAuth 太重:GitHub OAuth、Google OAuth 一套接一套,每个项目的文档还都不一样,接入成本远高于服务本身
  • 反向代理层加 Basic Auth 太弱:1Panel / Nginx 能加密码,但浏览器记住的明文密码、没法接 SSO、没法按邮箱/组放行,体验很原始
  • 第 20 期埋的伏笔:Pocket ID 已经把"统一身份"搭好了,但它本身不帮别的网站做登录守卫——它只是个 IdP,得有个"门卫"把登录态翻译成每个网站能懂的 HTTP 头

oauth2-proxy 干的事很纯粹:挡在服务和用户之间,先让用户去 OAuth/OIDC 提供商登录,登录成功才把请求转发给后面的服务,并带上 X-Forwarded-User、X-Forwarded-Email 这类头。它支持 Google、GitHub、GitLab、Azure/Entra、Keycloak,以及任何标准 OIDC 提供商——其中就包括你自建的 Pocket ID。

oauth2-proxy 登录页:一个清爽的卡片,点一下跳去 IdP 登录

(上图是官方登录页截图:白卡片 + 项目 logo + 一个"Sign in with XXX"按钮,下方"Secured with OAuth2 Proxy"标明是谁在守门。默认风格,可换 logo/文案。)

能力边界

能干什么

  • 两种部署形态:① 直接当反向代理——它自己监听端口、做认证、再把流量转发给 upstream;② 当认证中间件——配合 Nginx/OpenResty 的 auth_request 指令,只回答"过没过认证"(202/401),真正的转发还是交给你的反代。1Panel 场景两种都可用,下文细说
  • 几乎通吃所有 IdP:Google、Azure/Entra ID、GitHub、GitLab、Keycloak、Nextcloud、Gitea、LinkedIn、Facebook、Bitbucket、DigitalOcean,以及任意标准 OIDC(Pocket ID、Authelia、Authentik、Keycloak 等)——通过通用的 oidc provider + discovery 自动适配
  • 把身份翻译成 HTTP 头:登录后给上游注入 X-Forwarded-User、X-Forwarded-Email、X-Forwarded-Preferred-Username,以及可选的 X-Forwarded-Access-Token(OAuth access token)。上游应用只读这几个头就知道"谁登录了",自己不用接 OAuth
  • 精细放行:按邮箱域名(email-domain)、按具体邮箱名单文件(authenticated-emails-file)、按 OIDC 组(allowed-groups)、按 IP(trusted-ip)四种维度控制谁能进
  • 会话存浏览器 cookie 或 Redis:默认全部塞进加密 cookie(无需额外存储);用户多、OIDC token 大(如 Entra 的大 group 声明)时切 Redis,避免 cookie 被拆成好几段
  • 可观测:/ping、/ready 健康检查端点,/metrics 暴露 Prometheus 指标,认证尝试、请求都走结构化日志
  • 登出:/oauth2/sign_out 清自己的 cookie,并能带着 rd 参数跳去 IdP 的登出页做联合登出

不干什么

  • 不是用户系统,不存账号。它只是"门卫 + 翻译",身份来自上游 IdP(Pocket ID / Google / GitHub…)。想自建账号体系那是 Authentik / Pocket ID 的事
  • 不做细粒度授权。它只能回答"这个人过没过认证、属于哪个组",至于"这个用户能删哪条数据",是上游应用自己的事,oauth2-proxy 管不到
  • 不发通知/告警。它没有"有人登录了就推一条到手机"这种能力(下面"可观测性"一节会诚实说明怎么绕)。这点和系列里 Uptime Kuma、ntfy、Scrutiny 不同,别指望它主动喊你
  • 不解决 IdP 本身。你总得有一个 OAuth/OIDC 提供商——要么用大厂的(GitHub/Google),要么像第 20 期那样自己起一个 Pocket ID。oauth2-proxy 不替你发 client 凭证
  • 不是 WAF / 不是限速器。它只管"登录没登录",DDoS、SQL 注入、路径遍历这些不在它的职责范围
  • HTTPS 终止要你自己管。它默认不终止 TLS(除非配 tls-* 并监听 443),生产环境通常放在已经终止了 HTTPS 的反代后面,记得开 cookie-secure

部署前准备

项 说明
镜像 quay.io/oauth2-proxy/oauth2-proxy:v7.15.5。官方只发布到 quay.io(安装文档和镜像 config 的 org.opencontainers.image.url 都指向 quay);Docker Hub、GHCR 上没有官方镜像,别去 Docker Hub 找。国内直连 quay.io 一般可用,拉不动就走代理
tag 规则 只有完整版本号(v7.15.5)+ latest + -alpine 变体,没有 v7 / v7.15 这类滚动次版本 tag(我逐个探过:404)。latest 当前 digest 与 v7.15.5 完全相同。不用 latest,钉 v7.15.5,理由同系列一贯要求
平台 amd64 / arm64 / armv7 / armv6 / ppc64le / s390x 全有;-alpine 后缀变体用于需要 shell 的调试场景(见踩坑清单第 1 条)
端口 4180/tcp(注意:默认只绑 127.0.0.1!镜像 config 里 http-address 默认 127.0.0.1:4180。想让容器外/反代访问,必须显式 --http-address=0.0.0.0:4180)
数据卷 无必需卷——会话默认存浏览器 cookie,无需持久化目录。OIDC 的 JWT 签名私钥镜像已自带(/etc/ssl/private/jwt_signing_key.pem),不用挂。配置可选挂 /etc/oauth2-proxy.cfg
运行用户 65532(distroless 的 nonroot 用户)。镜像基于 distroless(自 v7.6.0 起从 Alpine 换成了 distroless)——几乎没有 shell,docker exec ... sh 进不去,排障要用 -alpine 标签
健康检查 镜像无内置 healthcheck(config 里 Healthcheck = null)。浅检查打 /ping,深检查(会确认 Redis 连上没)打 /ready。容器级健康检查见踩坑清单第 1 条
资源 常驻几十 MB 内存、几乎不占 CPU,纯转发,对 1 核 256MB 的小机毫无压力

动手前,你这边要备齐两样东西:

  1. 一个 OAuth/OIDC 提供商,并且在那里注册好一个应用,拿到 client-id 和 client-secret,回调地址(redirect URI)填 https://你的域名/oauth2/callback。本系列最顺的搭配是第 20 期的 Pocket ID:在 Pocket ID 后台建一个 OIDC client,callback 填上面的地址即可
  2. 一串 32 字节的随机串当 cookie 加密密钥(必须能 base64 解码出 16/24/32 字节,否则启动直接报错):
# 32 字节 → 64 位 base64,复制这一行输出当 OAUTH2_PROXY_COOKIE_SECRET
python3 -c 'import secrets,base64; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())'
# 等价写法:openssl
openssl rand -base64 32 | tr -- '+/' '-_'

docker run 一行版

先跑一个"纯守门员"形态(只做认证、不反向代理具体服务),配合你现有的 Nginx 用 auth_request 模式——这是 1Panel 机器上最省事的一种:

docker run -d --name oauth2-proxy --restart unless-stopped \
  -p 127.0.0.1:4180:4180 \
  -e OAUTH2_PROXY_PROVIDER=oidc \
  -e OAUTH2_PROXY_OIDC_ISSUER_URL=https://pocketid.example.com \
  -e OAUTH2_PROXY_CLIENT_ID=你的client_id \
  -e OAUTH2_PROXY_CLIENT_SECRET=你的client_secret \
  -e OAUTH2_PROXY_COOKIE_SECRET=上面的32字节base64 \
  -e OAUTH2_PROXY_EMAIL_DOMAIN="*" \
  -e OAUTH2_PROXY_HTTP_ADDRESS=127.0.0.1:4180 \
  -e OAUTH2_PROXY_REDIRECT_URL=https://app.example.com/oauth2/callback \
  -e OAUTH2_PROXY_REVERSE_PROXY=true \
  -e OAUTH2_PROXY_TRUSTED_PROXY_IP=127.0.0.1/32 \
  -e OAUTH2_PROXY_UPSTREAM=static://202 \
  -e OAUTH2_PROXY_SKIP_PROVIDER_BUTTON=true \
  -e OAUTH2_PROXY_CODE_CHALLENGE_METHOD=S256 \
  -e OAUTH2_PROXY_WHITELIST_DOMAIN=".example.com" \
  -e OAUTH2_PROXY_SET_XAUTHREQUEST=true \
  -e OAUTH2_PROXY_COOKIE_SECURE=true \
  -e OAUTH2_PROXY_COOKIE_SAMESITE=lax \
  quay.io/oauth2-proxy/oauth2-proxy:v7.15.5

说明:OAUTH2_PROXY_UPSTREAM=static://202 让 / 直接返回 202(健康检查友好),实际流量走 Nginx 的 auth_request 去问 /oauth2/auth,不经过 upstream。-p 127.0.0.1:4180:4180 只暴露给本机回环,由同机 Nginx 来调,更安全。

docker-compose 推荐版

如果你想"一条 compose 直接给某个裸奔服务套壳"(反向代理模式),让 oauth2-proxy 自己当入口转发给 upstream,用这份:

services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
    container_name: oauth2-proxy
    restart: unless-stopped
    # 反向代理模式下它要当公网入口,绑 0.0.0.0
    ports:
      - "4180:4180"
    environment:
      # 用你自建的 Pocket ID(第 20 期)当 IdP
      OAUTH2_PROXY_PROVIDER: oidc
      OAUTH2_PROXY_OIDC_ISSUER_URL: https://pocketid.example.com
      OAUTH2_PROXY_CLIENT_ID: 你的client_id
      OAUTH2_PROXY_CLIENT_SECRET: 你的client_secret
      OAUTH2_PROXY_COOKIE_SECRET: 上面的32字节base64
      # 放行规则:* 表示任何登录用户都放;要收紧就写具体域名或邮箱名单文件
      OAUTH2_PROXY_EMAIL_DOMAIN: "*"
      # 必须显式绑 0.0.0.0,否则默认 127.0.0.1 外部连不上
      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
      # OAuth 回调地址,必须和 IdP 后台填的一致
      OAUTH2_PROXY_REDIRECT_URL: https://app.example.com/oauth2/callback
      # 真正要守卫的后端(举例:第 24 期 Scrutiny),同 compose 网络内用服务名
      OAUTH2_PROXY_UPSTREAM: http://scrutiny:8080
      # 跨子域种 cookie 的白名单,前缀 . 允许所有子域
      OAUTH2_PROXY_WHITELIST_DOMAIN: .example.com
      # 登录后把身份和 token 注入请求头,上游应用只读头就行
      OAUTH2_PROXY_SET_XAUTHREQUEST: "true"
      OAUTH2_PROXY_PASS_ACCESS_TOKEN: "true"
      # 跳过"选择提供商"按钮,直接跳登录(单 IdP 时用)
      OAUTH2_PROXY_SKIP_PROVIDER_BUTTON: "true"
      # OIDC 建议开 PKCE(Pocket ID 等现代 IdP 通常要求)
      OAUTH2_PROXY_CODE_CHALLENGE_METHOD: S256
      # cookie 安全:HTTPS 下必须 secure + 合理 SameSite
      OAUTH2_PROXY_COOKIE_SECURE: "true"
      OAUTH2_PROXY_COOKIE_SAMESITE: lax
    # oauth2-proxy 无内置健康检查;distroless 镜像里没有 curl/wget,
    # 容器级 healthcheck 需要 -alpine 标签才有 wget。这里不挂,靠 /ping 外部探。

上面的 scrutiny:8080 只是举例。你要守卫谁,就把 OAUTH2_PROXY_UPSTREAM 指向谁(Gitea、Miniflux、Dozzle、Homepage…都行)。只要那个服务在同网络里、不需要自己登录,oauth2-proxy 就替它把门看住了。

配置项逐项解释

oauth2-proxy 三套配置等价:命令行 flag(如 --http-address)、环境变量(前缀 OAUTH2_PROXY_,下划线代替横线,如 OAUTH2_PROXY_HTTP_ADDRESS)、配置文件(如 /etc/oauth2-proxy.cfg,同样下划线、可重复项用复数 upstreams)。优先级:命令行 > 环境变量 > 配置文件。下面是部署时真正要动的几个,"为什么这么写"一并说明:

配置项 默认值 为什么这么写
provider google 必须改。默认是 google,用别的 IdP 不显式指定就会走 Google 流程。自建 OIDC 写 oidc
oidc-issuer-url 空 oidc provider 必填。填 IdP 的 issuer(如 https://pocketid.example.com),oauth2-proxy 会自动去读 /.well-known/openid-configuration 拿端点,不用手写
client-id / client-secret 空 必填(除 Entra 联邦令牌、login.gov 外所有 provider 都要求)。在 IdP 后台建应用拿。secret 也可走 client-secret-file 让文件热更新,适合密钥轮转
cookie-secret 空 必填,且必须能 base64 解出 16/24/32 字节。它是加密会话 cookie 的 AES 密钥,丢了所有用户会话失效、且明文 cookie 可被篡改。用上一节命令生成
email-domain 空 必填其一(另两个是 authenticated-emails-file、htpasswd-file)。不填启动直接报 "missing setting for email validation"。* 表示放行所有登录邮箱;只想放自己域名就写 example.com
http-address 127.0.0.1:4180 反代/公网部署时必须设 0.0.0.0:4180,否则镜像里只绑回环,容器外连不上——这是最容易踩的第一个坑
redirect-url 自动推导 强烈建议显式写 https://域名/oauth2/callback,且和 IdP 后台登记的回调地址逐字符一致,否则登录回调直接被拒
upstream 空 反向代理模式下填后端地址(http://svc:port)。只做 auth_request 守门员时填 static://202 让 / 返回 202 即可
reverse-proxy false 配合 Nginx auth_request 时必须 true,这样它才信任 X-Real-IP / X-Forwarded-For 这类反代传来的头,正确拿到真实客户端 IP
trusted-proxy-ip 空(默认信任所有 IP) reverse-proxy=true 时务必设成反代的来源,如 127.0.0.1/32。留空意味着"任何能伪造 X-Forwarded-For 的人都可能是可信代理",有绕过风险
set-xauthrequest false 设 true 才把 X-Auth-Request-User/Email/Access-Token 头传给 Nginx(auth_request 模式下 Nginx 用 auth_request_set 读这些头再转给后端)。想让后端知道"谁登录了"就开
cookie-secure true HTTPS 下保持 true。只有纯 HTTP 内网才关。若反代层是 HTTP、又开着 secure,cookie 写不进去 → 无限登录循环
cookie-samesite 空 现代浏览器建议 lax(或跨站场景 none,但 none 强制 cookie-secure)。空 = 不设置该属性,行为看浏览器默认
skip-provider-button false 单 IdP 时设 true,跳过"选择登录方式"页,直接跳登录,体验更顺
code-challenge-method 空 OIDC 建议 S256 开 PKCE,Pocket ID 这类现代 IdP 通常要求,不开可能注册回调时报错
whitelist-domain 空 登出后重定向、以及某些跳转允许的目标域。前缀 . 或 *. 放行子域。不填,登出跳转会被忽略
session-store-type cookie 默认 cookie 直存(无需 Redis)。OIDC token 大(如 Entra 大 group 声明)导致 cookie 被拆成多段时,改 redis 只存一个小 ticket,Nginx 也省去处理多段 cookie 的麻烦
pass-access-token false 设 true 把 OAuth access token 通过 X-Forwarded-Access-Token 传给后端,后端可拿它去调 IdP 的 userinfo 等接口
silence-ping-logging false 健康检查 /ping 默认也写访问日志,监控频繁探活会把日志刷爆。设 true 安静一点

1Panel 面板怎么搞

1Panel 的应用商店不同版本收录情况不一样,我这台没搜到 oauth2-proxy 的收录项,所以直接走「容器 → 编排」贴 compose 最稳:

# 先手建宿主机目录(避免 Docker 用 root 创建导致权限绕不开)
mkdir -p /opt/1panel/apps/oauth2-proxy/oauth2-proxy

然后把上面「docker-compose 推荐版」的 ports/environment 原样贴进 容器 → 编排 → 创建编排(落盘在 /opt/1panel/apps/oauth2-proxy/oauth2-proxy/docker-compose.yml),启动即可。

1Panel 特有的两个注意点:

  • 反向代理模式 vs 中间件模式:若你只用 oauth2-proxy 给某个已有 1Panel 网站加登录,更推荐「中间件模式」——oauth2-proxy 只监听 127.0.0.1:4180,由该网站的 Nginx 反代用 auth_request 去调(见下一节)。这时编排里 ports 写成 "127.0.0.1:4180:4180",并且要带 OAUTH2_PROXY_REVERSE_PROXY=true + OAUTH2_PROXY_TRUSTED_PROXY_IP=127.0.0.1/32
  • 环境变量里的引号:1Panel 编排编辑器的「环境变量」是 key=value 单行格式,"true" 这种带引号写法只在 YAML 文件里需要;在表单里填 true 即可,别把 YAML 的引号也带进去

首次访问

以「中间件模式 + 1Panel 网站 app.example.com」为例:

  1. 浏览器打开 https://app.example.com → Nginx 的 auth_request 发现没登录,302 跳去 https://app.example.com/oauth2/sign_in?rd=...
  2. 如果点了 skip-provider-button,会跳过登录页直接重定向到 Pocket ID 的授权页;否则先看到上面那张"Sign in with Pocket ID"卡片
  3. 在 Pocket ID 完成登录/授权 → 跳回 https://app.example.com/oauth2/callback → oauth2-proxy 校验授权码、签发加密 cookie、再 302 回你最初想访问的 rd 地址
  4. 此后同一浏览器带着 cookie,Nginx 每次 auth_request 都拿到 202,正常放行;cookie 默认 168 小时(cookie-expire)内免登录
  5. 想登出:访问 https://app.example.com/oauth2/sign_out(可带 ?rd=https://pocketid.example.com/sign_out_page 做联合登出)

如果卡在无限重定向:九成是 cookie-secure 与协议不匹配(HTTPS 站点却开着 HTTP 反代且 cookie-secure=true),或 redirect-url 和 IdP 后台填的回调地址不一致。先查这两项。

最小可用配置

最小可跑(纯守门员 + 单 OIDC + 跳过选提供商),除必填项外尽量精简:

services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
    container_name: oauth2-proxy
    restart: unless-stopped
    ports:
      - "127.0.0.1:4180:4180"
    environment:
      OAUTH2_PROXY_PROVIDER: oidc
      OAUTH2_PROXY_OIDC_ISSUER_URL: https://pocketid.example.com
      OAUTH2_PROXY_CLIENT_ID: 你的client_id
      OAUTH2_PROXY_CLIENT_SECRET: 你的client_secret
      OAUTH2_PROXY_COOKIE_SECRET: 32字节base64
      OAUTH2_PROXY_EMAIL_DOMAIN: "*"
      OAUTH2_PROXY_HTTP_ADDRESS: 127.0.0.1:4180
      OAUTH2_PROXY_REDIRECT_URL: https://app.example.com/oauth2/callback
      OAUTH2_PROXY_REVERSE_PROXY: "true"
      OAUTH2_PROXY_TRUSTED_PROXY_IP: 127.0.0.1/32
      OAUTH2_PROXY_UPSTREAM: static://202
      OAUTH2_PROXY_SKIP_PROVIDER_BUTTON: "true"
      OAUTH2_PROXY_CODE_CHALLENGE_METHOD: S256
      OAUTH2_PROXY_COOKIE_SECURE: "true"

这版不带 set-xauthrequest(后端拿不到用户头,适合"只要挡住未登录"的场景)也不接 Redis(会话全在 cookie 里),够大多数个人用处。

可观测性与访问控制(它不发通知,但有这些)

先说清楚:oauth2-proxy 没有任何"登录推送告警"能力,别按系列其他项目的习惯等它喊你。它的"可观测性"是这几个:

  • 健康检查端点:/ping 返回 200(浅,只确认进程活着);/ready 返回 200 且确认底层连接(如 Redis)都通了(深)。挂到你的 Uptime Kuma(第 1 期)探这两个地址就行
  • Prometheus 指标:/metrics 默认关闭,设 OAUTH2_PROXY_METRICS_ADDRESS=:9090(或 0.0.0.0:9090)后暴露,可被 Prometheus / 你已有的监控抓。指标含认证成功/失败计数、上游响应延时等
  • 访问与认证日志:认证尝试、每次请求都走结构化日志(request-logging 默认开)。想排障把 auth-logging-format 调详细,show-debug-on-error 只建议在非生产排障时开(它会把错误详情打到页面,可能泄漏信息)
  • 谁进来了谁没进:放行逻辑本身即访问控制——
  • email-domain=* 放行所有登录邮箱;写具体域名(如 example.com)只放该域
  • authenticated-emails-file=/path/allow.txt(每行一个邮箱)做精确白名单,改文件滚动重启即生效
  • allowed-groups=admin,dev(OIDC 的 groups 声明)按组放行,适合"只让运维组进后台"
  • trusted-ip 放允许绕过认证的 IP/CIDR(⚠️ 有固有安全缺陷,务必配合 reverse-proxy + trusted-proxy-ip 正确配置,别裸开)

如果你确实想要"有人登录就推一条到手机":oauth2-proxy 做不到,但可以在 Nginx 层用 auth_request 成功后的日志 + fail2ban / 或直接在 IdP(Pocket ID)侧配登录通知来间接实现。别在 oauth2-proxy 上等这个功能。

反向代理与 HTTPS

中间件模式(1Panel 推荐,给已有网站加登录)——这是你 1Panel 机器上最贴合的用法。步骤:

  1. oauth2-proxy 按上面"中间件模式"跑在 127.0.0.1:4180(带 reverse-proxy + trusted-proxy-ip=127.0.0.1/32)
  2. 在 1Panel 里给 app.example.com 建网站、绑域名、上 Let's Encrypt,反向代理到 http://127.0.0.1:4180(注意:不是代理到你的后端,是代理到 oauth2-proxy 的认证端点)
  3. 编辑该网站的反代片段 /opt/1panel/www/sites/app.example.com/proxy/root.conf,把默认透传写法替换成下面这套(auth_request 标准写法):
# oauth2-proxy 的认证端点
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;
}
# auth_request 只问 /oauth2/auth:过=202,不过=401,不真正转发
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;
}
# 真正的业务流量:先过认证,401 就跳登录
location / {
    auth_request /oauth2/auth;
    error_page 401 = @oauth2_signin;

    # 把登录身份透传给后端(需 oauth2-proxy 开 set-xauthrequest)
    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;

    proxy_pass http://后端地址/;   # 你的真实 upstream,如 http://127.0.0.1:8080
}
# 401 时用 302 跳登录页(别用 error_page 401 =403,浏览器不跟 403 的 Location)
location @oauth2_signin {
    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}

⚠️ 官方文档特别强调:不要用 error_page 401 =403 /oauth2/sign_in 这种老写法——它返回 403 + Location,浏览器不会自动跟随,配合 skip-provider-button=true 时用户只会看到个"Found."链接。上面 @oauth2_signin 命名 location 返回标准 302,所有配置都正常。

反向代理模式(oauth2-proxy 自己当入口):把 OAUTH2_PROXY_HTTP_ADDRESS 设 0.0.0.0:4180、upstream 指向后端,1Panel 网站直接反代到 http://127.0.0.1:4180 即可,连 auth_request 那段都不用写。适合"一条 compose 给单个服务套壳"的轻量场景。

HTTPS 与 cookie:oauth2-proxy 默认不终止 TLS。生产环境让它待在已经终止 HTTPS 的反代后面,并保持 cookie-secure=true。如果是纯 HTTP 内网访问,必须 cookie-secure=false,否则 cookie 写不进、无限登录循环。

多段 cookie:大 OIDC token(如 Entra 的大 group 声明)会让会话 cookie 超过 4KB,oauth2-proxy 自动拆成 _oauth2_proxy + _oauth2_proxy_1。Nginx 默认只转发第一段 Set-Cookie,会导致丢会话。两个解法:① 上面 auth_request 写法里已经带了多段 cookie 提取逻辑(针对默认 cookie 名);② 更省事——session-store-type=redis,浏览器只存一个小 ticket。Redis 接法:

services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
    container_name: oauth2-proxy
    restart: unless-stopped
    ports:
      - "127.0.0.1:4180:4180"
    environment:
      # 把会话从 cookie 迁到 Redis,浏览器只留一个小 ticket
      OAUTH2_PROXY_SESSION_STORE_TYPE: redis
      OAUTH2_PROXY_REDIS_CONNECTION_URL: redis://redis:6379
      # 其余环境变量同上文(provider / client / cookie-secret / email-domain …)
      OAUTH2_PROXY_PROVIDER: oidc
      OAUTH2_PROXY_OIDC_ISSUER_URL: https://pocketid.example.com
      OAUTH2_PROXY_CLIENT_ID: 你的client_id
      OAUTH2_PROXY_CLIENT_SECRET: 你的client_secret
      OAUTH2_PROXY_COOKIE_SECRET: 32字节base64
      OAUTH2_PROXY_EMAIL_DOMAIN: "*"
      OAUTH2_PROXY_HTTP_ADDRESS: 127.0.0.1:4180
      OAUTH2_PROXY_REDIRECT_URL: https://app.example.com/oauth2/callback
      OAUTH2_PROXY_REVERSE_PROXY: "true"
      OAUTH2_PROXY_TRUSTED_PROXY_IP: 127.0.0.1/32
      OAUTH2_PROXY_UPSTREAM: static://202
      OAUTH2_PROXY_SKIP_PROVIDER_BUTTON: "true"
      OAUTH2_PROXY_CODE_CHALLENGE_METHOD: S256
      OAUTH2_PROXY_COOKIE_SECURE: "true"
  redis:
    image: redis:7-alpine
    container_name: oauth2-proxy-redis
    restart: unless-stopped
    # 会话是临时的,不需要持久化卷;重启最多让用户重新登录
    command: ["redis-server", "--save", "", "--appendonly", "no"]

踩坑清单

1. distroless 镜像没有 shell,exec 进不去 自 v7.6.0 起基础镜像从 Alpine 换成 distroless,镜像里没有 sh/bash,docker exec -it oauth2-proxy sh 会直接报 exec 失败。排障(看日志、改配置)要么看 docker logs,要么临时改用 -alpine 标签的镜像(带 busybox,有 wget,能进 shell)。同时因为没 curl/wget,容器级 healthcheck 在 distroless 上没法探 /ping——要么用 -alpine 标签写 wget -q -O- http://localhost:4180/ping,要么干脆不挂、用外部探活。

2. 默认只绑 127.0.0.1 镜像里 http-address 默认 127.0.0.1:4180。反向代理模式忘记设 0.0.0.0:4180 的话,容器外、宿主机其他进程都连不上 4180,现象是 Nginx 反代一直 502。这是第一个也是最常踩的坑。

3. cookie-secret 长度不对直接启动失败 cookie-secret 必须能 base64 解出 16 / 24 / 32 字节,否则启动报 "cookie_secret must be 16, 24, or 32 bytes"。别用随便一句中文或短密码凑数,用上面给的 secrets.token_bytes(32) 生成。

4. email-domain 不填起不来 校验逻辑:当 authenticated-emails-file、email-domain、htpasswd-file 三个都为空时报 "missing setting for email validation"。哪怕用 OIDC,也得至少给 email-domain=*(放行所有)或具体的名单文件。

5. redirect-url 必须和 IdP 回调地址逐字符一致 登录最后一步回调 https://域名/oauth2/callback,IdP 后台登记的回调 URI 必须和它完全一样(协议、域名、路径、有没有末尾斜杠)。不一致直接被 IdP 拒绝,报 redirect_uri_mismatch 之类。

6. reverse-proxy 模式忘记设 trusted-proxy-ip 有绕过风险 开了 reverse-proxy=true 却把 trusted-proxy-ip 留空,等于"信任所有能连上来的 IP 设置的 X-Forwarded-For"——攻击者可以伪造头冒充可信代理、甚至伪造客户端 IP 绕过 trusted-ip 白名单。守门员模式务必 trusted-proxy-ip=127.0.0.1/32(或你反代的真实 IP/CIDR)。

7. cookie-secure 与协议不匹配 → 无限登录循环 HTTPS 站点 + cookie-secure=false:cookie 被浏览器拒绝(混合内容/secure 策略),每次请求都当未登录 → 无限跳登录。反过来纯 HTTP 内网 + cookie-secure=true:cookie 写不进,同样无限循环。对齐两者。

8. PKCE 不开,现代 IdP 注册可能失败 OIDC 下建议显式 code-challenge-method=S256。Pocket ID、Authelia 这类现代 IdP 通常要求 PKCE,不开时授权请求会被拒。

9. 大 token 多段 cookie 丢会话 见上一节"多段 cookie"。解法:Nginx 多段提取(上面写法已含),或 session-store-type=redis。

10. 镜像只在 quay.io,没有 Docker Hub / GHCR 别去 Docker Hub 搜 oauth2-proxy/oauth2-proxy(非官方/可能滞后),认准 quay.io/oauth2-proxy/oauth2-proxy。国内直连 quay.io 一般没问题;拉不动就走代理或 podman pull 后 docker load。nightly 标签是 master 每晚构建,官方不建议生产用。

备份

oauth2-proxy 默认无状态:会话在用户浏览器 cookie 里、配置在你手里、没有数据库要备。真正需要备份的只有两样:

  • 配置文件 /etc/oauth2-proxy.cfg(如果你用文件而非环境变量)——这就是全部"状态"
  • client 凭证与 cookie-secret:client-secret 和 cookie-secret 建议你用密码管理器/密文管理单独存一份。cookie-secret 丢了只是全员掉登录(重新登录即可),但别和配置一起明文落盘到随手可得的地方

如果用的是 session-store-type=redis,那 Redis 里的会话 ticket 是临时的(用户退出/过期即失效),不需要备份——丢了最多让在线用户重新登录,不影响长期数据。比起系列里 Scrutiny(要备 SQLite+InfluxDB)、Kopia(备仓库)这种,oauth2-proxy 的备份负担几乎为零,这也是它适合当"门卫"的好处之一。

小结

适合谁

  • 有一堆裸奔自托管服务、又不想给每个单独接 OAuth 的人:Scrutiny(第 24 期)、Dozzle(第 22 期)、Homepage(第 18 期)、Kopia(第 21 期)、ntfy(第 13 期)、Miniflux(第 12 期)、linkding(第 15 期)都能一键套壳
  • 已经按第 20 期起了 Pocket ID 的人:oauth2-proxy 直接当它的"门卫",一套身份管全站
  • 已经在用 Nginx/1Panel(OpenResty)的人:auth_request 模式接入成本极低,几行反代片段搞定
  • 想给内网服务做"外网可访问但必须登录"的人:比塞 VPN、比逐个配 Basic Auth 都优雅

不适合谁

  • 想要"自建用户系统/注册登录页"的:它是门卫不是 IdP,账号体系得另起(Authentik / Pocket ID)
  • 想要"有人登录就推手机通知"的:它没有这功能,别等(用 IdP 侧通知或 Nginx 日志 + 监控间接实现)
  • 不想碰 OAuth/OIDC 概念、连 client-id 都不想注册的人:它的前提就是你得有一个 IdP。纯内网图省事,直接用 1Panel 的密码访问或 VPN 更合适
  • 指望它做 WAF / 限速 / 细粒度授权的:职责之外

一句话总结:Pocket ID(第 20 期)管"你是谁",oauth2-proxy 管"你进不进得来"。把第 20 期的身份和第 25 期的门卫拼起来,前面 24 期那些裸奔的服务,才算真正关进了有锁的屋里。

项目地址