From 1d984181b572377b7684a6e6918864b05c0d6ec2 Mon Sep 17 00:00:00 2001 From: admin Date: Fri, 9 Oct 2026 21:40:09 +0800 Subject: [PATCH] =?UTF-8?q?docs(iap):=20IAP=20(Identity-Aware=20Proxy)=20?= =?UTF-8?q?=E6=8E=A5=E5=85=A5=E6=8C=87=E5=8D=97=20+=20=E6=BC=94=E7=A4=BA?= =?UTF-8?q?=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/iap-demo/backend.py | 58 +++++++++++ docs/iap-demo/nginx.conf.template | 60 +++++++++++ docs/iap-demo/sample-response.html | 27 +++++ docs/iap.md | 161 +++++++++++++++++++++++++++++ 4 files changed, 306 insertions(+) create mode 100644 docs/iap-demo/backend.py create mode 100644 docs/iap-demo/nginx.conf.template create mode 100644 docs/iap-demo/sample-response.html create mode 100644 docs/iap.md diff --git a/docs/iap-demo/backend.py b/docs/iap-demo/backend.py new file mode 100644 index 0000000..a09cfee --- /dev/null +++ b/docs/iap-demo/backend.py @@ -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"""{title} +

IAP Demo Backend :18200

{body}""" + + +@app.route("/", defaults={"p": ""}) +@app.route("/") +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 = '✓ IAP 已注入身份' if identity_injected else '✗ IAP 未注入(未授权或未配置)' + + body = f""" +

{badge}   请求路径: /{p}

+

1) 身份总结(X-Auth-* 头)

+{''.join(f'' for k, v in summary.items())}
{k}{v}
+

2) 完整请求头(Flask request.headers)

+
{json.dumps(all_headers, indent=2, ensure_ascii=False)}
+""" + 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) diff --git a/docs/iap-demo/nginx.conf.template b/docs/iap-demo/nginx.conf.template new file mode 100644 index 0000000..06c98e1 --- /dev/null +++ b/docs/iap-demo/nginx.conf.template @@ -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"; + } + } +} diff --git a/docs/iap-demo/sample-response.html b/docs/iap-demo/sample-response.html new file mode 100644 index 0000000..f222e92 --- /dev/null +++ b/docs/iap-demo/sample-response.html @@ -0,0 +1,27 @@ +IAP echo +

IAP Demo Backend :18200

+

✓ IAP 已注入身份   请求路径: /iap-demo/whoami

+

1) 身份总结(X-Auth-* 头)

+
X-Auth-Useradmin
X-Auth-Subadmin
X-Auth-Emailadmin@yourdomain.com
X-Auth-Groupsadmin
X-Auth-TokeneyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0x…
+

2) 完整请求头(Flask request.headers)

+
{
+  "Host": "127.0.0.1",
+  "X-Auth-User": "admin",
+  "X-Auth-Sub": "admin",
+  "X-Auth-Email": "admin@yourdomain.com",
+  "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"
+}
diff --git a/docs/iap.md b/docs/iap.md new file mode 100644 index 0000000..d5105dd --- /dev/null +++ b/docs/iap.md @@ -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 ` | HTTP 头 | 第三方 API / SPA / 移动端 | +| `Cookie: sso_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 auth_email=admin@yourdomain.com auth_groups=admin +``` + +下游后端 `request.headers`: + +```json +{ + "X-Auth-User": "admin", + "X-Auth-Sub": "admin", + "X-Auth-Email": "admin@yourdomain.com", + "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-* 注入头)