Files
sso/README.md
T
ssw 4a780a4ce7 feat(sso): MaxKey 迁移 P1/P2 —— SCIM/CAS/LDAP/同步连接器/自助密码重置/归属地
- 新增 plugin-sso 模块(零新增 crate):scim.rs(SCIM 2.0)、cas.rs(CAS 1.0/2.0)、

  ldap.rs(LDAP/AD,手写 BER/ASN.1 Simple Bind)、sync.rs(钉钉/企微/飞书手动触发同步)、

  reset.rs(自助密码重置)、geo.rs(登录 IP 归属地)

- api.rs 兜底路由按 scim→cas→reset→sync 分发兄弟模块;h_login 集成 LDAP(未启用零行为变化)

- 修 http::redirect 空 body 触发 NGX_ERROR(CAS 302 无 Location 的根因)

- nginx.conf / nginx.test.conf 补 env SYNC_* / PASSWORD_RESET_*(worker 可见)

- 新增第 7 套 e2e tests/maxkey-p1p2-e2e.sh(21 项),harness 接入 [7/7];七套全绿 rc=0

- 修脚本 $var 紧跟全角字符被并入变量名的 shell 坑(tests + scripts)

- 文档同步:maxkey-migration-analysis(P1/P2 状态) / roadmap(v4) / CLAUDE.md / README.md
2026-09-14 18:51:37 +08:00

280 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# iPass 统一网关 —— 身份插件(nginx 动态模块 + Rust)
> 本仓库是 **iPass 统一网关**的代码库,形态是**内核 + 插件**(编译期装配,产出单个 `.so`):
>
> | crate | 职责 |
> | --- | --- |
> | `ipass-core` | 内核:共享内存状态、`users.json` 与 API Key 的**唯一读写者** |
> | `plugin-sso` | 身份插件(本 README 的主体):OAuth2/OIDC + IAP |
> | `plugin-domain` | 域名插件:企业域名「子域名 → 后端」转发(新增能力插件的完整示例) |
>
> 判据:去掉 SSO,网关仍能转域名、仍能代理 LLM → 所以内核不是身份,**身份只是插件之一**。
> 架构论证见 `docs/plugin-architecture-analysis.md`。
自包含的 **OAuth2.0 / OIDC 身份提供者(IdP)** 与 **身份感知代理(IAP)**,
以 nginx 动态模块形式运行:加载进 nginx,不引入数据库、Redis、消息队列或任何额外常驻进程。
- **IdP**:签发 access / refresh / id_token,支持 `authorization_code`(含 PKCE)、
`refresh_token`、`client_credentials`、`password` 四种 grant,附带 discovery / introspect / userinfo。
- **IAP**:在 nginx `access` 阶段做门禁,把身份以 `X-Auth-*` 请求头**注入**到后端,
既有业务系统改一行 nginx 配置即可接入,**业务代码零改造**。
- **协议兼容 MaxKey**:提供 `/oauth/v20/*`、`/oauth2.0/*` 端点别名与 context-path 归一化,
照抄 MaxKey 文档的第三方应用不用改一行代码。
> **身份与流量分离**:`plugin-sso` 只回答「你是谁」与「把这个身份告诉后端」。
> 动态域名转发、LLM 上游代理、用量计费属于**其它插件**(来源存档见 `refs/ipass`),
> 与身份插件共用同一份 `users.json`、同一把 API Key——由 `ipass-core` 统一读写。
---
## 快速开始
### 依赖
- 一棵已 `./configure` 过的 **nginx 1.30.4 源码树**(模块须与 nginx 二进制同源编译)
- Rust 工具链 + `libclang`(bindgen 用)
- `curl`、`python3`(只用于测试脚本与种子生成)
### 本机跑通端到端(不依赖 Docker)
```bash
# ① 准备 nginx 源码树(只需 configure,一次即可)
mkdir -p /tmp/sso-build/src && cd /tmp/sso-build/src
curl -fsSL https://nginx.org/download/nginx-1.30.4.tar.gz -o nginx.tar.gz && tar xzf nginx.tar.gz
curl -fsSL https://github.com/PCRE2Project/pcre2/releases/download/pcre2-10.44/pcre2-10.44.tar.gz -o pcre2.tar.gz && tar xzf pcre2.tar.gz
# ② 编译 nginx(必须含 rewrite 模块:`return` / `error_page` 内部跳转都靠它)
cd nginx-1.30.4
./configure --prefix=/tmp/sso-build/nginx \
--with-pcre=/tmp/sso-build/src/pcre2-10.44 --with-http_realip_module \
--without-http_gzip_module --without-http_ssi_module --without-http_userid_module \
--without-http_autoindex_module --without-http_geo_module \
--without-http_split_clients_module --without-http_referer_module \
--without-http_uwsgi_module --without-http_scgi_module --without-http_grpc_module \
&& make -j"$(sysctl -n hw.ncpu)"
# ③ 编译 Rust 模块
cd <本仓库>/source/rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib # macOS
export NGINX_SOURCE_DIR=/tmp/sso-build/src/nginx-1.30.4
export NGINX_BUILD_DIR=/tmp/sso-build/src/nginx-1.30.4/objs
cargo build --release # 产物 source/rust/target/release/libsso_gateway.dylib
# ④ 一键跑七套端到端(自动播种数据、起 nginx + demo 系统、跑完自动清理)
cd <本仓库> && bash scripts/run-local-e2e.sh
```
### 手工观察 IdP / 管理台
```bash
bash scripts/run-local-e2e.sh --keep # 保留进程不清理
# 管理台 http://127.0.0.1:18098/admin 账号 admin / 123456
# 演示用户 alice / alice123
# discovery http://127.0.0.1:18098/.well-known/openid-configuration
kill <打印出的 pid>
```
---
## 目录结构
```
sso/
├── docs/
│ ├── design.md 设计文档:端点、token 模型、共享内存、MaxKey 互通、构建与测试
│ ├── roadmap.md 路线图(v1–v4 已完成 + 待办)
│ └── screenshots/ 管理台与登录页截图
├── source/ 可部署产物(代码 + 配置 + 静态页)
│ ├── rust/ 动态模块源码(Cargo workspace,vendor 了 ngx-rust)
│ │ ├── crates/ipass-core/ 内核:状态 / 账号 / Key 的唯一读写者 / 插件契约
│ │ ├── crates/plugin-sso/ 身份插件:OAuth2 / OIDC + IAP
│ ├── crates/plugin-domain/ 域名插件:企业域名子域名转发(插件示例)
│ │ └── gateway/ 装配层:module 壳 + 插件注册表 → libsso_gateway.so
│ ├── conf/
│ │ ├── nginx.conf 生产模板(TLS、IAP 子域、日志字段)
│ │ ├── nginx.test.conf 本机/CI 验证配置(明文端口 18093-18099)
│ │ └── tls/README.md 证书约定、acme.sh 签发与校验
│ ├── www/admin.html 管理台单页(纯静态 + fetch)
│ ├── data-seed/ 种子模板(进版本库)
│ └── data/ 运行时数据(**不进版本库**,由 scripts/seed-data.sh 生成)
├── tests/ 测试程序与测试应用
│ ├── oauth2-e2e.sh 协议基线(discovery/grant/token/IAP 注入)
│ ├── oauth2-maxkey-e2e.sh MaxKey 互通 + demo 系统接入
│ ├── admin-oauth-clients-e2e.sh 管理接口(接入方注册表)
│ ├── rs256-jwks-e2e.sh RS256 + JWKS 本地验签
│ ├── admin-users-batch-e2e.sh 管理接口(账号批量维护)
│ ├── domain-e2e.sh 域名插件(申请/审核/转发)
│ ├── maxkey-p1p2-e2e.sh MaxKey P1/P2(SCIM/CAS/密码重置/同步/LDAP)
│ └── demo-system/ 演示用「简单业务系统」(Python 标准库)
├── scripts/
│ ├── run-local-e2e.sh 本机一键起停 + 跑七套 e2e
│ └── seed-data.sh 物化运行时数据目录
└── refs/ 参考资料(**不进版本库**):ipass 来源项目、MaxKey
```
---
## 端点一览
### 认证协议端点
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/oauth/authorize` | 授权端点(未登录跳登录页) |
| POST | `/oauth/token` | 换发令牌(四种 grant) |
| GET/POST | `/oauth/userinfo` | 当前令牌对应用户声明 |
| POST | `/oauth/introspect` | RFC 7662 令牌自省(第三方校验,需客户端鉴权) |
| GET | `/.well-known/openid-configuration` | OIDC discovery |
| GET | `/oauth/jwks` · `/.well-known/jwks.json` | 公钥集合(**RS256**,`kid` 轮换;第三方本地验签,无需回源 introspect) |
| GET/POST | `/login` | 登录页与表单提交(建立 `sso_sid` 会话) |
| GET/POST | `/oauth/logout` | 注销会话 |
### MaxKey 兼容别名
| 别名 | 说明 |
| --- | --- |
| `/oauth/v20/authorize` · `/oauth2.0/authorize` | 授权端点 |
| `/oauth/v20/token` · `/oauth2.0/accessToken` | 换发(**裸对象响应**,不套 `{code,msg,data}`) |
| `/oauth/v20/me` | 扁平字段 `username`/`userid`/`realname`/`email`/`mobile`,令牌走 `access_token` 参数 |
| `/oauth2.0/profile` · `/oauth/v20/logout` | 同上 |
| `/maxkey/...` · `/sign/authz/...` · `/sign/...` · `/authz/...` · `/api/...` 前缀 | context-path 自动归一化 |
### P1/P2 扩展端点(2026-09-14)
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/scim/v2/ServiceProviderConfig` · `/Schemas` · `/ResourceTypes` | SCIM 2.0 元数据 |
| GET/POST | `/scim/v2/Users` | 列表 / 创建(201) |
| GET/PATCH/DELETE | `/scim/v2/Users/{id}` | 查询 / 增量改 / 删除(204) |
| GET | `/scim/v2/Groups` | 用户组(派生自账号 `groups`) |
| GET | `/cas/login?service=URL` | 已登录签发 ST 并 302 回跳 `?ticket=ST-` |
| GET | `/cas/validate` | CAS 1.0 纯文本(`yes\n<user>` / `no`) |
| GET | `/cas/serviceValidate` · `/cas/proxyValidate` | CAS 2.0 XML |
| GET | `/cas/logout` | 注销 CAS 会话 |
| POST | `/api/public/forgot-password` | 自助密码找回(发一次性 token;防账号枚举) |
| POST | `/api/public/reset-password` | 凭 token 重置口令(单次有效) |
| POST | `/api/admin/sync/{dingtalk,workwechat,feishu}` | 手动触发身份同步(管理员) |
### 管理接口(`/api/admin/*`,需管理员会话 Cookie)
| 分类 | 路径 |
| --- | --- |
| 会话 | `login` · `logout` · `session` |
| 账号 | `users`(列表)· `users/create` · `users/key` · `users/password` · `users/display` · `users/profile`(部门/用户组)· `users/role` · `users/unlock` · `users/batch` · `users/totp/setup|enable|disable` · `users/delete` |
| 同步 | `sync/dingtalk` · `sync/workwechat` · `sync/feishu`(手动触发,需配 `SYNC_*_URL`) |
| 接入方 | `oauth-clients`(列表)· `oauth-clients/save` · `oauth-clients/rotate` · `oauth-clients/delete` |
账号态 API:`GET /api/v1/me`(`X-API-Key` 或 Bearer 鉴权)。
---
## 两种接入姿势
**方式一:应用自己当 OAuth2 客户端** —— 应用实现授权码流程,拿到令牌代用户调用 API。
适合需要令牌的场景(示例见 `tests/demo-system/app.py`,支持 `maxkey` / `standard` 两种端点风格)。
**方式二:前置 IAP,零改造** —— 在业务 location 上加两段配置即可:
```nginx
location / {
sso_iap on; # access 阶段门禁
proxy_pass http://127.0.0.1:8080;
# ⚠️ 这组 header 由网关断言覆盖,客户端伪造同名头会被盖掉
proxy_set_header X-Auth-User $auth_user;
proxy_set_header X-Auth-Email $auth_email;
proxy_set_header X-Auth-Groups $auth_groups;
proxy_set_header X-Auth-Sub $auth_sub;
proxy_set_header X-Auth-Token $auth_token;
error_page 401 = @oauth_login; # 未登录 → 跳登录页并回跳
}
location @oauth_login { # 注意:named location 不能写 `location = @name`
return 302 "https://sso.yourdomain.com/login?redirect=$scheme://$host$request_uri";
}
```
后端只读 `X-Auth-*`,不接触令牌。跨子域 SSO 用 `OAUTH_COOKIE_DOMAIN=.yourdomain.com` 打开。
---
## 生产部署
```bash
# 1. 模块装到 nginx
install -m 755 source/rust/target/release/libsso_gateway.so /usr/local/nginx/modules/
# 2. 配置(按环境改域名与证书路径)
cp source/conf/nginx.conf /usr/local/nginx/conf/nginx.conf
cp -r source/www /usr/local/nginx/www
cp -r source/data-seed /usr/local/nginx/data-seed
# 3. 播种账号(生产务必覆盖默认口令)
DATA_DIR=/usr/local/nginx/data ADMIN_PASSWORD='<强口令>' bash scripts/seed-data.sh
# 4. 证书:见 source/conf/tls/README.md(acme.sh 签发 + 公钥比对校验)
# 5. 启动/重载
/usr/local/nginx/sbin/nginx -t && /usr/local/nginx/sbin/nginx
```
**改代码后必须重启,不能 reload** —— 动态模块在 `load_module` 时载入,`reload` 不会重新读取 `.so`。
### 必须显式声明的环境变量
nginx 默认剥离所有环境变量,`nginx.conf` 的 main 上下文里必须有:
```nginx
env ADMIN_INIT_PASSWORD; # 缺了这行模块读到的初始口令恒为空
env OAUTH_SIGNING_SECRET; # 令牌签名密钥(HS256 对称密钥)
env OAUTH_ISSUER; # 必须与浏览器实际访问的 host 一致,否则第三方校验 issuer 失败
env OAUTH_COOKIE_DOMAIN; # 跨子域 SSO 才需要;不设 = 主机级 cookie
# P1/P2 新增模块用到的(缺了则 worker 里读不到)
env SYNC_DINGTALK_URL; # 同步连接器:钉钉用户目录源
env SYNC_WORKWECHAT_URL; # 同步连接器:企业微信用户目录源
env SYNC_FEISHU_URL; # 同步连接器:飞书用户目录源
env PASSWORD_RESET_TOKEN_SINK;# 自助密码重置:token 落盘路径(生产可改接 SMTP)
env PASSWORD_RESET_TTL; # 自助密码重置:token 有效期秒(缺省 1800)
# LDAP/AD 认证源(未设置 = 关闭,既有登录行为不变):
env LDAP_ENABLED; # 1 = 启用 LDAP 兜底认证
env LDAP_SERVER; # 如 ldap://127.0.0.1
env LDAP_PORT; # 缺省 389
env LDAP_BASE_DN; # 如 dc=example,dc=com
env LDAP_USER_DN_TEMPLATE; # 如 uid={user},ou=people,dc=example,dc=com
env LDAP_AUTO_CREATE; # 1 = LDAP 认证成功但本地无账号时自动建号
```
---
## 测试
```bash
bash scripts/run-local-e2e.sh # 七套全跑(推荐)
bash tests/oauth2-e2e.sh http://127.0.0.1:18098 http://127.0.0.1:18099 # 协议基线
bash tests/oauth2-maxkey-e2e.sh # MaxKey 互通 + demo 接入
bash tests/admin-oauth-clients-e2e.sh # 管理接口(接入方)
bash tests/rs256-jwks-e2e.sh # RS256 + JWKS 验签
bash tests/admin-users-batch-e2e.sh # 管理接口(账号批量)
bash tests/domain-e2e.sh # 域名插件
bash tests/maxkey-p1p2-e2e.sh # SCIM / CAS / 密码重置 / 同步 / LDAP
```
客户端密钥**不硬编码在脚本里**,运行时从 `$DATA_DIR/oauth_clients.json` 读取。
---
## 待执行任务
见 [`docs/roadmap.md`](docs/roadmap.md)。已完成:v2(RS256 + JWKS)、用户管理界面、
v3(MaxKey/JNPF/uc 迁移 P0)、v4(MaxKey 迁移 **P1/P2**:SCIM 2.0 · CAS · LDAP/AD · 同步连接器 ·
自助密码重置 · 登录 IP 归属地)。明确跳过:WebAuthn/Passkey、SAML 2.0、社交/扫码、FormBased。
明细与依据见 [`docs/maxkey-migration-analysis.md`](docs/maxkey-migration-analysis.md)。
---
## 深入阅读
- [`docs/design.md`](docs/design.md) —— 完整设计:token 模型、共享内存布局、防伪造机制、
MaxKey 差异说明、构建踩坑、测试覆盖清单
- [`CLAUDE.md`](CLAUDE.md) —— 给 AI 协作者的项目说明:硬约定、目录地图、排障速查