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