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:
1 parent
534632e1a8
commit
1d984181b5
4 files changed
+306
No files matched your search
@@ -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} 请求路径: <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)
|
||||
@@ -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";
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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> 请求路径: <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
@@ -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-* 注入头)
|
||||
Reference in new issue
Block a user