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]>
177 lines
8.3 KiB
Markdown
177 lines
8.3 KiB
Markdown
# 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 <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)
|
||
|
||
```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 [email protected] auth_groups=admin
|
||
```
|
||
|
||
下游后端 `request.headers`:
|
||
|
||
```json
|
||
{
|
||
"X-Auth-User": "admin",
|
||
"X-Auth-Sub": "admin",
|
||
"X-Auth-Email": "[email protected]",
|
||
"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-* 注入头)
|