本文是 V-56「部署集成验收项」的实操手册,与 配套设计说明(服务端 SSO 设计章节) 互补:§5.6 讲设计意图,本文讲「客户 IT 拿到TrueAGT后,如何对接自己的 IdP 真正跑通」。 设计定位回顾:真实 SSO 下 IdP 是身份唯一权威,TrueAGT不存用户密码、不校验口令;用户由 IdP 认证,TrueAGT按 id_token 映射/创建本地账号。
本软件的 SSO 只支持 OIDC Authorization Code 模式 + id_token 用 HS256(HMAC-SHA256,共享 client_secret)验签。
⚠️ 最关键的坑:绝大多数现成 IdP(Keycloak / Authentik / Auth0 / 各大云服务 / Google / GitHub…)默认用 RS256(非对称、JWKS)签 id_token。TrueAGT当前不会用 RS256 验签(那样要引入加密依赖,破零依赖红线)。因此:
client_secret 完全一致的共享密钥;或下面分「TrueAGT侧配置」「IdP 侧配置」「必带 claims」「验证」「排错」「安全」六部分讲清。
config.json)SSO 配置位于 config.json 的 server.auth.sso。修改后须重启 web.py 才生效(配置在启动时加载,不走热更新)。
{
"server": {
"auth": {
"sso": {
"enabled": true,
"provider": "oidc",
"issuer": "https://keycloak.example.com/realms/trueagt",
"metadata_url": "",
"client_id": "trueagt",
"client_secret": "<与 IdP 客户端密钥完全一致的长随机串>",
"redirect_uri": "https://trueagt.example.com/api/sso/callback",
"scopes": "openid profile email",
"username_claim": "email",
"auto_provision": true,
"default_role": "user",
"pkce": false
}
}
}
}
| 字段 | 说明 | 注意 |
|---|---|---|
enabled | 总开关 | true 才启用 |
provider | 固定 oidc | 当前仅 OIDC |
issuer | IdP 的 issuer 标识符 | 必须和 id_token 的 iss claim 完全一致(含 http/https、域名、路径,结尾不要多斜杠)。TrueAGT据此拼 .well-known/openid-configuration,并校验 iss |
metadata_url | 发现文档地址(可选) | 留空则自动用 issuer + /.well-known/openid-configuration |
client_id | IdP 里注册的 Client ID | 同时作为 aud 校验值 |
client_secret | HS256 共享密钥 | 既用于令牌端点 client_secret_post 认证,也用于验签 id_token。敏感,勿提交(已在 .gitignore 忽略 config.json) |
redirect_uri | 回调地址 | 必须等于 IdP 里注册的 Redirect URI,形如 https://<TrueAGT公网地址>/api/sso/callback |
scopes | 请求的 scope | 默认 openid profile email;email 必带(见 username_claim) |
username_claim | 用来映射本地用户名的 claim | 默认 email;id_token 必须携带该 claim 且值唯一稳定 |
auto_provision | 首次登录自动建号 | 默认 true;false 时仅允许 sso_sub 已绑定的既有账号登录 |
default_role | 自动建号的默认角色 | user 或 admin |
pkce | 是否启用 PKCE(S256) | 默认 false;true 时 IdP 须支持 PKCE |
前端登录页会在 SSO 启用时显示「使用企业账号登录(SSO)」按钮;启动后GET /api/auth/config的sso字段可见启用状态(已脱敏,不含client_secret)。
https://<TrueAGT公网地址>/api/sso/callback(与 redirect_uri 一字不差)。openid、profile、email(保证 email claim 下发)。client_secret_post(或 client_secret_basic);TrueAGT用 POST 表单带 client_id+client_secret。client_secret(最关键,见第 1 节)。iss/aud/sub/email/nonce/exp(标准 OIDC 基本都含,HS256 与 nonce 回显需确认)。trueagt),建 Client(如 trueagt),Client Type = OpenID Connect。https://trueagt.example.com/api/sso/callback(精确匹配,可加 /* 兜底)。Client secret;记下 Client ID 与 Client Secret。HS256(默认常是 RS256,必须改)。email claim 可能不下发)。email scope 已映射到该 client(默认 email scope 会下发 email/email_verified)。issuer = https://<keycloak>/realms/trueagt(无结尾斜杠),client_id = trueagt,client_secret = Credentials 页的 secret。openid email)、签名算法。TrueAGT verify_jwt_hs256 逐项校验,任一不符即拒绝登录:
| claim | 要求 | 对应配置 |
|---|---|---|
头部 alg | 必须为 HS256(HMAC-SHA256,密钥 = client_secret) | — |
iss | 字符串精确等于 issuer | server.auth.sso.issuer |
aud | 含 client_id(字符串或数组均可) | server.auth.sso.client_id |
sub | 必存在,用户唯一标识 | → 存为 sso_sub,账号匹配/创建主键 |
email(或 username_claim) | 必存在,作为本地用户名 | server.auth.sso.username_claim(默认 email) |
nonce | 必须等于TrueAGT授权时发的 nonce(防重放) | TrueAGT随机生成,IdP 须原样回显 |
exp | 必存在且在有效期(容差 5s) | 标准 |
令牌端点响应 JSON 中必须包含 id_token 字段(TrueAGT只消费 id_token,不依赖 access_token)。
GET /api/sso/authorize → 302 跳 IdP 授权端点(带 response_type=code、client_id、redirect_uri、scope、state、nonce;pkce=true 时附 code_challenge)。code 重定向回 redirect_uri?code=...&state=...。GET /api/sso/callback 用 code 换 id_token(POST 令牌端点,client_secret_post),HS256 验签 + 校验 iss/aud/sub/email/nonce/exp。sso_sub 匹配既有账号;未匹配则按 username_claim JIT 自动建号(不存密码)→ 签发TrueAGT会话令牌 → 302 回 /?sso_token=...,前端自动登录。state 有效期 600 秒(10 分钟),超时或重放会要求重新发起登录。
web.py 后 curl -s http://127.0.0.1:8765/api/auth/config | python -m json.tool
应看到 "sso": { "enabled": true, "issuer": "...", ... } 且不含 client_secret。
curl -s -H "Authorization: Bearer <token>" http://127.0.0.1:8765/api/auth/me
返回中 "auth_source": "sso" 表示走的是 SSO 身份。
auto_provision=true 时,首次用某 IdP 身份登录即创建本地账号(用户名 = email,角色 = default_role)。若本地已存在同名账号,则绑定该 sso_sub(不会新建冲突账号)。auto_provision=false 时,仅允许 sso_sub 已绑定的既有账号登录;新身份会报错「未开启自动建号」。如需预置,可先临时开启 auto_provision 让其首次登录绑定,再关回。status 置为 disabled(登录会被拒「该 SSO 账号已被停用」)。password_hash/salt 为空,不能用密码登录,管理员也无法重置其密码(V-55 零知识兜底)。找回/改密都在 IdP 侧。config.json 的 server.auth.sso 后必须重启 web.py(Python 配置启动时加载)。ProxyHandler({})),因此自托管/内网 IdP(含 localhost)即便本机配了代理也能连通。| 现象 / 错误 | 根因 | 解决 |
|---|---|---|
| 登录页无 SSO 按钮 | sso.enabled 未 true 或服务未重启 | 检查 enabled=true 并重启 web.py |
id_token 签名校验失败 (401) | IdP 用 RS256 签,或 client_secret 与 IdP 不一致 | 把 IdP 签名算法改为 HS256,密钥与TrueAGT client_secret 完全一致 |
id_token 签发方(iss=…)与配置不符 (401) | issuer 与 id_token iss 字符串不一致(多斜杠 / http↔https / realm 路径错) | issuer 末尾去斜杠、协议与域名严格对齐 IdP 实际 iss |
id_token 受众(aud)与 client_id 不符 (401) | client_id 不匹配,或 IdP 把 aud 设成别的 | 确认 client_id 与 IdP Client ID 完全一致 |
id_token nonce 不匹配(疑似重放) (401) | IdP 未把 nonce 回显到 id_token,或时钟偏移 >5s | 确认 IdP 回显 nonce;校准TrueAGT与 IdP 主机时钟 |
id_token 已过期 (401) | 时钟偏移或 exp 过短 | 校准时钟;延长 IdP id_token 有效期 |
state 无效或已过期 (400) | 超过 600s 或重放 | 重新点 SSO 登录按钮发起 |
id_token 缺少 email (400) | IdP 未下发 username_claim 对应 claim | IdP 侧为该 client 映射并下发 email scope/claim |
该 IdP 身份未绑定本地账号,且未开启自动建号 (403) | auto_provision=false 且无匹配账号 | 开启 auto_provision,或预建并绑定账号 |
client_secret 是 HS256 的签名密钥:一旦泄露,攻击方可伪造任意 id_token。请使用长随机串、HTTPS 传输、定期轮换,并妥善保管(勿入版本库)。audit_log(sso_login / sso_login JIT),可在管理端审计页查看。users 表 auth_source/sso_idp/sso_sub,SCHEMA_VERSION 11→12)、零依赖 HS256 决策见 配套设计说明(服务端 SSO 设计章节)。sso.py、accounts.py 与 web.py 的 /api/sso/* 路由,及 test_sso.py(逻辑层 14/14)、test_sso_http.py(HTTP 端到端 5/5)。