真实 SSO 接入指南

本文是 V-56「部署集成验收项」的实操手册,与 配套设计说明(服务端 SSO 设计章节) 互补:§5.6 讲设计意图,本文讲「客户 IT 拿到TrueAGT后,如何对接自己的 IdP 真正跑通」。 设计定位回顾:真实 SSO 下 IdP 是身份唯一权威,TrueAGT不存用户密码、不校验口令;用户由 IdP 认证,TrueAGT按 id_token 映射/创建本地账号。

1. 一句话结论(先读这条)

本软件的 SSO 只支持 OIDC Authorization Code 模式 + id_token 用 HS256(HMAC-SHA256,共享 client_secret)验签。

⚠️ 最关键的坑:绝大多数现成 IdP(Keycloak / Authentik / Auth0 / 各大云服务 / Google / GitHub…)默认用 RS256(非对称、JWKS)签 id_token。TrueAGT当前不会用 RS256 验签(那样要引入加密依赖,破零依赖红线)。因此:

下面分「TrueAGT侧配置」「IdP 侧配置」「必带 claims」「验证」「排错」「安全」六部分讲清。


2. TrueAGT侧配置(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
issuerIdP 的 issuer 标识符必须和 id_token 的 iss claim 完全一致(含 http/https、域名、路径,结尾不要多斜杠)。TrueAGT据此拼 .well-known/openid-configuration,并校验 iss
metadata_url发现文档地址(可选)留空则自动用 issuer + /.well-known/openid-configuration
client_idIdP 里注册的 Client ID同时作为 aud 校验值
client_secretHS256 共享密钥既用于令牌端点 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)。

3. IdP 侧配置

3.1 通用 OIDC 要点(任何 IdP 都满足这几条)

  1. 注册一个 Confidential Client(需要客户端密钥),启用 Authorization Code 流程。
  2. Redirect URI 精确填写:https://<TrueAGT公网地址>/api/sso/callback(与 redirect_uri 一字不差)。
  3. Scope 勾选 openid、profile、email(保证 email claim 下发)。
  4. 令牌端点客户端认证方式选 client_secret_post(或 client_secret_basic);TrueAGT用 POST 表单带 client_id+client_secret。
  5. 把 id_token 签名算法设为 HS256,密钥 = TrueAGT的 client_secret(最关键,见第 1 节)。
  6. 确保 id_token 含 iss/aud/sub/email/nonce/exp(标准 OIDC 基本都含,HS256 与 nonce 回显需确认)。

3.2 Keycloak(推荐,HS256 支持最干净)

3.3 Authentik / Zitadel / Pocket-Id 等

3.4 不支持的 IdP(当前限制)


4. id_token 必须包含的 claims(对接验收清单)

TrueAGT verify_jwt_hs256 逐项校验,任一不符即拒绝登录:

claim要求对应配置
头部 alg必须为 HS256(HMAC-SHA256,密钥 = client_secret)—
iss字符串精确等于 issuerserver.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)。

5. 登录流程回顾

  1. 用户点「使用企业账号登录(SSO)」→ TrueAGT GET /api/sso/authorize → 302 跳 IdP 授权端点(带 response_type=code、client_id、redirect_uri、scope、state、nonce;pkce=true 时附 code_challenge)。
  2. 用户在 IdP 完成认证(密码 / MFA / 企业策略均在 IdP 侧)。
  3. IdP 携 code 重定向回 redirect_uri?code=...&state=...。
  4. TrueAGT GET /api/sso/callback 用 code 换 id_token(POST 令牌端点,client_secret_post),HS256 验签 + 校验 iss/aud/sub/email/nonce/exp。
  5. 按 sso_sub 匹配既有账号;未匹配则按 username_claim JIT 自动建号(不存密码)→ 签发TrueAGT会话令牌 → 302 回 /?sso_token=...,前端自动登录。
state 有效期 600 秒(10 分钟),超时或重放会要求重新发起登录。

6. 启用后验证

  1. 配置生效检查:重启 web.py 后
   curl -s http://127.0.0.1:8765/api/auth/config | python -m json.tool

应看到 "sso": { "enabled": true, "issuer": "...", ... } 且不含 client_secret。

  1. 前端走通:登录页出现「使用企业账号登录(SSO)」→ 点击 → 跳 IdP → 登录 → 自动回到TrueAGT并已登录。
  2. 账号来源确认:登录后调用(或看账号页)
   curl -s -H "Authorization: Bearer <token>" http://127.0.0.1:8765/api/auth/me

返回中 "auth_source": "sso" 表示走的是 SSO 身份。

  1. 管理视图:用户管理列表里 SSO 用户带「SSO」徽标,且「重置密码」置灰(SSO 用户无本地密码,见 V-55)。

7. 账号管理与运维


8. 排错表(对照TrueAGT返回的错误文案)

现象 / 错误根因解决
登录页无 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 对应 claimIdP 侧为该 client 映射并下发 email scope/claim
该 IdP 身份未绑定本地账号,且未开启自动建号 (403)auto_provision=false 且无匹配账号开启 auto_provision,或预建并绑定账号

9. 安全建议


10. 与设计方案的关系

本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。