Files
sso/docs/iap.md
adminandClaude Opus 4.8 6b323c1e64 docs: 修正 ipass-sso NodePort 30082 → 30089
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]>
2026-10-12 11:49:59 +08:00

177 lines
8.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-* 注入头)