docs(iap): IAP (Identity-Aware Proxy) 接入指南 + 演示文件

- docs/iap.md 写清 3 段配置 + 5 个 X-Auth-* 头 + Bearer/Cookie 双源 + 6 个踩坑
- docs/iap-demo/ 留 nginx.conf.template 与回显 backend.py,可复用

实测: ipass-sso-v0.7.0 .so 加载自签 RSA key,挂到 30089 端口
      /iap-demo/ 走 sso_iap on; 注入 X-Auth-User/Sub/Email/Groups/Token

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-09 21:40:09 +08:00
1 parent 534632e1a8
commit 1d984181b5
4 files changed
+306

No files matched your search

+58
View File
@@ -0,0 +1,58 @@
#!/usr/bin/env python3
"""
IAP Demo Backend — 回显所有收到的请求头,让 IAP 注入的 X-Auth-* 头肉眼可见。
"""
import json
import sys
from flask import Flask, request
app = Flask(__name__)
def page(title, body):
return f"""<!doctype html><meta charset=utf-8><title>{title}</title>
<style>body{{font-family:ui-monospace,Menlo,monospace;padding:20px;max-width:1100px}}
pre{{background:#0f172a;color:#e2e8f0;padding:14px;border-radius:8px;overflow:auto}}
h2{{margin-top:24px}}
.tag{{display:inline-block;padding:2px 8px;border-radius:4px;background:#dcfce7;color:#166534;font-size:12px}}
.auth{{background:#fef3c7;color:#92400e}}
.iam{{background:#dbeafe;color:#1e3a8a}}
table{{border-collapse:collapse;width:100%}}
td{{padding:4px 10px;border-bottom:1px solid #1e293b;font-family:ui-monospace,monospace}}
td.k{{color:#94a3b8;width:280px}}
</style><body><h1>IAP Demo Backend <span class=tag>:18200</span></h1>{body}"""
@app.route("/", defaults={"p": ""})
@app.route("/<path:p>")
def echo(p):
# 重点:把所有 X-Auth-* 头挑出来 + 全部 headers
auth_headers = {k: v for k, v in request.headers.items() if k.lower().startswith("x-auth-")}
all_headers = dict(request.headers)
# 身份总结
summary = {
"X-Auth-User": auth_headers.get("X-Auth-User", "(missing)"),
"X-Auth-Sub": auth_headers.get("X-Auth-Sub", "(missing)"),
"X-Auth-Email": auth_headers.get("X-Auth-Email", "(missing)"),
"X-Auth-Groups": auth_headers.get("X-Auth-Groups", "(missing)"),
"X-Auth-Token": (auth_headers.get("X-Auth-Token", "(missing)")[:48] + "…") if auth_headers.get("X-Auth-Token") else "(missing)",
}
# 关键判定
identity_injected = bool(auth_headers.get("X-Auth-User"))
badge = '<span class=tag>✓ IAP 已注入身份</span>' if identity_injected else '<span class=tag style="background:#fee2e2;color:#991b1b">✗ IAP 未注入(未授权或未配置)</span>'
body = f"""
<p>{badge} &nbsp; 请求路径: <code>/{p}</code></p>
<h2>1) 身份总结(X-Auth-* 头)</h2>
<table>{''.join(f'<tr><td class=k>{k}</td><td>{v}</td></tr>' for k, v in summary.items())}</table>
<h2>2) 完整请求头(Flask request.headers)</h2>
<pre>{json.dumps(all_headers, indent=2, ensure_ascii=False)}</pre>
"""
return page("IAP echo", body)
if __name__ == "__main__":
print(f"[iap-backend] listening on http://127.0.0.1:18200", file=sys.stderr)
app.run(host="127.0.0.1", port=18200, debug=False)
+60
View File
@@ -0,0 +1,60 @@
worker_processes 1;
error_log /dev/stderr info;
pid /tmp/nginx/nginx.pid;
load_module /usr/local/nginx/modules/libipass_sso_gateway.so;
env OAUTH_SIGNING_SECRET;
env OAUTH_ISSUER;
env OAUTH_COOKIE_DOMAIN;
events {
worker_connections 1024;
}
http {
include /usr/local/nginx/conf/mime.types;
default_type application/json;
sendfile on;
keepalive_timeout 65;
client_body_temp_path /tmp/nginx/client_body;
proxy_temp_path /tmp/nginx/proxy;
log_format iapfmt '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent '
'auth_user=$auth_user auth_sub=$auth_sub '
'auth_email=$auth_email auth_groups=$auth_groups';
access_log /dev/stdout iapfmt;
ipass_state state 16m;
ipass_data_dir /usr/local/nginx/data;
server {
listen 30089;
server_name _;
location = /healthz {
return 200 "ok\n";
}
location /iap-demo/ {
sso_iap on;
proxy_pass http://host.docker.internal:18200;
proxy_set_header Host $host;
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;
proxy_set_header X-Original-URI $request_uri;
error_page 401 = @oauth_login;
}
location @oauth_login {
return 302 "http://192.168.1.26:30082/oauth/authorize?client_id=app-crm&redirect_uri=http%3A%2F%2F127.0.0.1%3A18101%2Fcallback&response_type=code&scope=openid+profile+email&state=iap_demo";
}
}
}
+27
View File
@@ -0,0 +1,27 @@
<!doctype html><meta charset=utf-8><title>IAP echo</title>
<style>body{font-family:ui-monospace,Menlo,monospace;padding:20px;max-width:1100px}
pre{background:#0f172a;color:#e2e8f0;padding:14px;border-radius:8px;overflow:auto}
h2{margin-top:24px}
.tag{display:inline-block;padding:2px 8px;border-radius:4px;background:#dcfce7;color:#166534;font-size:12px}
.auth{background:#fef3c7;color:#92400e}
.iam{background:#dbeafe;color:#1e3a8a}
table{border-collapse:collapse;width:100%}
td{padding:4px 10px;border-bottom:1px solid #1e293b;font-family:ui-monospace,monospace}
td.k{color:#94a3b8;width:280px}
</style><body><h1>IAP Demo Backend <span class=tag>:18200</span></h1>
<p><span class=tag>✓ IAP 已注入身份</span> &nbsp; 请求路径: <code>/iap-demo/whoami</code></p>
<h2>1) 身份总结(X-Auth-* 头)</h2>
<table><tr><td class=k>X-Auth-User</td><td>admin</td></tr><tr><td class=k>X-Auth-Sub</td><td>admin</td></tr><tr><td class=k>X-Auth-Email</td><td>[email protected]</td></tr><tr><td class=k>X-Auth-Groups</td><td>admin</td></tr><tr><td class=k>X-Auth-Token</td><td>eyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0x…</td></tr></table>
<h2>2) 完整请求头(Flask request.headers)</h2>
<pre>{
"Host": "127.0.0.1",
"X-Auth-User": "admin",
"X-Auth-Sub": "admin",
"X-Auth-Email": "[email protected]",
"X-Auth-Groups": "admin",
"X-Auth-Token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0xIiwidHlwIjoiSldUIn0.eyJhdWQiOiJhcHAtY3JtIiwiY2xpZW50X2lkIjoiYXBwLWNybSIsImRlcGFydG1lbnQiOiJcdTVlNzNcdTUzZjAiLCJlbWFpbCI6ImFkbWluQHlvdXJkb21haW4uY29tIiwiZXhwIjoxNzkxNTU2NzMyLCJncm91cHMiOlsiYWRtaW4iXSwiaWF0IjoxNzkxNTUzMTMyLCJpc3MiOiJodHRwOi8vMTkyLjE2OC4xLjI2OjMwMDgyIiwianRpIjoiaWFwLWRlbW8tMDAxIiwibW9iaWxlIjoiIiwibmFtZSI6Ilx1N2JhMVx1NzQwNlx1NTQ1OCIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCIsInN1YiI6ImFkbWluIiwidG9rZW5fdHlwZSI6ImFjY2VzcyJ9.RoGeQU9H1EXDSCd-K1oO8xFsBRA_UklKpix479VJHzXGDYdOjb-un4GPpN5gqKtbKccvntxpFDiVFJhBHN64AGbTt9lpiSW5cKFWCzH5nBkEbmnYGsjEmlGRX7vvkHDEbpyhFw5ahddgVutHVuyQvDQFw_I8vIdBMPgDeqCwDIx2Tt6ZeYWixEijCJXCBovtG0xcFq0QaEA_Ml4XKBqNzSpZ-dxBPz2W0YHeLTWXfKVxpGX1m9kCvaMKcId6WdRobGjm-H48rWUwOb27cRPJpcy3Kp-ryKJVDyhdOBA_LUuBLibLJIky5Q6LbkQJe_Lxva0ZFlio5rLBVyYPqIEMBQ",
"X-Original-Uri": "/iap-demo/whoami",
"User-Agent": "curl/8.7.1",
"Accept": "*/*",
"Authorization": "Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0xIiwidHlwIjoiSldUIn0.eyJhdWQiOiJhcHAtY3JtIiwiY2xpZW50X2lkIjoiYXBwLWNybSIsImRlcGFydG1lbnQiOiJcdTVlNzNcdTUzZjAiLCJlbWFpbCI6ImFkbWluQHlvdXJkb21haW4uY29tIiwiZXhwIjoxNzkxNTU2NzMyLCJncm91cHMiOlsiYWRtaW4iXSwiaWF0IjoxNzkxNTUzMTMyLCJpc3MiOiJodHRwOi8vMTkyLjE2OC4xLjI2OjMwMDgyIiwianRpIjoiaWFwLWRlbW8tMDAxIiwibW9iaWxlIjoiIiwibmFtZSI6Ilx1N2JhMVx1NzQwNlx1NTQ1OCIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCIsInN1YiI6ImFkbWluIiwidG9rZW5fdHlwZSI6ImFjY2VzcyJ9.RoGeQU9H1EXDSCd-K1oO8xFsBRA_UklKpix479VJHzXGDYdOjb-un4GPpN5gqKtbKccvntxpFDiVFJhBHN64AGbTt9lpiSW5cKFWCzH5nBkEbmnYGsjEmlGRX7vvkHDEbpyhFw5ahddgVutHVuyQvDQFw_I8vIdBMPgDeqCwDIx2Tt6ZeYWixEijCJXCBovtG0xcFq0QaEA_Ml4XKBqNzSpZ-dxBPz2W0YHeLTWXfKVxpGX1m9kCvaMKcId6WdRobGjm-H48rWUwOb27cRPJpcy3Kp-ryKJVDyhdOBA_LUuBLibLJIky5Q6LbkQJe_Lxva0ZFlio5rLBVyYPqIEMBQ"
}</pre>
+161
View File
@@ -0,0 +1,161 @@
# 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: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`:
```json
{
"X-Auth-User": "admin",
"X-Auth-Sub": "admin",
"X-Auth-Email": "[email protected]",
"X-Auth-Groups": "admin",
"X-Auth-Token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0xIi..."
}
```
## 6. 踩过的坑(来自实测)
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-* 注入头)