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"""
{badge} 请求路径: /{p}
| {k} | {v} |
{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 已注入身份 请求路径: /iap-demo/whoami
| X-Auth-User | admin |
| X-Auth-Sub | admin |
| X-Auth-Email | admin@yourdomain.com |
| X-Auth-Groups | admin |
| X-Auth-Token | eyJhbGciOiJSUzI1NiIsImtpZCI6ImlhcC1kZW1vLWtleS0x… |
{
+ "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