Files
sso/tests/demo-system

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

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

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

配合 scripts/run-local-e2e.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 = 显示名(如 爱丽丝)。第三方系统按账号绑定用户时用前者。