admin 2821adf116 docs(deploy): 容器化部署方案 + rust-nginx-base 基础镜像说明
- docs/sso-deploy-plan.md:ucenter chg_0012 落地 SSO 的容器化部署计划
  (本机端口 8881 + host 编产物再 COPY 进极简镜像的逆模型)
- docs/rust-nginx-base.md:rust-nginx-base 镜像设计 + tag 约定 + 复用姿势
  (iPass / SSO / 未来其他 ngx-rust 项目共用)
2026-09-24 16:27:08 +08:00

iPass 统一网关 —— 身份插件(nginx 动态模块 + Rust)

本仓库是 iPass 统一网关中 SSO(单点登录)身份插件的代码库,形态是内核 + 插件(编译期装配,产出单个 .so):

crate 仓库内? 职责
plugin-sso ✅ 本仓库 身份插件(本 README 的主体):OAuth2/OIDC + IAP
gateway ✅ 本仓库 装配层:module 壳 + 插件注册表 → libsso_gateway.so
ipass-core / plugin-domain / plugin-llm / plugin-apix ⬇️ deps/ipass 子模块 网关内核与通用能力插件(见 ipass/ipass),本仓库不再内置

判据:去掉 SSO,网关仍能转域名、仍能代理 LLM → 所以内核不是身份,身份只是插件之一。 内核与通用子系统统一由 deps/ipass git 子模块(ipass/ipass)提供,本仓库只持有 plugin-sso + gateway。 架构论证见 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 上游代理、用量计费属于其它插件,它们与身份插件一同来自 deps/ipass 子模块(ipass/ipass,来源存档见 refs/ipass)。所有插件共用同一份 users.json、同一把 API Key——由子模块内核 ipass-core 统一读写。


快速开始

依赖

  • 一棵已 ./configure 过的 nginx 1.30.4 源码树(模块须与 nginx 二进制同源编译)
  • Rust 工具链 + libclang(bindgen 用)
  • curl、python3(只用于测试脚本与种子生成)

本机跑通端到端(不依赖 Docker)

# ① 准备 nginx 源码树(只需 configure,一次即可)
mkdir -p ./build/src && cd ./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=./build/nginx \
  --with-pcre=./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)"

# ③ 拉取内核子模块(首次克隆后只需一次)
git submodule update --init deps/ipass

# ④ 编译 Rust 模块
cd <本仓库>/rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib   # macOS
export NGINX_SOURCE_DIR=./build/src/nginx-1.30.4
export NGINX_BUILD_DIR=./build/src/nginx-1.30.4/objs
cargo build --release            # 产物 rust/target/release/libsso_gateway.dylib

# ⑤ 一键跑 SSO 端到端(自动播种数据、起 nginx + demo 系统、跑完自动清理)
cd <本仓库> && bash scripts/run-local-e2e.sh

手工观察 IdP / 管理台

bash scripts/run-local-e2e.sh --keep      # 保留进程不清理
# 管理台  http://127.0.0.1:18098/admin     账号 admin / 123456
#   页签:账号管理 / OAuth 应用 / 身份同步 / 会话·审计 / 接入指南
# 演示用户 alice / alice123
# 终端用户自助找回  http://127.0.0.1:18098/forgot   (登录页有「忘记密码?」入口)
# discovery http://127.0.0.1:18098/.well-known/openid-configuration
kill <打印出的 pid>

目录结构

sso/
├── deps/
│   └── ipass/                # git 子模块 → ipass/ipass:内核 ipass-core + vendor/ngx-rust + 通用插件(plugin-domain/llm/apix) + gateway 装配骨架
├── docs/
│   ├── design.md            设计文档:端点、token 模型、共享内存、MaxKey 互通、构建与测试
│   ├── roadmap.md           路线图(v1–v4 已完成 + 待办)
│   └── screenshots/         管理台与登录页截图
├── rust/                    动态模块源码(本仓库的 Cargo workspace)
│   ├── Cargo.toml           members=[crates/plugin-sso, gateway];ipass-core/ngx-rust 走 deps/ipass 的 path 依赖
│   ├── crates/plugin-sso/   身份插件:OAuth2 / OIDC + IAP(本仓库唯一业务 crate)
│   └── 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/                   测试程序与测试应用(SSO 相关 e2e;域名/LLM 相关见 deps/ipass)
│   ├── 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 管理接口(账号批量维护)
│   ├── maxkey-p1p2-e2e.sh       MaxKey P1/P2(SCIM/CAS/密码重置/同步/LDAP/应用门户)
│   └── demo-system/             演示用「简单业务系统」(Python 标准库)
├── scripts/
│   ├── run-local-e2e.sh     本机一键起停 + 跑 SSO 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 会话
GET /forgot 找回密码页(终端用户入口;登录页有「忘记密码?」链接)
GET /reset?token=… 重置口令页(凭一次性 token 设置新口令)
POST /api/public/forgot-password 自助密码找回(发一次性 token;防账号枚举)
POST /api/public/reset-password 凭 token 重置口令(单次有效)
POST /api/admin/sync/{dingtalk,workwechat,feishu} 手动触发身份同步(管理员)
GET /apps 用户门户「我的应用」(登录后按可见范围列出可访问应用,点击直达)
GET /api/portal/apps 门户数据的 JSON(未登录 401)
分类 路径
会话 login · logout · session
账号 users(列表)· users/create · users/key · users/password · users/display · users/profile(部门/用户组)· users/role · users/unlock · users/batch · `users/totp/setup
同步 sync/dingtalk · sync/workwechat · sync/feishu(手动触发,需配 SYNC_*_URL)
接入方 oauth-clients · oauth-clients/save · …/rotate · …/delete;字段含 协议类型(oauth2/cas)、访问地址、描述、图标、可见范围(角色/部门/用户组)
运维 sessions(在线会话列表)· sessions/kick(token / username / all 三种踢法)· audit(审计日志,含 IP 归属地)
接入方 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 上加两段配置即可:

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 打开。


生产部署

# 1. 模块装到 nginx
install -m 755 rust/target/release/libsso_gateway.so /usr/local/nginx/modules/

# 2. 配置(按环境改域名与证书路径)
cp conf/nginx.conf /usr/local/nginx/conf/nginx.conf
cp -r www /usr/local/nginx/www
cp -r data-seed /usr/local/nginx/data-seed

# 3. 播种账号(生产务必覆盖默认口令)
DATA_DIR=/usr/local/nginx/data ADMIN_PASSWORD='<强口令>' bash scripts/seed-data.sh

# 4. 证书:见 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 上下文里必须有:

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 scripts/run-local-e2e.sh                    # 本仓库 SSO e2e 全跑(推荐)
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/maxkey-p1p2-e2e.sh                    # SCIM / CAS / 密码重置 / 同步 / LDAP
# 注:域名插件、LLM 上游代理等通用能力插件的 e2e 在 deps/ipass 子模块内运行

客户端密钥不硬编码在脚本里,运行时从 $DATA_DIR/oauth_clients.json 读取。


待执行任务

见 docs/roadmap.md。已完成:v2(RS256 + JWKS)、用户管理界面、 v3(MaxKey/JNPF/uc 迁移 P0)、v4(MaxKey 迁移 P1/P2:SCIM 2.0 · CAS(含 service 白名单)· LDAP/AD · 同步连接器 · 自助密码重置 · 登录 IP 归属地 · 应用管理增强与用户门户)。明确跳过:WebAuthn/Passkey、SAML 2.0、社交/扫码、FormBased。 明细与依据见 docs/maxkey-migration-analysis.md。


深入阅读

  • docs/design.md —— 完整设计:token 模型、共享内存布局、防伪造机制、 MaxKey 差异说明、构建踩坑、测试覆盖清单
  • CLAUDE.md —— 给 AI 协作者的项目说明:硬约定、目录地图、排障速查
S
Description
SSO 统一认证服务 —— nginx 动态模块 + Rust(自包含 OAuth2/OIDC IdP + IAP 身份注入)
Readme
5.5 MiB
0 Stars 1 Watchers 0 Forks
Languages
HTML 59.9%
Shell 15.4%
Rust 14.3%
Dockerfile 6%
Python 4.4%