深信服零信任 aTrust 对接 Keycloak（OIDC）实战指南

企业级 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

正确写法

六、实施经验总结

核心 4 条

先拿接口文档，再配置
redirect_uri 是最大坑点
Token 脚本是核心步骤
建议配置logout，避免会话残留

总结

本质上，这类对接只需抓住两点：

1️⃣ redirect_uri 必须完全一致

2️⃣ access_token 必须正确获取并传递

掌握这两个关键点，

无论是 Keycloak、Azure AD 还是其他 OIDC 服务，都可以快速完成对接。