195 lines
10 KiB
Markdown
195 lines
10 KiB
Markdown
# 外部单点登录（External SSO）接入说明
|
||
|
||
## 功能概述
|
||
|
||
- 支持外部系统携带一次性 token 跳转本系统，实现免密单点登录。
|
||
- 去除了历史实现中的 payload 解密、nonce 强校验、自动建号与邮箱匹配等逻辑，所有账号均需在本地预先存在并保持映射关系。
|
||
- 前后端新增 `/system/sso/verify` 校验能力，返回标准的 `AuthLoginRespVO` 令牌信息，并记录审计与登录日志。
|
||
- 通过 `ExternalSsoClient` 抽象外部接口调用，可按需自定义实现或复用默认 HTTP 客户端封装。
|
||
|
||
## 关键组件
|
||
|
||
### 后端
|
||
|
||
- `ExternalSsoServiceImpl`：单点登录主流程，实现参数校验、外部用户查询、本地账号匹配、令牌签发与日志记录。
|
||
- `ExternalSsoStrategy`：定义按来源系统拆分的策略接口，不同系统可实现自定义的拉取与匹配逻辑。
|
||
- `DefaultExternalSsoStrategy`：默认策略实现，复用配置化的 HTTP 客户端与匹配顺序，可按优先级被自定义策略覆盖。
|
||
- `ExternalSsoClient`：获取外部用户信息的接口抽象。
|
||
- `DefaultExternalSsoClient`：基于 `RestTemplate` 的默认实现，支持 Header/Query/Body 占位符渲染、重试、响应字段映射、代理配置。
|
||
- `ExternalSsoClientConfiguration`：通过 `@Configuration` 在缺省情况下注册 `DefaultExternalSsoClient` Bean，允许业务自定义覆盖。
|
||
- `ExternalSsoProperties`：`external-sso.*` 配置项，包含开关、外部接口、账号映射、跨域等子配置；示例配置已同步到 `zt-module-system/zt-module-system-server/src/main/resources/application.yaml` 与 `zt-server/src/main/resources/application.yaml`。
|
||
- `ExternalSsoVerifyReqVO`：`POST /system/sso/verify` 请求载荷。
|
||
- `ExternalSsoUserInfo`：外部用户标准化模型，包含基础字段与自定义属性集合。
|
||
|
||
### 前端
|
||
|
||
- `src/router/modules/remaining.ts`：新增隐藏路由 `/externalsso`，用于回调页面。
|
||
- `src/views/Login/ExternalSsoCallback.vue`：处理 URL 参数、调用校验接口、落地令牌、跳转目标页面，异常时提示并引导返回登录页。
|
||
- `src/api/login/index.ts`：新增 `externalSsoVerify` 方法，请求 `/system/sso/verify` 并返回 `TokenType`。
|
||
|
||
## 调用流程
|
||
|
||
1. 外部系统完成本地认证后，构造 URL：`{本系统域名}/#/externalsso?x-token={外部token}&target={回跳地址}` 并跳转，可选附带 `sourceSystem` 指定来源系统。
|
||
2. Vue 页面 `ExternalSsoCallback` 解析查询参数，优先读取 `x-token`（兼容历史的 `token` 参数）并校验是否存在；缺失时终止流程并提示错误。
|
||
3. 前端调用 `POST /system/sso/verify`，请求体：
|
||
|
||
```json
|
||
{
|
||
"token": "外部系统颁发的 token",
|
||
"targetUri": "/#/dashboard", // 可选
|
||
"sourceSystem": "partner-a" // 可选
|
||
}
|
||
```
|
||
|
||
4. `ExternalSsoServiceImpl#verifyToken` 执行以下步骤：
|
||
|
||
- 校验功能开关与 token 有效性。
|
||
- 基于 `sourceSystem` 选择匹配的 `ExternalSsoStrategy`，若无匹配直接返回来源系统不支持。
|
||
- 通过策略触发 `ExternalSsoClient` 拉取外部用户信息（默认调用配置的 HTTP 接口）。
|
||
- 按策略内定义的匹配顺序（默认外部 ID → 用户名 → 手机号）查找本地账号，未命中直接返回 "未找到匹配的本地用户"。
|
||
- 校验账号状态是否启用，签发 OAuth2 访问令牌并记录登录日志（类型 `LOGIN_EXTERNAL_SSO`）。
|
||
- 生成操作审计日志，记录外部响应摘要、映射账号、目标地址、来源系统等信息。
|
||
|
||
5. 前端拿到 `AuthLoginRespVO`，通过 `authUtil.setToken`/`setTenantId` 持久化，随后跳转到整理后的 `targetUri`（默认 `/`）。
|
||
6. 当流程出现异常（例如 token 缺失、外部接口失败、账号不存在）时，后端返回对应错误码，前端弹出提示并清除本地缓存。
|
||
|
||
下图为时序示意：
|
||
|
||
```text
|
||
外部系统 -> 浏览器 -> Vue /externalsso -> POST /system/sso/verify -> ExternalSsoService -> ExternalSsoClient -> 外部用户接口
|
||
\-> OAuth2TokenService -> 登录日志/审计日志
|
||
```
|
||
|
||
## 前端细节
|
||
|
||
- `ExternalSsoCallback.vue` 对 `target`/`targetUri`/`redirect` 参数做统一解码与归一化，支持携带绝对地址或 hash 路由，防止开放跳转漏洞。
|
||
- 解析 URL 中的 `sourceSystem`（兼容 `source`、`systemCode`）并透传给后端，便于在多来源系统场景下选择策略。
|
||
- 在成功回调后调用 `router.replace`，保证不会产生历史记录；失败时引导用户回到 `/login` 并附带原目标地址。
|
||
- 通过 `buildErrorMessage` 兼容后端返回的 `msg`、`Error` 对象或字符串，统一展示错误提示。
|
||
|
||
## 后端流程拆解
|
||
|
||
- **开关与参数校验**：
|
||
- 关闭开关或缺少 token 时抛出 `EXTERNAL_SSO_DISABLED` / `EXTERNAL_SSO_TOKEN_MISSING`。
|
||
- **外部用户获取**：
|
||
- 默认客户端会在 `external-sso.remote` 中加载请求配置，支持 GET/POST 等多种场景。
|
||
- 占位符：`${externalUserId}`（初始值为 token）、`${shareToken}`/`${token}`（共享服务访问 token）、`${xToken}`（原始回调 token）、`${targetUri}`、`${sourceSystem}`。
|
||
- 会自动通过 `ShareServiceUtils` 获取共享服务访问 token，并写入 `ShareServiceProperties#tokenHeaderName` 对应的请求头。
|
||
- 请求体会以 JSON 形式发送 `{ "x-token": "回调参数中的 token" }`，满足上游接口 `S_BF_CS_01` 的要求。
|
||
- `validateResponse` 可按 `codeField` 与 `successCode` 校验业务状态，失败时抛出带详细信息的 `ExternalSsoClientException`。
|
||
- **本地账号匹配**：
|
||
- 使用 `mapping.order` 控制字段优先级；`custom.entries` 保存 "外部ID → 本地用户ID" 静态映射。
|
||
- 找不到用户或账号禁用时分别抛出 `EXTERNAL_SSO_USER_NOT_FOUND`、`EXTERNAL_SSO_USER_DISABLED`，均会同步写入登录日志。
|
||
- **令牌签发与日志**：
|
||
- 通过 `OAuth2TokenService#createAccessToken` 使用默认客户端 `CLIENT_ID_DEFAULT` 颁发本地访问令牌。
|
||
- `recordAuditLog` 把原始响应的 SHA-256 摘要、外部属性、token 摘要等写入操作日志，便于排查。
|
||
- `recordLoginLog` 记录登录行为并在成功时更新用户最后登录 IP。
|
||
|
||
## `ExternalSsoClient` 扩展
|
||
|
||
- 默认实现 `DefaultExternalSsoClient` 由 `ExternalSsoClientConfiguration` 自动注册，若需要接入其它协议，可在任意配置类中自定义：
|
||
|
||
```java
|
||
@Bean
|
||
public ExternalSsoClient customExternalSsoClient(...) {
|
||
return new MyExternalSsoClient(...);
|
||
}
|
||
```
|
||
|
||
- 默认实现要点：
|
||
- 按配置构造 `RestTemplate`，支持连接/读取超时、HTTP 代理、重试次数。
|
||
- 解析 JSON 响应，将指定字段映射到 `ExternalSsoUserInfo`，并保留原始 data 节点到 `attributes`。
|
||
- 在解析失败、状态码异常时抛出带原始响应的 `ExternalSsoClientException`。
|
||
|
||
## 配置项参考
|
||
|
||
```yaml
|
||
external-sso:
|
||
enabled: true
|
||
system-code: example-partner
|
||
token:
|
||
secret: "shared-secret"
|
||
algorithm: AES
|
||
allowed-clock-skew-seconds: 60
|
||
max-age-seconds: 300
|
||
require-nonce: false
|
||
replay-protection-enabled: false
|
||
remote:
|
||
base-url: http://10.1.7.110
|
||
user-info-path: /api/sso/user
|
||
method: POST
|
||
headers:
|
||
Authorization: "Bearer ${token}"
|
||
query-params: {}
|
||
body:
|
||
userId: "${externalUserId}"
|
||
code-field: code
|
||
success-code: "0"
|
||
message-field: message
|
||
data-field: data
|
||
user-id-field: data.userId
|
||
username-field: data.username
|
||
nickname-field: data.nickname
|
||
email-field: data.email
|
||
mobile-field: data.mobile
|
||
tenant-id-field: data.tenantId
|
||
connect-timeout-millis: 3000
|
||
read-timeout-millis: 5000
|
||
retry-count: 1
|
||
proxy:
|
||
enabled: false
|
||
mapping:
|
||
order:
|
||
- EXTERNAL_ID
|
||
- USERNAME
|
||
- MOBILE
|
||
ignore-case: true
|
||
update-profile-on-login: false
|
||
custom:
|
||
entries:
|
||
partnerUser001: 10001
|
||
cors:
|
||
allowed-origins:
|
||
- https://partner.example.com
|
||
allowed-methods: ["OPTIONS", "POST"]
|
||
allowed-headers: ["Authorization", "Content-Type"]
|
||
allow-credentials: true
|
||
max-age: 1800
|
||
```
|
||
|
||
| 配置路径 | 说明 |
|
||
| --- | --- |
|
||
| `enabled` | 总开关，关闭后接口直接返回 `EXTERNAL_SSO_DISABLED` |
|
||
| `system-code` | 默认来源系统标识，可作为 `sourceSystem` 的缺省值及日志标签 |
|
||
| `token.*` | 若仍需解密/校验外部 token，可在自定义 `ExternalSsoClient` 内按需使用；默认实现仅透传 |
|
||
| `remote.*` | 外部接口 HTTP 调用参数、字段映射与超时控制，模板占位符支持 `externalUserId`、`shareToken`(`token`)、`xToken`、`targetUri`、`sourceSystem` |
|
||
| `mapping.order` | 本地账号匹配优先级，支持 `EXTERNAL_ID`、`USERNAME`、`MOBILE` |
|
||
| `mapping.custom.entries` | 外部用户标识到本地用户 ID 的静态映射表 |
|
||
| `cors.*` | 用于开放 `/system/sso/verify` 的跨域访问白名单 |
|
||
|
||
## 错误码与日志
|
||
|
||
- 错误码：
|
||
- `1_002_000_050`：功能未开启。
|
||
- `1_002_000_051`：token 缺失。
|
||
- `1_002_000_055`：外部接口异常，具体原因写入占位符。
|
||
- `1_002_000_056`：未匹配到本地用户。
|
||
- `1_002_000_057`：本地用户已禁用。
|
||
- `1_002_000_058`：来源系统不支持，需配置匹配的策略实现。
|
||
- 登录日志：使用 `LoginLogTypeEnum.LOGIN_EXTERNAL_SSO` 记录成功/失败。
|
||
- 操作日志：类型 `EXTERNAL_SSO/VERIFY`，包含外部用户 ID、映射账号、目标地址、来源系统、响应摘要等元数据。
|
||
|
||
## 注意事项
|
||
|
||
- 所有账号须提前维护映射，系统不会自动创建或按邮箱兜底匹配用户。
|
||
- `targetUri` 会在前端归一化，避免开放跳转风险；无合法目标时默认跳转首页。
|
||
- 确保外部接口返回的 JSON 字段与配置保持一致，必要时可通过 `remote.data-field` 指向具体节点。
|
||
- 若外部接口速度较慢或易失败，可提高 `retry-count`、超时时间或自定义客户端实现。
|
||
- 如需记录更多审计信息，可在 `ExternalSsoUserInfo#addAttribute` 注入自定义字段，审计日志会自动保留。
|
||
|
||
## 扩展与测试建议
|
||
|
||
- 通过提供新的 `ExternalSsoStrategy` 或 `ExternalSsoClient` Bean，可扩展不同来源系统的对接方式。
|
||
- 建议为主要错误场景编写集成测试：token 缺失、映射缺失、来源系统不支持、外部接口超时、账号被禁用等。
|
||
- 外部系统回调前可先调用 `/system/sso/verify` 联调接口验证配置是否正确，再接入正式流程。
|