# 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 ""`): ```nginx 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 端点)。 ## 3. 鉴权源:Bearer / Cookie / 都行 `iap_identity()` 识别顺序(`oauth.rs` 中的 `iap_identity` 函数): | 来源 | 触发 | 典型场景 | |---|---|---| | `Authorization: Bearer ` | HTTP 头 | 第三方 API / SPA / 移动端 | | `Cookie: sso_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) ```bash # ① 拿一个 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:30089/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 auth_email=admin@yourdomain.com auth_groups=admin ``` 下游后端 `request.headers`: ```json { "X-Auth-User": "admin", "X-Auth-Sub": "admin", "X-Auth-Email": "admin@yourdomain.com", "X-Auth-Groups": "admin", "X-Auth-Token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0xIi..." } ``` ## 6. 踩过的坑(来自实测) 0. **`sso_iap` 只设 nginx 变量不自动注头**(2026-10-12 v0.7.22 实测踩):sso_iap 验签后把身份写进 `$auth_user/$auth_email/...` nginx 变量,但**不会**自动给 `proxy_pass` 出去的请求加 `X-Auth-*` 头。必须每个 sso_iap location 显式: ```nginx 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 拼到了请求上)。 1. **`/oauth/token` 返回的是 `{code,data,msg}` 信封**——下游用 `access_token` 字段取 会取到 `data` 那个对象。改用 `/oauth/v20/token`(MaxKey 兼容端点,裸 OAuth2 响应)。 2. **shm/disk 不一致**:`active.jwk.json` 落盘但 pod 内存里可能已经有新 kid(admin 操作触发过 key 轮换时发生)。表现:access_token 的 `kid` 与磁盘上的不一致, 其他实例的 .so 验签失败 → IAP 返回 401。**修复:先 `curl IdP/oauth/jwks` 拿当前 公钥,覆盖磁盘 jwks,重启 pod**。 3. **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)。 4. **JWKS 私钥分量**:`active.jwk.json` 必须含 `d`/`p`/`q` 等私钥分量,模块 init 阶段会拒收纯公钥 JWKS(`缺少私钥分量`),即使 IAP 只需要验签。 解决:自建一份带私钥的 JWK 用作演示。 5. **cookie 跨实例**:sso_sid 在 pod A 上有效,pod B 不认识(shm 不共享)。 IAP 端必须和签发 sso_sid 的 IdP **同实例**才能走 cookie 路径。 6. **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-* 注入头)