From 8b8562dff1f45eca6994e9f83fa474de942f6784 Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 10 Oct 2026 18:24:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(iap):=20=E5=AE=8C=E6=95=B4=E9=9B=86?= =?UTF-8?q?=E6=88=90=E6=8C=87=E5=8D=97=20(app-crm=20=E4=B8=BA=E4=BE=8B,=20?= =?UTF-8?q?=E5=90=AB=20WeChat=20Work=20=E6=8E=A5=E5=85=A5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 覆盖: - 架构一图 (企微工作台 → ipass-sso IAP → app) - ipass-sso 端 3 处配置 (oauth_clients / nginx.conf / WXWORK env) - app 端 3 个 env + 4 条硬规则 (Flask 路由 /HTML 字符串 /Flask redirect) - /callback 端点 OAuth dance 模板 (/oauth/v20/token + Basic Auth) - 部署拓扑 (OrbStack / 跨机 / K8s 反例) - 5 步端到端验证 - AI 快速集成 checklist (按概率排序的失败排查) - 100 行最小可运行 app-crm 模板 关键规则: HTML href/action/src 必须带 BASE, Flask redirect() 不能带 BASE, nginx proxy_redirect 必须是正则, Flask 路由不能带 /proxy 前缀。 Co-Authored-By: Claude Code --- docs/integrate-with-iap.md | 490 +++++++++++++++++++++++++++++++++++++ 1 file changed, 490 insertions(+) create mode 100644 docs/integrate-with-iap.md diff --git a/docs/integrate-with-iap.md b/docs/integrate-with-iap.md new file mode 100644 index 0000000..f2c0432 --- /dev/null +++ b/docs/integrate-with-iap.md @@ -0,0 +1,490 @@ +# ipass-sso IAP 集成指南(企业微信工作台场景) + +> 把任意 Web app 接入 ipass-sso 的「Identity-Aware Proxy」+「WeChat Work 工作台」: +> 用户在企微工作台点应用图标 → 自动 OAuth → 进 app。**app 永远不需要公网 IP/域名**, +> 所有流量走 ipass-sso 反代。 + +适用场景:iPhone 企微工作台 / PC 企微工作台 / 任何浏览器访问受保护的内部应用。 + +--- + +## 1. 架构(一图) + +``` + ┌─────────────────────────────────────┐ + │ WeChat Work (企业微信) │ + 用户点工作台图标 ───→ │ https://work.weixin.qq.com/... │ + │ "应用主页" = https://idp/proxy/app/ │ + └─────────────┬───────────────────────┘ + │ 302 → IdP /oauth/authorize + ▼ + ┌─────────────────────────────────────┐ + │ ipass-sso (idp.example.com:88) │ + ─────────────────────→│ nginx + libipass_sso_gateway.so │ + │ │ + ① 无 sso_sid → 401 ──→│ /proxy/app-crm/ │ sso_iap on; + ② 兜底跳 /portal/ │ ↓ sso_iap 鉴权 + 注 X-Auth-* │ error_page 401 + wxwork/login │ ↓ proxy_pass │ + │ ↓ sub_filter (无, demo 自加) │ + └──────┬──────────────────────────────┘ + │ X-Auth-User: alice + │ X-Auth-Token: eyJ... + ▼ + ┌─────────────────────────────────────┐ + │ app-crm (Mac 本机 127.0.0.1:18101) │ + │ Flask + Python │ + │ 只需要读 X-Auth-User 就知道是谁 │ + │ 不需要公网 / 不需要处理 OAuth dance │ + └─────────────────────────────────────┘ +``` + +**关键事实**: +- IAP 模式下 app 接收的请求已经被注入了 `X-Auth-User / X-Auth-Sub / X-Auth-Email / X-Auth-Groups / X-Auth-Token` 头 +- 唯一需要 app 自己处理 OAuth dance 的端点是 `/callback`(IdP 把 code 投递到这里) +- 其余所有路径都依赖 IAP 自动鉴权 + 头注入 + +--- + +## 2. ipass-sso 端配置(三处) + +### 2.1 注册 OAuth 客户端 + +`/usr/local/nginx/data/oauth_clients.json` 加一条: + +```json +{ + "client_id": "app-crm", + "client_secret": "cs_crm_xxx_change_me_2026", + "name": "CRM 演示", + "redirect_uris": [ + "https://idp.example.com:88/proxy/app-crm/callback" + ], + "grant_types": ["authorization_code", "refresh_token"], + "scopes": ["openid", "profile", "email"], + "confidential": true, + "visible_roles": ["admin", "user"] +} +``` + +**硬约定**: +- `redirect_uris` 必须写**公网 URL + `/proxy//callback`**(不是 `127.0.0.1:/callback`) +- `client_secret` 自己生成(`openssl rand -hex 32` 即可),app 端用 HTTP Basic Auth 或 form post 发 +- `visible_roles` 控制工作台谁能看见这个 app + +### 2.2 nginx 加 IAP location + +`deploy/nginx.conf` 的 server 块内加: + +```nginx +upstream app_crm_backend { + server host.docker.internal:18101; # Mac 本机端口(OrbStack docker 场景) + # 或 server 127.0.0.1:8080; # 纯本机场景 + # 或 server 192.168.1.18:18101; # 局域网场景(demo app 必须 bind 0.0.0.0) +} + +# /callback 子路径:单独挂,不走 sso_iap(IdP 来的 callback 无 JWT/cookie) +location /proxy/app-crm/callback { + ipass_api off; # 显式关, 防 merge_loc_conf 漏父级 ipass_api on + proxy_pass http://app_crm_backend/callback; + proxy_redirect ~^(https?://[^/]+)?(/.*)$ /proxy/app-crm$2; # 正则 (重要!) + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; +} + +# / 及其子路径:挂 sso_iap 强制 sso_sid +location /proxy/app-crm/ { + ipass_api off; + sso_iap on; + error_page 401 = @iap_oauth_login; + proxy_pass http://app_crm_backend/; + proxy_redirect ~^(https?://[^/]+)?(/.*)$ /proxy/app-crm$2; # 正则 (重要!) + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; +} + +# 401 兜底:跳企微登录, redirect 保留原 URL (named location 必须在 server 块内) +location @iap_oauth_login { + return 302 "/portal/wxwork/login?redirect=$request_uri"; +} +``` + +**为什么 `proxy_redirect` 必须是正则 `~^(https?://[^/]+)?(/.*)$`?** + +app 内 `redirect("/me")` 返回 `Location: /me`(相对路径)。nginx 默认会把 `/me` 改写成 `<请求 Host>/me` = `https://idp/crm/.../me` —— 错!要用正则显式捕获整个路径再加 `/proxy/app-crm` 前缀: + +- `Location: /`(demo app 内部 redirect 根)→ `Location: /proxy/app-crm/` +- `Location: /me` → `Location: /proxy/app-crm/me` +- `Location: http://app_crm_backend/...` → 同样改写回 `/proxy/app-crm/...` + +字面量 `proxy_redirect http://app_crm_backend/ /proxy/app-crm/;` **不工作**——它只匹配绝对 URL,漏掉相对路径。 + +### 2.3 WeChat Work 工作台应用配置 + +企微管理后台 → 应用 → 自建 / 第三方应用 → **应用主页** = `https://idp.example.com:88/proxy/app-crm/` + +> 不是 `https://idp.example.com:88/admin/`,**必须是 IAP 路径**。 +> 这样用户在企微点图标 → 第一次跳到 `/proxy/app-crm/` → IAP 401 兜底跳企微登录 → OAuth dance → 落到 demo app。 + +环境变量(在 ipass-sso 容器内): +- `OAUTH_ISSUER=https://idp.example.com:88` +- `OAUTH_COOKIE_DOMAIN=example.com`(只影响 sso 终端用户 cookie;admin 会话恒 host-only) +- `WXWORK_ENABLED=true` +- `WXWORK_CORP_ID=ww...` +- `WXWORK_AGENT_ID=1000015` +- `WXWORK_SECRET=...`(**从 K8s Secret 或 xop vault 注入,绝不写到 conf**) +- `WXWORK_REDIRECT=https://idp.example.com:88/portal/wxwork/callback` + +--- + +## 3. App 端要求(关键规则) + +### 3.1 三个 env 变量 + +```bash +# 公网 IdP 地址 (token 兑换 / userinfo 都走这里) +export IDP_BASE=https://idp.example.com:88 + +# 自己 redirect_uri (用 IAP 路径, 不是 loopback) +export REDIRECT_URI=https://idp.example.com:88/proxy/app-crm/callback + +# HTML 路径前缀 (HTML 里所有内部链接加这个前缀; Flask 路由保持 /X) +export BASE=/proxy/app-crm +``` + +> 三个 env 都在 `~/.ipass-sso-data/oauth_clients.json` 的 client 注册和 `deploy/nginx.conf` 里有对应。改一个必须改另两个。 + +### 3.2 路由不要带前缀 + +```python +# ✅ 正确: Flask 路由保持 /X, IAP 会自动 strip /proxy/app-crm 前缀 +@app.route("/") +def home(): ... +@app.route("/customers") +def customers_list(): ... +@app.route("/customers/") +def customer_detail(cid): ... +@app.route("/customers/new", methods=["GET", "POST"]) +def customer_new(): ... + +# ❌ 错误: 不要写成 /proxy/app-crm/customers, 否则 IAP 透传过来时 +# prefix strip 后变成 /customers, 找不到路由 404 +@app.route("/proxy/app-crm/customers") # 错! +def customers_list(): ... +``` + +### 3.3 HTML 字符串必须带 BASE 前缀 + +```python +# ✅ 正确: HTML 里的 href/action/src 用 BASE 拼 +客户 +{name} +
+ +# ❌ 错误: 写裸 /customers → 浏览器跳到 https://idp/customers (公网根) +# → IAP 没匹配 (前缀不对) → 落到 IdP 兜底 404 +客户 # 错! +``` + +### 3.4 Flask `redirect()` 不能带 BASE + +```python +# ✅ 正确: Flask redirect 输出相对路径, IAP proxy_redirect 会加前缀 +@app.route("/callback") +def callback(): + ... + return redirect("/me") # 改 IAP 加前缀 + return redirect("/") # 改 IAP 加前缀 + return redirect(f"/customers/{new_id}") + +# ❌ 错误: 自己加 BASE, IAP 又加一次 → 双前缀 +return redirect(f"{BASE}/me") # 错! → /proxy/app-crm/proxy/app-crm/me +``` + +**规则总结**: +| 输出形态 | 由谁加 BASE | +|---|---| +| HTML 静态字符串 `href` / `action` / `src` | app 自己 (`{BASE}/...`) | +| Flask 动态 `redirect()` 输出 | IAP 的 `proxy_redirect` 正则 | + +### 3.5 /callback 端点要做的(demo app 流程) + +```python +import os, secrets, urllib.parse, urllib.request, json +from flask import Flask, redirect, request, session + +IDP = os.environ.get("IDP_BASE", "https://idp.example.com:88") +CLIENT_ID = "app-crm" +REDIRECT_URI= os.environ["REDIRECT_URI"] # 必须 = oauth_clients.json 注册的 +BASE = os.environ.get("BASE", "") + +app = Flask(__name__) +app.secret_key = os.environ.get("FLASK_SECRET", "change-me-32-bytes-random!") + +@app.route("/login") +def login(): + state = secrets.token_urlsafe(16) + session["state"] = state + qs = urllib.parse.urlencode({ + "response_type": "code", + "client_id": CLIENT_ID, + "redirect_uri": REDIRECT_URI, + "scope": "openid profile email", + "state": state, + }) + return redirect(f"{IDP}/oauth/authorize?{qs}") + +@app.route("/callback") +def callback(): + # 注意: app-crm 实现是「无 state 也放行」, 因为 IdP-initiated 流程 + # (企微工作台点图标) 不带 state. 收到 state 才校验一致性. + received = request.args.get("state") + if received and received != session.get("state"): + return "state 不匹配", 400 + code = request.args.get("code") + if not code: + return "no code", 400 + + # token 兑换: confidential client 用 Basic Auth + import base64 + basic = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode() + req = urllib.request.Request( + f"{IDP}/oauth/v20/token", # 注意是 v20 不是 /oauth/token + data=urllib.parse.urlencode({ + "grant_type": "authorization_code", + "code": code, + "redirect_uri": REDIRECT_URI, + }).encode(), + headers={ + "Authorization": f"Basic {basic}", + "Content-Type": "application/x-www-form-urlencoded", + "Accept": "application/json", + }, + method="POST", + ) + with urllib.request.urlopen(req, timeout=8) as r: + tokens = json.loads(r.read()) # 直接是 OAuth2 裸响应 (不是信封) + + # 公开客户端 (无 client_secret) 改 form-post, 加 PKCE: code_verifier 等 + session["tokens"] = tokens + return redirect("/me") # 走 IAP proxy_redirect → /proxy/app-crm/me +``` + +### 3.6 其余路径直接读 X-Auth-* 头 + +```python +@app.route("/") +def home(): + # IAP 已经鉴权 + 注头, app 不需要再校验 + user = request.headers.get("X-Auth-User", "(anonymous)") + email = request.headers.get("X-Auth-Email", "") + groups = request.headers.get("X-Auth-Groups", "").split(",") + return f"

欢迎 {user} ({email})

组: {', '.join(g for g in groups if g)}

" + +@app.route("/me") +def me(): + # 拿 access_token 调 userinfo + token = request.headers.get("X-Auth-Token", "") + req = urllib.request.Request( + f"{IDP}/oauth/userinfo", + headers={"Authorization": f"Bearer {token}"}, + ) + with urllib.request.urlopen(req) as r: + ui = json.loads(r.read()) + return json.dumps(ui, indent=2, ensure_ascii=False) +``` + +--- + +## 4. 部署拓扑 + +### 4.1 单机 OrbStack(演示用) + +``` +Mac 127.0.0.1 + ├─ OrbStack docker 容器 (ipass-sso 镜像) + │ ├─ 容器内 18098 (nginx) + │ └─ 映射 Mac 28889 (docker run -p 28889:18098) + │ 容器内 → host.docker.internal:18101 → Mac 127.0.0.1:18101 (Flask) + └─ Flask app 本机 127.0.0.1:18101 +``` + +### 4.2 多机生产(app 在另一台) + +``` + ipass-sso 容器 (Mac 28889 或 K8s pod) + │ nginx upstream 指向 192.168.1.X:18101 + │ 关键: app 必须 bind 0.0.0.0 不是 127.0.0.1 + ▼ + app 服务器 (另一台 Mac / Linux / K8s pod) + └─ Flask app bind 0.0.0.0:18101 +``` + +### 4.3 K8s pod 内启动(**反例**, 不要这么干) + +K8s pod 在 OrbStack VM 内独立 netns, pod 内 192.168.1.x / host.docker.internal +都连不上 Mac LAN(被 K8s 网络层隔离)。如果一定要在 K8s 内跑 app, 必须: +- app 用 NodePort/Service 暴露给 OrbStack VM +- 或在 Mac 起 socat/iptables 把 K8s 端口转出来 + +--- + +## 5. 端到端验证(5 步) + +```bash +# 0) 起 demo app, 带 BASE env +cd /tmp/idp-sim +nohup env BASE=/proxy/app-crm \ + IDP_BASE=https://idp.example.com:88 \ + REDIRECT_URI=https://idp.example.com:88/proxy/app-crm/callback \ + FLASK_SECRET=$(openssl rand -hex 32) \ + python3 -u app-crm.py > app-crm.log 2>&1 & + +# 1) 直连 demo app: / 应 redirect /login (无 BASE, 走 IAP proxy_redirect) +curl -s -o /dev/null -D - http://127.0.0.1:18101/ | grep -i location +# 期望: Location: /login + +# 2) IAP /proxy/app-crm/ (无 sso_sid → 401 兜底) +curl -s -o /dev/null -D - http://127.0.0.1:28889/proxy/app-crm/ | grep -i location +# 期望: Location: /portal/wxwork/login?redirect=/proxy/app-crm/ + +# 3) IAP /proxy/app-crm/callback (无 sso_iap, demo app 400 因缺 state/code) +curl -s -o /dev/null -D - http://127.0.0.1:28889/proxy/app-crm/callback | head -1 +# 期望: HTTP/1.1 400 + +# 4) 真 iPhone/PC 企微点 CRM 图标 +# 期望: 落 /proxy/app-crm/me 或 /, 不再 /admin/ → /manage/users +``` + +--- + +## 6. AI 快速集成 checklist + +把这一节复制给 AI,让它按项 check: + +### ipass-sso 端 + +- [ ] `oauth_clients.json` 加 client, `redirect_uris` 第一条 = `https:///proxy//callback` +- [ ] `deploy/nginx.conf` 加 4 段 location(upstream / callback / iap-loc / 401-namied-location) +- [ ] 每段 IAP location 的 `proxy_redirect` 都用**正则** `~^(https?://[^/]+)?(/.*)$ /proxy/$2` +- [ ] iap-loc 显式 `ipass_api off;` + `sso_iap on;` + `error_page 401 = @iap_oauth_login` +- [ ] /callback 显式 `ipass_api off;` + `proxy_pass http:///callback`(**具体子路径**) +- [ ] 企微工作台应用主页 URL = `https:///proxy//`(**IAP 路径**) + +### App 端 + +- [ ] `IDP_BASE` / `REDIRECT_URI` / `BASE` 三个 env 配齐 +- [ ] `REDIRECT_URI` 必须 = `oauth_clients.json` 注册的(否则 token 兑换 `invalid_grant`) +- [ ] Flask 路由全部 `/X`(**不**带 `/proxy//` 前缀) +- [ ] HTML 模板里所有 `href` / `action` / `src` 写 `{BASE}/X`(**带**前缀) +- [ ] Flask `redirect()` 全部 `/X`(**不带** BASE,让 IAP proxy_redirect 改写) +- [ ] `id_token` / `access_token` 兑换用 `/oauth/v20/token`(**不**是 `/oauth/token`,后者是信封格式) +- [ ] 拿 `userinfo` 用 `Authorization: Bearer ` 打 `/oauth/userinfo` +- [ ] 公开客户端(无 client_secret)走 PKCE/S256,token 兑换 form-post +- [ ] `app.run(host="0.0.0.0", port=PORT)`(**不**是 127.0.0.1,否则 IAP 容器连不上) + +### 失败排查(按概率排序) + +| 现象 | 原因 | 修复 | +|---|---|---| +| `{"code":404,"msg":"接口不存在:GET /customers"}` | demo app 渲染 `href="/customers"`, 浏览器跳公网 `/customers` 落 IdP 兜底 | HTML 改 `href="{BASE}/customers"` | +| iPhone 点 CRM 落 `/manage/users` | demo app `redirect("/")` 没被改写, IAP proxy_redirect 字面量只匹配绝对 URL | nginx 改正则 `~^(https?://[^/]+)?(/.*)$ /proxy/$2` | +| 落在 `/proxy/app-crm/proxy/app-crm/`(双前缀) | demo app 自己也加了 BASE 到 `redirect()`, IAP 又加一次 | demo app `redirect()` 还原成 `/X` 形式 | +| `invalid_grant: redirect_uri 不匹配` | demo app 写的 REDIRECT_URI 与 oauth_clients.json 注册的不一致 | env 改一致, 都用公网 IAP 路径 | +| iPhone 一直转圈 | demo app 监听 127.0.0.1, 容器连不上 | `app.run(host="0.0.0.0", port=PORT)` | + +--- + +## 7. 完整最小 app-crm 模板 + +最小可运行的 demo(约 100 行),复制后改 `CLIENT_ID` / `REDIRECT_URI` / `BASE` 即可: + +```python +#!/usr/bin/env python3 +"""最小可工作的 IAP demo - 复制改 env 即用""" +import os, secrets, base64, json, urllib.parse, urllib.request +from flask import Flask, redirect, request, session + +IDP = os.environ["IDP_BASE"] +CLIENT_ID = "app-crm" # ← 改 +CLIENT_SECRET= "cs_crm_xxx_change_me_2026" # ← 改 +REDIRECT_URI = os.environ["REDIRECT_URI"] # ← 改 = oauth_clients.json 注册 +BASE = os.environ.get("BASE", "") # ← 改 = /proxy/ +PORT = 18101 # ← 改 +app = Flask(__name__) +app.secret_key = os.environ.get("FLASK_SECRET", secrets.token_hex(32)) + +def _idp_post(path, body, auth=True): + headers = {"Accept": "application/json", "Content-Type": "application/x-www-form-urlencoded"} + if auth: + headers["Authorization"] = "Basic " + base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode() + req = urllib.request.Request(f"{IDP}{path}", data=urllib.parse.urlencode(body).encode(), + headers=headers, method="POST") + with urllib.request.urlopen(req, timeout=8) as r: + return json.loads(r.read()) + +@app.route("/login") +def login(): + state = secrets.token_urlsafe(16) + session["state"] = state + qs = urllib.parse.urlencode({"response_type": "code", "client_id": CLIENT_ID, + "redirect_uri": REDIRECT_URI, "scope": "openid profile email", + "state": state}) + return redirect(f"{IDP}/oauth/authorize?{qs}") + +@app.route("/callback") +def callback(): + rcv = request.args.get("state") + if rcv and rcv != session.get("state"): + return "state mismatch", 400 + tokens = _idp_post("/oauth/v20/token", { + "grant_type": "authorization_code", + "code": request.args["code"], + "redirect_uri": REDIRECT_URI, + }) + session["tokens"] = tokens + return redirect("/me") # ← 不带 BASE, 走 IAP + +@app.route("/") +def home(): + user = request.headers.get("X-Auth-User", "?") + return f'

欢迎 {user}

' + +@app.route("/me") +def me(): + tok = request.headers.get("X-Auth-Token", "") + req = urllib.request.Request(f"{IDP}/oauth/userinfo", + headers={"Authorization": f"Bearer {tok}"}) + with urllib.request.urlopen(req) as r: + ui = json.loads(r.read()) + return f"
{json.dumps(ui, indent=2, ensure_ascii=False)}
" + +if __name__ == "__main__": + app.run(host="0.0.0.0", port=PORT, debug=False) # ← 0.0.0.0 不是 127.0.0.1 +``` + +启动: + +```bash +export IDP_BASE=https://idp.example.com:88 +export REDIRECT_URI=https://idp.example.com:88/proxy/app-crm/callback +export BASE=/proxy/app-crm +export FLASK_SECRET=$(openssl rand -hex 32) +python3 app-crm.py +``` + +--- + +## 8. 参考 + +- 实际跑的 demo app 源码:`/tmp/idp-sim/app-crm.py`(约 700 行,含客户/商机/阶段管理完整功能) +- ipass-sso IAP 通用接入(不依赖企微工作台):`docs/iap.md`(讲 X-Auth-* 头注入 / Bearer vs Cookie 鉴权) +- 记忆 `iap-reverse-proxy.md`:架构 + 拓扑 + 历次踩坑 +- 记忆 `k8s-to-docker-migration.md`:OrbStack 容器网络细节 +- IAP 烟测脚本:`/tmp/idp-sim/test-iap.sh` +- demo app 重启脚本:`/tmp/idp-sim/restart-demo-apps.sh`