Files
sso/docs/iap.md
T
adminandClaude Code ddc396c992 fix(iap): 4 处 IAP location 补 X-Auth-* 注头 + 文档同步 (v0.7.22)
影响:sso_iap 验签后只设 $auth_* nginx 变量, 不会自动给 proxy_pass 请求加
X-Auth-User 等 5 个头. v0.7.22 前 4 处 IAP location 全部漏, demo app 读
X-Auth-User 拿到空字符串; nginx access log 显示 auth_user=admin ≠ 头已注.
补 5 行后下游 request.headers 正常, /me 端到端返用户身份.

改动:
- deploy/nginx.conf:/proxy/app-crm/{callback,/} + /proxy/app-mobile/{callback,/}
  四段 IAP location 各加 5 行 proxy_set_header X-Auth-* $auth_*.
- deploy/k8s/ipass-sso.yaml:镜像 tag v0.7.21 → v0.7.22; 头部注释记录此坑.
- docs/iap.md §6 坑列表加 #0, 附 5 行注头示例 + 解释 access log 误导.
- docs/integrate-with-iap.md §2.2 注释提醒(不照搬 4 段示例避免冗长);
  §6 ipass-sso 端 checklist + 失败排查表各加一条.

设计:sso_iap 注头责任全在 nginx.conf(不打算让 sso 插件自动改请求头——
保持 $auth_* 变量语义纯粹, 不想动就 $auth_* 直接用; 想要头自己
proxy_set_header, 跟 $arg_XXX / $http_XXX 风格一致).

Co-Authored-By: Claude Code <[email protected]>
2026-10-12 10:52:01 +08:00

8.3 KiB
Raw Blame History

ipass-sso IAP(Identity-Aware Proxy)接入指南

SSO 不只做 IdP,还能在 nginx 接入层做「身份识别 + 反向代理」:访问被保护的后端 应用时,sso 插件从 Authorization Bearer 或 sso_sid cookie 读出身份,注入 X-Auth-* 头给下游。下游应用不用自己实现登录跳转、不用存 session,只看头就知道 你是谁。

1. 一张图

                      ┌──────────────┐
                      │  ipass-sso   │  ← ① 没有 Bearer/sso_sid?
   客户端 ─── HTTP ──→│  nginx + .so │       302 + WWW-Authenticate → IdP /login
                      │  (sso_iap)   │  ← ② 有了之后:JWT 验签 → 抽 sub/email/groups
                      └──────┬───────┘       写 $auth_user/$auth_sub/... nginx 变量
                             │
                             │ proxy_pass + proxy_set_header X-Auth-* $auth_*
                             ▼
                      ┌──────────────┐
                      │  上游后端    │  读 request.headers["X-Auth-User"] 就能识别用户
                      │  (任意语言)  │
                      └──────────────┘

2. nginx 接入:3 段配置

最小可用配置(生产里全开 SSL、加 proxy_http_version 1.1 与 proxy_set_header Connection ""):

http {
    # 模块已注册 4 条指令(gateway/src/lib.rs)
    ipass_state    state 16m;                 # main: 共享内存 zone
    ipass_data_dir /usr/local/nginx/data;     # main: 落盘 JSON + jwks 所在目录

    upstream my_app {
        server 127.0.0.1:8080;                # 上游后端
    }

    server {
        listen 443 ssl;
        server_name app.example.com;

        location / {
            sso_iap on;                       # loc: 开启 IAP

            proxy_pass http://my_app;

            # 把身份变量注入到下游请求头(变量名固定,见 §4)
            proxy_set_header X-Auth-User   $auth_user;
            proxy_set_header X-Auth-Sub    $auth_sub;
            proxy_set_header X-Auth-Email  $auth_email;
            proxy_set_header X-Auth-Groups $auth_groups;
            proxy_set_header X-Auth-Token  $auth_token;

            # 401 走登录页
            error_page 401 = @oauth_login;
        }

        location @oauth_login {
            # 跳到 IdP 的 /login(login 页面登录后回跳回原 URL)
            return 302 "https://sso.example.com/login?redirect=$scheme://$host$request_uri";
        }
    }
}

硬约定(漏一条即失效):

  • 必须在 main 上下文里写 ipass_state + ipass_data_dir——模块拿不到 zone 就 500。
  • 必须在要保护的 location 里写 sso_iap on;,否则 $auth_* 全空,下游拿到 X-Auth-User: ""。
  • $auth_* 变量只在 sso_iap on; 的 location 范围内有值;server 级别用是空的。
  • 401 跳登录:error_page 401 = @oauth_login; 必须挂在 sso_iap 那个 location 上, 不要写 server 级(会同时作用到非 IAP 端点)。

iap_identity() 识别顺序(oauth.rs 中的 iap_identity 函数):

来源 触发 典型场景
Authorization: Bearer <jwt> HTTP 头 第三方 API / SPA / 移动端
Cookie: sso_sid=<sid> HTTP 头 浏览器访问反代出来的 Web 应用
都没有 — 401 → 走 error_page 401 = @oauth_login;

⚠️ Cookie 路径只对同实例有效:sso_sid 是进程内 shm 里的会话键,跨实例不共享。 要多个 nginx 实例共用 cookie 路径,必须先把 shm 切到共享内存后端(暂未实现)。 Bearer 路径天然跨实例——只要所有实例的 jwks 一致,JWT 自带可验签信息。

4. 注入的下游头

nginx 变量 注入头 来源
$auth_user X-Auth-User JWT preferred_username(或 sub)
$auth_sub X-Auth-Sub JWT sub
$auth_email X-Auth-Email JWT email
$auth_groups X-Auth-Groups JWT groups(数组 → 逗号串)
$auth_token X-Auth-Token 原始 Bearer(或基于 sso 会话新签发的 JWT)

⚠️ 可信边界:$auth_* 只在经过本 nginx 的请求上可信。如果上游后端能被客户端 直连(绕过 nginx),那任何人都能伪造 X-Auth-User: admin。生产里上游必须 firewall 隔离或绑定 127.0.0.1。

5. 端到端验证(已实测,2026-10-09 v0.7.0 .so + v0.7.9 签发的 token)

# ① 拿一个 access_token(OIDC 授权码 → v20/token;/oauth/token 返回的是信封不是裸 token)
TOK=$(curl -s -X POST -u 'app-crm:cs_crm_simulated_secret_2026' \
  -d "grant_type=authorization_code&code=$CODE&redirect_uri=$REDIRECT_URI" \
  http://192.168.1.26:30082/oauth/v20/token | jq -r .access_token)

# ② 访问 IAP 端点
curl -i -H "Authorization: Bearer $TOK" http://127.0.0.1:30089/iap-demo/whoami

观察 nginx access log:

GET /iap-demo/whoami HTTP/1.1" 200 3238
auth_user=admin auth_sub=admin [email protected] auth_groups=admin

下游后端 request.headers:

{
  "X-Auth-User":   "admin",
  "X-Auth-Sub":    "admin",
  "X-Auth-Email":  "[email protected]",
  "X-Auth-Groups": "admin",
  "X-Auth-Token":  "eyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0xIi..."
}

6. 踩过的坑(来自实测)

  1. sso_iap 只设 nginx 变量不自动注头(2026-10-12 v0.7.22 实测踩):sso_iap 验签后把身份写进 $auth_user/$auth_email/... nginx 变量,但不会自动给 proxy_pass 出去的请求加 X-Auth-* 头。必须每个 sso_iap location 显式:

    proxy_set_header X-Auth-User   $auth_user;
    proxy_set_header X-Auth-Email  $auth_email;
    proxy_set_header X-Auth-Groups $auth_groups;
    proxy_set_header X-Auth-Sub    $auth_sub;
    proxy_set_header X-Auth-Token  $auth_token;
    

    漏了之后表现是:sso_iap 验签通过、请求 200 到下游,但下游 request.headers 看不到 X-Auth-*(demo app 读 X-Auth-User 拿到空字符串)。nginx access log 里 auth_user=admin ≠ 头已注(access log 直接读 nginx 变量,不代表 proxy_set_header 拼到了请求上)。

  2. /oauth/token 返回的是 {code,data,msg} 信封——下游用 access_token 字段取 会取到 data 那个对象。改用 /oauth/v20/token(MaxKey 兼容端点,裸 OAuth2 响应)。

  3. shm/disk 不一致:active.jwk.json 落盘但 pod 内存里可能已经有新 kid(admin 操作触发过 key 轮换时发生)。表现:access_token 的 kid 与磁盘上的不一致, 其他实例的 .so 验签失败 → IAP 返回 401。修复:先 curl IdP/oauth/jwks 拿当前 公钥,覆盖磁盘 jwks,重启 pod。

  4. Elf/Mach-O:从 K8s pod 抽 .so 到本机 macOS 跑不通——.so 是 Linux ELF, macOS nginx dlopen 报 slice is not valid mach-o file。演示必须用 Linux nginx(同版本 1.30.4,从 K8s 镜像里抠 nginx 二进制 + 加载 .so,或直接用 Docker crpi-.../ssw188/nginx:ipass-sso-v0.7.0 跑 + 挂载自定义 conf)。

  5. JWKS 私钥分量:active.jwk.json 必须含 d/p/q 等私钥分量,模块 init 阶段会拒收纯公钥 JWKS(缺少私钥分量),即使 IAP 只需要验签。 解决:自建一份带私钥的 JWK 用作演示。

  6. cookie 跨实例:sso_sid 在 pod A 上有效,pod B 不认识(shm 不共享)。 IAP 端必须和签发 sso_sid 的 IdP 同实例才能走 cookie 路径。

  7. is_safe_redirect 拒 host:port:oauth.rs:1468-1499 用 .ends_with(&cookie_domain) 检查,URL 带端口(https://app.example.com:8443/...)会被判为「跨域跳转」拒绝。 跑 error_page 401 跳登录时 redirect= 拼的是 $scheme://$host$request_uri → 含端口 → 拒绝。生产用 443/80 标准端口规避,或修 is_safe_redirect。

7. 演示文件

docs/iap-demo/ 留了可复用 demo:

  • nginx.conf.template — 本地 IAP nginx 配置(listen 30089,避开 K8s 节点)
  • backend.py — Flask 回显服务,echo 所有 X-Auth-* 头到页面
  • sample-response.html — 实测抓回的页面(含 5 个 X-Auth-* 注入头)