企业级 SSO 接入实战，重点避坑：redirect_uri、Token脚本、用户映射
目录
[1.1 对接本质](#1.1 对接本质)
[1.2 对接目标](#1.2 对接目标)
[1.3 协议说明](#1.3 协议说明)
[2.1 元数据接口（推荐优先使用）](#2.1 元数据接口（推荐优先使用）)
[2.2 核心接口（Keycloak 示例）](#2.2 核心接口（Keycloak 示例）)
[2.3 必备参数](#2.3 必备参数)
[三、Keycloak 侧配置（客户侧）](#三、Keycloak 侧配置（客户侧）)
[3.1 创建 Client](#3.1 创建 Client)
[3.2 获取 Client Secret](#3.2 获取 Client Secret)
[3.3 配置 Redirect URI（最大坑点）](#3.3 配置 Redirect URI（最大坑点）)
[四、零信任 aTrust 配置（核心）](#四、零信任 aTrust 配置（核心）)
[4.1 阶段一：获取授权码（code）](#4.1 阶段一：获取授权码（code）)
[4.2 阶段二：获取 Token（关键步骤）](#4.2 阶段二：获取 Token（关键步骤）)
[🔧 Token 处理脚本（必须配置）](#🔧 Token 处理脚本（必须配置）)
[⚠️ 关键说明](#⚠️ 关键说明)
[4.3 阶段三：获取用户信息](#4.3 阶段三：获取用户信息)
[4.4 阶段四：注销配置（推荐）](#4.4 阶段四：注销配置（推荐）)
[5.1 redirect_uri 报错](#5.1 redirect_uri 报错)
[5.2 invalid_grant](#5.2 invalid_grant)
[5.3 UserInfo 获取失败](#5.3 UserInfo 获取失败)
[5.4 登录循环](#5.4 登录循环)
[5.5 变量引用错误](#5.5 变量引用错误)
[核心 4 条](#核心 4 条)
一、场景说明
1.1 对接本质
在企业实际项目中，零信任对接 OAuth2 的本质并不是"实现认证"，而是：
接入已有身份系统（如 Keycloak），复用认证能力
典型特点：
-
企业已部署统一身份平台（Keycloak / Azure AD 等）
-
零信任不维护本地账号
-
所有认证由身份中心完成
1.2 对接目标
本次对接的核心目标：
-
实现统一 SSO（单点登录）
-
用户使用企业账号登录零信任
-
零信任专注访问控制（认证交由OIDC服务）
1.3 协议说明
本方案使用：
OAuth2 + OIDC（OpenID Connect）
区别说明：
-
OAuth2：授权框架（获取 access_token）
-
OIDC：身份层（获取用户信息 userinfo / id_token）
👉 本文涉及 userinfo、openid scope，属于 OIDC 标准流程
二、对接前提（必须提前获取）
⚠️ 实施第一步：先拿参数，再配置
2.1 元数据接口（推荐优先使用）
Keycloak 提供标准 OIDC 发现接口：
http://{host}:{port}/realms/{realm}/.well-known/openid-configuration
示例：
http://10.253.253.66:8080/realms/demo/.well-known/openid-configuration
作用：
-
自动获取所有端点地址
-
避免手动填写错误
2.2 核心接口（Keycloak 示例）
| 接口用途 | 地址 | 说明 |
|---|---|---|
| 认证地址 | /protocol/openid-connect/auth |
获取 code |
| Token 地址 | /protocol/openid-connect/token |
获取 access_token |
| 用户信息 | /protocol/openid-connect/userinfo |
获取用户信息 |
| 注销接口 | /protocol/openid-connect/logout |
单点登出 |
2.3 必备参数
| 参数 | 说明 | 示例 |
|---|---|---|
| client_id | 客户端 ID | atrust |
| client_secret | 客户端密钥 | ****** |
| redirect_uri | 回调地址（必须完全一致） | https://xxx/passport/... |
| scope | 权限范围 | openid profile email |
三、Keycloak 侧配置（客户侧）
3.1 创建 Client
路径：
Realm → Clients → Create
配置：
| 配置项 | 值 |
|---|---|
| Client ID | atrust |
| Client Protocol | openid-connect |
| Client authentication | ON |
| Standard Flow | ON（授权码模式） |
3.2 获取 Client Secret
路径：
Clients → atrust → Credentials
3.3 配置 Redirect URI（最大坑点）
路径：
Clients → atrust → Settings → Valid Redirect URIs
示例：
https://xxxxxx.top:4430/passport/v1/auth/httpsOauth2
强制要求：
-
协议一致（http/https）
-
域名一致
-
端口一致
-
路径完全一致
👉 任何一个字符不一致都会报错
四、零信任 aTrust 配置（核心）
4.1 阶段一：获取授权码（code）
-
请求方式：GET
-
核心参数：
response_type=code
client_id=xxx
redirect_uri=xxx
scope=openid profile email
- 返回：
👉 提取 code → 存入 env.code
4.2 阶段二：获取 Token（关键步骤）
-
请求方式：POST
-
请求头：
Content-Type: application/x-www-form-urlencoded
请求体参数：
| 参数 | 配置值 | 说明 |
|---|---|---|
| grant_type | authorization_code | 固定值 |
| code | {{env.code}} | 引用上一阶段获取的授权码（关键语法：双大括号） |
| client_id | atrust | 客户端ID |
| client_secret | FSIF6POw2R7p3I0Rjsc9kH1MRnxvVFRp | 客户端密钥 |
| redirect_uri | https://xxxxxx.top:4430/passport/v1/auth/httpsOauth2 | 必须与Authorization阶段一致 |
🔧 Token 处理脚本（必须配置）
function AfterResponse(response, result) {
// TODO: 在此添加nodejs代码
env.access_token =JSON.parse(response.body).access_token;
result.access_token = env.access_token;
}
AfterResponse(response, result);
⚠️ 关键说明
-
env：aTrust 内置环境变量对象 -
用于跨阶段传递数据（类似 session）
👉 不写脚本 = 后续 UserInfo 必失败
4.3 阶段三：获取用户信息
- 请求方式：GET
Authorization: Bearer {{env.access_token}}
提取字段
preferred_username
👉 映射为零信任用户名
4.4 阶段四：注销配置（推荐）
配置：
/logout
作用：
-
清理 Keycloak 会话
-
避免退出后自动登录
五、高频问题排查（实战）
5.1 redirect_uri 报错
现象
invalid_redirect_uri
原因
- 回调地址不一致
排查
-
逐字符核对：
-
协议
-
域名
-
端口
-
路径
-
5.2 invalid_grant
现象
- token 获取失败
原因
-
code 已使用 / 过期
-
redirect_uri 不一致
排查
-
重新获取 code
-
检查 redirect_uri
5.3 UserInfo 获取失败
现象
- 无法获取用户信息
原因
-
scope 未包含 openid
-
access_token 未正确传递
排查
-
scope 必须包含 openid
-
检查 token 脚本执行
5.4 登录循环
现象
- 一直跳转登录
原因
-
token 未写入 env
-
用户字段未正确提取
5.5 变量引用错误
错误写法
env.access_token
正确写法
{{env.access_token}}
六、实施经验总结
核心 4 条
-
先拿接口文档，再配置
-
redirect_uri 是最大坑点
-
Token 脚本是核心步骤
-
建议配置logout，避免会话残留
总结
本质上，这类对接只需抓住两点：
1️⃣ redirect_uri 必须完全一致
2️⃣ access_token 必须正确获取并传递
掌握这两个关键点，
无论是 Keycloak、Azure AD 还是其他 OIDC 服务，都可以快速完成对接。