零信任平台简易 SSO 对接指南
1. 概述
什么是简易 SSO？
与其他 SSO 方式的区别
| SSO 方式 | 复杂度 | 开发量 | 适用场景 |
|---|---|---|---|
| 简易 SSO | ⭐ | 极低 | 内部应用、快速对接 |
| OAuth 2.0 | ⭐⭐⭐ | 中等 | 公开应用、需精细授权 |
| SAML | ⭐⭐⭐⭐ | 较高 | 企业级跨域联邦认证 |
| CAS | ⭐⭐⭐ | 中等 | 传统企业 CAS Server 已有场景 |
前置条件
2. 架构原理
整体流程
零信任网关
┌─────────────────┐
① 用户通过零信任门户 │ 1. SSL 终止 │
完成身份认证 │ 2. 身份校验 │
│ │ 3. Header 注入 │
▼ └───────┬─────────┘
┌──────────┐ ② 已认证请求 ③ 注入 SSO Header
│ 用户浏览器 │ ──────────────────────► ─────────────────► ┌──────────┐
└──────────┘ (经过网关) │ 业务系统 │
└──────────┘
④ 校验 Header
⑤ 自动登录
⑥ 建立会话详细认证流程
用户浏览器 零信任网关 业务系统后端
│ │ │
│ 1. 访问应用域名 │ │
│ ─────────────────────► │ │
│ │ │
│ 2. 未认证,跳转门户登录 │ │
│ ◄───────────────────── │ │
│ │ │
│ 3. 用户完成门户认证 │ │
│ ─────────────────────► │ │
│ │ │
│ 4. 建立信任会话 │ │
│ ◄───────────────────── │ │
│ │ │
│ 5. 再次访问应用 │ │
│ ─────────────────────► │ │
│ │ 6. 注入 SSO Header │
│ │ 转发给后端 │
│ │ ─────────────────────► │
│ │ │ 7. 解析 Header
│ │ │ 8. 校验签名
│ │ │ 9. 校验可信 IP
│ │ │ 10. 查找/创建用户
│ │ │ 11. 建立本地会话
│ │ 12. 返回响应 │
│ ◄─────────────────────────────────────────────────│
│ │ │
│ 13. 后续请求使用本地会话 │ │
│ ─────────────────────► │ ─────────────────────► │ (会话优先,不走SSO)推荐认证优先级
| 优先级 | 认证方式 | 触发条件 |
|---|---|---|
| 1️⃣ | 本地会话（JWT/Session） | 请求携带有效的会话凭证 |
| 2️⃣ | 简易 SSO | 无本地会话且请求含 SSO Header |
| 3️⃣ | 其他认证方式 | API Key、LDAP 等 |
💡 关键设计：本地会话优先于 SSO。SSO 首次认证通过并建立本地会话后，后续请求走本地会话快速通道，不再重复校验 SSO Header，以减少性能开销。
3. 零信任网关侧配置
3.1 管控后台操作步骤
1.
2.
3.
4.
5.
6.
3.2 关键配置项
| 配置项 | 说明 | 示例值 |
|---|---|---|
| SSO 模式 | 选择 简易 SSO | 简易 SSO |
| 通信密钥 | 用于 MD5 签名计算的共享密钥，两端必须完全一致 | （由平台自动生成） |
3.3 网关注入的 HTTP Header
| Header 名称 | 必传 | 说明 | 示例值 |
|---|---|---|---|
X-SSO-UID | ✅ | 用户唯一标识（用户名） | zhangsan |
X-SSO-SIGN | ✅ | MD5 签名（用于防伪校验） | 3f4400901f1cf095dca6cd01a442ab20 |
X-SSO-RSR-IP | ✅ | 网关代理 IP（来源 IP） | 192.168.1.100 |
X-SSO-MAIL | ❌ | 用户邮箱（如有） | zhangsan@example.com |
X-SSO-CN | ❌ | 用户中文名（URL 编码） | %E5%BC%A0%E4%B8%89（张三） |
4. 业务系统侧配置
4.1 所需配置项
| 配置项 | 必填 | 类型 | 说明 |
|---|---|---|---|
SSO_ENABLED | ✅ | bool | 总开关。设为 false 即可立即关闭 SSO（逃生机制） |
SSO_TOKEN_SECRET | ✅ | string | 通信密钥，需与网关管控后台完全一致 |
SSO_TRUSTED_IPS | ✅ | string | 允许发送 SSO Header 的网关 IP 白名单，防止伪造 |
4.2 配置示例（以环境变量为例）
4.3 可信 IP 配置示例
⚠️ 重要：可信 IP 必须设置为零信任网关的实际回源 IP 地址。这是简易 SSO 安全性的核心保障——如果攻击者无法从可信 IP 发送请求，即使伪造了 SSO Header 也会被拒绝。
5. 签名算法详解
5.1 算法说明
5.2 签名公式
sign = MD5( URI + UID + RSR_IP + User-Agent + token_secret ).toLowerCase()URI、X-SSO-UID、X-SSO-RSR-IP、User-Agent、token_secret5.3 计算示例
zhangsan 通过网关（IP: 192.168.1.100）访问 /api/user/profile| 字段 | 值 |
|---|---|
| URI | /api/user/profile |
| X-SSO-UID | zhangsan |
| X-SSO-RSR-IP | 192.168.1.100 |
| User-Agent | Mozilla/5.0 |
| token_secret | 01234567890123456789 |
/api/user/profilezhangsan192.168.1.100Mozilla/5.001234567890123456789💡 你可以直接运行上面的 Python 代码验证。如果你的实现得到相同的输出 740883728e11e55036904f4a4f99e63b，说明签名算法实现正确。
5.4 各语言签名校验参考
740883728e11e55036904f4a4f99e63b。Python
Go
JavaScript (Node.js)
Java
5.5 空字段跳过示例
RSR-IP 为空时：6. 对接验证
6.1 业务系统后端校验逻辑（伪代码）
函数 handleRequest(request):
# 1️⃣ 优先检查本地会话（JWT/Session）
如果 request 包含有效的本地会话:
返回 已认证用户
# 2️⃣ 检查 SSO Header
如果 SSO 功能已启用:
uid = request.headers["X-SSO-UID"]
sign = request.headers["X-SSO-SIGN"]
ip = request.headers["X-SSO-RSR-IP"]
如果 uid 和 sign 都不为空:
# 校验可信 IP
如果 ip 不在 SSO_TRUSTED_IPS 白名单中:
返回 403 "来源 IP 不在可信列表中"
# 校验 MD5 签名
expected = MD5(request.path + uid + ip + request.userAgent + SSO_TOKEN_SECRET)
如果 sign != expected:
返回 403 "签名校验失败"
# 查找或创建用户
user = 数据库.查找(username == uid)
如果 user 不存在:
user = 数据库.创建新用户(username=uid, ...)
# 建立本地会话（后续请求直接走本地会话，不再走 SSO）
建立会话(user)
返回 已认证用户
# 3️⃣ 其他认证方式 ...
返回 401 "未认证"6.2 使用 curl 模拟验证
步骤 1：计算测试签名
步骤 2：携带 SSO Header 发送请求
期望结果
< HTTP/1.1 200 OK
{"username":"testuser","auth_source":"sso", ...}✅ 看到 200 响应 + 用户信息就说明对接成功！
6.3 推荐验证场景
| # | 测试场景 | 操作要点 | 期望结果 |
|---|---|---|---|
| 1 | 正常 SSO 认证（首次访问） | 携带完整、正确的 SSO Header | 200 + 建立会话 |
| 2 | 本地会话优先（已有会话时） | 携带上一步返回的 Cookie/Token | 200（走本地会话） |
| 3 | 降级（无 SSO + 无会话） | 不携带任何认证信息 | 401 未认证 |
| 4 | 非可信 IP | X-SSO-RSR-IP 设为非白名单IP | 403 拒绝 |
| 5 | 错误签名 | X-SSO-SIGN 设为任意错误值 | 403 拒绝 |
| 6 | 用户被禁用 | 管理后台禁用该用户后重试 | 403 账号已禁用 |
6.4 自验签名算法
| 字段 | 值 |
|---|---|
| URI | /api/user/profile |
| UID | zhangsan |
| RSR-IP | 192.168.1.100 |
| User-Agent | Mozilla/5.0 |
| token_secret | 01234567890123456789 |
| 期望签名 | 740883728e11e55036904f4a4f99e63b |
7. 逃生机制
⚠️ 逃生机制是保障系统可用性的最后一道防线。当 SSO 出现问题导致无法登录时，必须能够快速恢复访问。
7.1 一键关闭 SSO（最快捷）
SSO_ENABLED 设为 false 并重启服务，即可立即关闭 SSO，切换回本地登录模式：7.2 逃生场景一览
| 场景 | 影响 | 应急操作 |
|---|---|---|
| 零信任网关宕机 | SSO 认证不可用 | 关闭 SSO_ENABLED + 重启服务 |
| 通信密钥被意外更改 | 所有 SSO 请求签名校验失败 | 同步更新 SSO_TOKEN_SECRET |
| 网关 IP 变更 | 所有 SSO 请求被可信 IP 拦截 | 更新 SSO_TRUSTED_IPS |
| SSO 用户被误删 | 特定用户无法登录 | 在管理后台重建用户 |
| 需要临时绕过 SSO 进行维护 | - | 关闭 SSO_ENABLED + 重启服务 |
7.3 保底管理员账号（强烈建议）
🔑 始终保留至少一个本地管理员账号（非 SSO 用户），并确保该账号有密码。
1.
role=admin 的本地账号2.
3.
7.4 SSO 用户应急密码设置
8. 故障排查
8.1 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 |
|---|---|---|
| 登录后返回 401 未认证 | SSO 功能未启用 | 检查 SSO_ENABLED 配置 |
| 登录后返回 403 IP 不可信 | 网关 IP 不在白名单中 | 检查 SSO_TRUSTED_IPS 和实际 IP |
| 登录后返回 403 签名校验失败 | 通信密钥不一致 | 对比两端 token_secret |
| 用户名正确但无中文名 | X-SSO-CN Header 未传递 | 检查网关 Header 注入配置 |
| 首次用户无邮箱信息 | X-SSO-MAIL Header 未传递 | 检查网关 Header 注入配置 |
| SSO 正常但刷新页面又弹登录框 | 本地会话未正确建立 | 检查 Cookie/Session 设置 |
| 通过门户能访问，直接访问域名无法登录 | 绕过了网关直接访问后端 | 确认浏览器访问的是网关域名 |
8.2 签名对比排查法
8.3 排查注意事项
| 要素 | 常见陷阱 |
|---|---|
| URI | 仅 URL 的 path 部分，不含域名和查询参数（如 /api/user/me） |
| User-Agent | 必须是完整字符串，不同浏览器/curl 版本差异大，注意完整复制 |
| 空字段 | 空字段不参与拼接——确认拼接逻辑中正确跳过了空值 |
| 大小写 | 最终签名必须转为小写后比较 |
| 编码 | 所有字段使用 UTF-8 编码后再计算 MD5 |
| 无分隔符 | 字段之间直接拼接，不插入任何分隔符 |
9. 安全注意事项
9.1 简易 SSO 的安全模型
┌─────────────────────────────────────────┐
│ 第 1 层：网络隔离 │
│ 后端仅接受来自可信 IP 的 SSO 请求 │
│ （SSO_TRUSTED_IPS 白名单） │
├─────────────────────────────────────────┤
│ 第 2 层：签名校验 │
│ MD5(URI+UID+IP+UA+Secret) 防篡改 │
│ 密钥仅网关和业务系统知晓 │
├─────────────────────────────────────────┤
│ 第 3 层：内网环境 │
│ 简易 SSO 设计上假定运行在可控内网 │
│ 外网攻击者无法直接触达后端 │
└─────────────────────────────────────────┘9.2 安全建议
| 项目 | 建议 |
|---|---|
| 🔑 通信密钥 | 使用随机生成的强密钥（≥32 字符），定期轮换 |
| 🌐 可信 IP | 严格限定为网关 IP，切勿设为 0.0.0.0/0 |
| 🔒 网络隔离 | 后端服务不应直接暴露到公网，应仅通过网关访问 |
| 👤 管理员账号 | 始终保留本地 admin 账号作为逃生通道 |
| 📝 审计日志 | 记录每次 SSO 登录事件，定期检查异常登录 |
| ⏰ 密钥轮换 | 建议每 3-6 个月更换通信密钥（两端同步更改 + 重启服务） |
9.3 已知局限
| 局限点 | 说明 |
|---|---|
| 无时间戳/Nonce | 签 名中不含时间因子，理论上存在重放攻击风险。安全性依赖可信 IP + 内网。 |
| MD5 算法 | MD5 已不被视为密码学安全的哈希算法，但在签名校验场景中配合密钥仍可用。 |
| User-Agent 参与签名 | 不同浏览器的 UA 不同，签名也不同。这是防篡改设计，但调试时需注意。 |
10. FAQ
Q1: SSO 用户首次登录后的角色和权限怎么设置？
Q2: 修改通信密钥会影响在线用户吗？
Q3: SSO 和本地登录可以同时使用吗？
Q4: 网关 IP 变了怎么办？
SSO_TRUSTED_IPS 为新 IP 并重启服务即可。建议预先使用 CIDR 格式（如 192.168.1.0/24）减少 IP 变更影响。Q5: 如何禁止某个 SSO 用户登录？
403 错误。Q6: SSO 用户的姓名和邮箱能自动同步吗？
X-SSO-MAIL 和 X-SSO-CN Header，若有变化则自动更新本地用户信息。Q7: 如何区分用户是通过 SSO 还是本地登录的？
auth_source 字段，SSO 创建的用户标记为 sso，本地注册的用户标记为 local。附录：上线 Checklist
SSO_ENABLED 已设为 trueSSO_TOKEN_SECRET 与网关侧一致SSO_TRUSTED_IPS 设为网关的实际回源 IP修改于 2026-03-12 05:51:47