ipass-sso 已于 2026-10-12 迁到 NodePort 30089,nginx.conf / CLAUDE.md / iap.md 仍写 30082,按旧端口排查会打错节点。 deploy/k8s/ipass-sso.yaml 与 2026-10-09 spec 已是 30089,仅保留其 历史沿革说明。 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
8.3 KiB
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 端点)。
3. 鉴权源:Bearer / Cookie / 都行
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: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 [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. 踩过的坑(来自实测)
-
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 拼到了请求上)。 -
/oauth/token返回的是{code,data,msg}信封——下游用access_token字段取 会取到data那个对象。改用/oauth/v20/token(MaxKey 兼容端点,裸 OAuth2 响应)。 -
shm/disk 不一致:
active.jwk.json落盘但 pod 内存里可能已经有新 kid(admin 操作触发过 key 轮换时发生)。表现:access_token 的kid与磁盘上的不一致, 其他实例的 .so 验签失败 → IAP 返回 401。修复:先curl IdP/oauth/jwks拿当前 公钥,覆盖磁盘 jwks,重启 pod。 -
Elf/Mach-O:从 K8s pod 抽
.so到本机 macOS 跑不通——.so是 Linux ELF, macOS nginxdlopen报slice is not valid mach-o file。演示必须用 Linux nginx(同版本 1.30.4,从 K8s 镜像里抠 nginx 二进制 + 加载 .so,或直接用 Dockercrpi-.../ssw188/nginx:ipass-sso-v0.7.0跑 + 挂载自定义 conf)。 -
JWKS 私钥分量:
active.jwk.json必须含d/p/q等私钥分量,模块 init 阶段会拒收纯公钥 JWKS(缺少私钥分量),即使 IAP 只需要验签。 解决:自建一份带私钥的 JWK 用作演示。 -
cookie 跨实例:sso_sid 在 pod A 上有效,pod B 不认识(shm 不共享)。 IAP 端必须和签发 sso_sid 的 IdP 同实例才能走 cookie 路径。
-
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-* 注入头)