通讯录集成-SCIM
适用版本与验收边界
概述
集成价值
| 价值 | 说明 |
|---|---|
| 标准协议 | 基于 SCIM 2.0 标准协议，兼容性广 |
| 广泛适用 | 支持任意提供 SCIM 接口的身份源系统 |
| 自动化同步 | 通过标准 API 实现用户数据自动同步 |
准备工作
上游身份源要求
| 要求 | 说明 |
|---|---|
| SCIM 服务端地址 | 上游系统需提供 SCIM 2.0 协议的 endpoint URL |
| 认证 Token | 上游系统需提供 Bearer Token 用于 API 认证 |
| SCIM 接口 | 支持 /Users 和 /Groups 资源端点的 GET 请求 |
| 网络连通性 | 专属集成平台能够访问 SCIM 服务端地址 |
专属集成平台要求
| 要求 | 说明 |
|---|---|
| 管理员权限 | 拥有专属集成平台的管理员权限 |
| 通讯录集成权限 | 具备创建和管理通讯录集成连接器的权限 |
操作步骤
步骤 1：创建 SCIM 集成连接器
1.
2.
3.
4.
确认定位目标连接器入口中的关键配置
步骤 2：配置连接信息
| 参数名称 | 说明 | 填写指南 |
|---|---|---|
| 名称 | 连接器显示名称 | 自定义名称，如“SCIM-OKTA” |
| SCIM 服务地址 | SCIM 2.0 协议 endpoint URL | 如 https://example.com/scim/v2 |
| 认证方式 | API 认证方式 | 选择 Bearer Token |
| Bearer Token | SCIM 接口认证令牌 | 从上游客服系统获取 |
| 自定义 Headers | 额外的 HTTP 请求头 | 按需添加，格式为 Key:Value |
提示：SCIM 服务地址通常以 /scim/v2结尾。不确定时请参考上游系统的 SCIM 集成文档。
确认查看连接器创建表单中的关键配置
步骤 3：配置同步策略
| 参数名称 | 说明 | 建议配置 |
|---|---|---|
| 同步范围 | 同步的数据类型 | 用户和组 |
| 数据在本地挂载节点 | 同步数据在平台的挂载位置 | SCIM 认证 |
| 挂载方式 | 组织架构挂载方式 | 通常选择“在选择节点下新建” |
| 同步方式 | 数据同步策略 | 初次配置“手动全量同步”，验证后改为“自动增量同步” |
| 同步周期 | 自动同步的频率 | 建议 6 小时 |
| 账号关联 | 用户映射关系 | 常用“SCIM userName 与平台用户名” |
重要：首次配置建议选择「手动全量同步」，验证数据准确性后再改为「自动增量同步」。
确认查看连接信息配置区域中的关键配置
步骤 4：配置属性映射
| SCIM 属性 | 平台属性 | 映射方式 | 说明 |
|---|---|---|---|
| userName | username | 创建且更新 | 用户名 |
| displayName | display_name | 创建且更新 | 显示名称 |
| emails[type eq "work"].value | 创建且更新 | 工作邮箱 | |
| phoneNumbers[type eq "mobile"].value | phone_number | 创建且更新 | 手机号码 |
| title | title | 创建且更新 | 职位 |
| active | active | 创建且更新 | 用户状态 |
| externalId | connector_user_id | 创建且更新 | 外部系统用户 ID |
重要：确保 userName或externalId等唯一标识字段正确映射。SCIM 属性可能因上游系统实现差异而不同，请根据实际 API 返回结构调整映射。
确认查看属性映射配置区域中的关键配置
步骤 5：执行同步并验证
1.
2.
3.
4.
验证结果
| 验证项 | 操作方法 |
|---|---|
| 连接测试 | 输入上游系统中已存在的用户 userName，验证 SCIM 接口连通性 |
| 用户数据验证 | 在「用户管理」页面筛选 SCIM 连接器，抽查用户信息完整性 |
| 组结构验证 | 在「组织管理」页面检查组是否正确映射为组织架构 |
| 增量同步验证 | 在上游系统中变更用户后触发同步，验证变更是否同步 |
常见问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 连接测试失败 | SCIM 地址不正确、Token 无效、网络不通 | 检查 endpoint URL 和 Token 有效性，确认网络可达 |
| HTTP 401 错误 | Bearer Token 无效或已过期 | 重新获取有效的 Bearer Token |
| 响应数据格式异常 | SCIM 实现不完全符合标准 | 检查上游系统 SCIM 接口返回的数据格式，调整属性映射 |
停用或回滚
修改于 2026-09-14 10:20:56