Files
sso/tests/demo-system
ssw c8a02b8c49 feat: 从网关项目剥离为独立 SSO 统一认证服务
定位:身份层(IdP + IAP),不含动态域名转发 / LLM 上游代理 / 用量计费。

代码(source/rust,nginx 动态模块 + Rust,单进程零外部依赖)
- IdP:authorization_code(含 PKCE)/ refresh_token / client_credentials / password
  四种 grant,含 discovery / introspect / userinfo / jwks 占位
- IAP:access 阶段门禁,注入 X-Auth-* 到后端,客户端伪造同名头被覆盖
- MaxKey 互通:/oauth/v20/* 与 /oauth2.0/* 别名 + context-path 归一化 + 扁平字段
- 管理接口:账号(含角色/部门/用户组)与 OAuth 接入方注册表,热写穿共享内存
- 模块改名 ngx_http_sso_module,指令 sso_state / sso_data_dir / sso_api / sso_iap,
  Cookie sso_sid(终端用户)与 sso_admin_session(管理员)两套身份两套会话

配置(source/conf)
- nginx.conf 生产模板(TLS、IAP 子域、含 auth_sub 的日志格式)
- nginx.test.conf 本机验证配置(明文 18095-18099)
- tls/README.md 证书约定与公钥比对校验

前端(source/www/admin.html)
- 三 tab:账号管理 / 接入方 / 接入指南;去掉审核队列、域名、LLM 上游、用量统计

测试与脚本
- tests/ 三套端到端:协议基线 14 项 · MaxKey 互通与接入 24 项 · 管理接口 31 项,全绿
- tests/demo-system 演示业务系统(Python 标准库),覆盖应用自建客户端与 IAP 零改造两种姿势
- scripts/run-local-e2e.sh 本机一键起停;scripts/seed-data.sh 物化运行时数据目录

文档
- README.md 概览与快速开始;CLAUDE.md 硬约定与排障速查
- docs/design.md 完整设计;docs/roadmap.md 待执行任务(v2 RS256+JWKS、用户管理界面)
2026-09-12 21:42:06 +08:00
..

demo-system —— 一个「简单业务系统」

用来验证第三方系统如何接入 sso 统一认证。仅 Python 3 标准库,无依赖。

python3 app.py          # 默认:MaxKey 风格端点 + :18096 + 本地 IdP

配合 tests/run-oauth2-local.sh 会自动拉起本应用并跑完整端到端。

两种接入姿势

模式 A:自己做 OAuth2 客户端 模式 B:前置 IAP,零改造
谁做认证 本应用(授权码流程) 网关(nginx + sso_gateway)
应用做什么 /login → 授权码 → 换 token → 取 userinfo → 建本地会话 只读 X-Auth-* 请求头
需要改代码 需要(OAuth 客户端逻辑) 不需要
适用 需要拿令牌代用户调 API 既有系统、异构栈、改造代价大

代码里两种模式共存:current_identity() 先看 IAP 注入头,再看本地会话。

模式 A 的两种端点风格

DEMO_STYLE 控制(这就是「MaxKey 互通」的落点):

风格 授权 换发 用户信息 客户端鉴权 令牌位置
maxkey /oauth/v20/authorize /oauth/v20/token /oauth/v20/me 表单 client_id/secret access_token 参数
standard /oauth/authorize /oauth/token /oauth/userinfo Authorization: Basic Bearer 头

不带 client_secret 时自动启用 PKCE(S256),按公开客户端走。

端点

路径 说明
GET / 首页:未登录给登录入口,已登录展示身份(含来源标签)
GET /login 生成 state + (可选)PKCE,302 到 IdP 授权端点
GET /oauth2/callback 收 code → 换 token → 取 userinfo → 建本地会话(也接受 /callback)
GET /api/me 当前身份 JSON,source 为 oauth2 或 iap
GET /api/echo 回显收到的 X-Auth-* 头(验证网关注入)
GET /healthz 健康检查(含 style / idp / client_id)
GET /logout 清本地会话

配置

变量 默认 说明
DEMO_PORT 18096 监听端口
DEMO_BIND 127.0.0.1 绑定地址
DEMO_STYLE maxkey maxkey | standard
DEMO_IDP_BASE http://127.0.0.1:18098 IdP 地址
DEMO_CLIENT_ID demo-system 客户端 ID
DEMO_CLIENT_SECRET 空 为空则自动用 PKCE
DEMO_REDIRECT_URI http://127.0.0.1:<port>/oauth2/callback 须与注册的 redirect_uris 逐字符一致
DEMO_TRUST_IAP 1 是否信任 X-Auth-*

安全提示

模式 B 下应用无条件信任 X-Auth-*,因此端口不能让客户端直达,否则可伪造 X-Auth-User。生产上请只绑 127.0.0.1 / 只监听内网 / 防火墙白名单,或只经网关访问。 本样例为了同时演示模式 A 才直接暴露端口,DEMO_BIND 默认已是回环。

身份字段语义

sub / preferred_username / username(MaxKey /me)= 登录账号(如 alice); name / realname = 显示名(如 爱丽丝)。第三方系统按账号绑定用户时用前者。