连接属性映射用于告诉 identity：当外部身份提供商返回用户字段时，应该如何把这些字段写入标准用户属性、可写的自定义属性，或者权威部门归属。

本页包含

什么是属性映射

支持的连接家族

映射规则结构

MappingType 枚举值

目标属性名

源属性路径

如何编写和修改映射

典型映射示例

相关页面

什么是属性映射

连接属性映射是“按连接保存”的规则，用来决定上游登录资料怎样落到 identity。

典型目标包括：

把提供商字段 mail 写入 identity 的 email

把提供商字段 employeeId 写入某个自定义资料字段

写入固定值，例如 custom.source_system=provider_a

用上游部门外部 ID 驱动部门归属

每条规则都挂在某一个连接上，并在联邦登录运行时针对上游用户资料执行。

支持的连接家族

当前控制面 IDL 在以下连接家族上显式暴露了 AttributeMappings：

家族	是否支持 AttributeMappings	说明
OIDC	是	创建、更新、查询和列表响应中都已暴露
OAuth	是	创建、更新、查询和列表响应中都已暴露
SAML	是	新配置优先用 AttributeMappings；旧版 AttributeMapping 仅为兼容保留
WeCom	是	除了企业微信专属字段外，也支持显式属性映射
Token Exchange	是	与令牌校验规则一起暴露

映射规则结构

每条映射规则都使用 IdpAttributeMapping 结构。

字段	是否必填	作用
TargetAttributeName	是	要写入的 identity 目标属性
SourceAttributeName	对导入型和部门归属型必填；硬编码型可省略	要读取的上游字段或路径
MappingType	是	映射执行模式
AdditionalConfig	对硬编码型必填；其余两类不用	映射类型专属的 JSON 配置

示例结构：

MappingType 枚举值

当前连接模型支持三类映射类型。

MappingType 值	作用	需要配合的字段	说明
ATTRIBUTE_IMPORTER	从上游载荷读取值，再写入目标属性	SourceAttributeName	AdditionalConfig 必须为空
HARDCODED_VALUE	从 AdditionalConfig 中读取固定字面值写入目标属性	AdditionalConfig，格式为 {"value": ...}	SourceAttributeName 不是必需的
DEPARTMENT_ASSIGNMENT	把解析出来的上游值当作权威部门外部 ID	TargetAttributeName=system.department_assignment、SourceAttributeName	只用于部门归属，同一用户池的所有连接中最多允许一个这类映射

目标属性名

TargetAttributeName 决定写到哪里。

支持的目标命名空间

目标形式	含义
user.<claim>	写入 identity 标准用户属性，背后对应 OIDC 标准声明
custom.<name>	写入目标 UserPool 中已存在的自定义属性
system.department_assignment	预留系统目标，用于权威部门归属

目标名自动归一化

控制面会对简写目标名做归一化：

您填写的输入	实际归一化后目标
email	user.email
given_name	user.given_name
department	custom.department
employee_code	custom.employee_code

这意味着：

如果裸写的目标名恰好是合法的 OIDC 标准声明，identity 会把它当成 user.<claim>

否则，identity 会把它当成 custom.<name>

合法的 user.* 标准目标

运行时会根据本页列出的 OIDC 标准声明校验 user.* 目标。

支持的声明	目标形式
sub	user.sub
preferred_username	user.preferred_username
email	user.email
name	user.name
email_verified	user.email_verified
phone_number	user.phone_number
phone_number_verified	user.phone_number_verified
given_name	user.given_name
family_name	user.family_name
middle_name	user.middle_name
nickname	user.nickname
profile	user.profile
picture	user.picture
website	user.website
gender	user.gender
birthdate	user.birthdate
zoneinfo	user.zoneinfo
locale	user.locale

合法的自定义目标

custom.<name> 目标必须同时满足：

该自定义属性定义已经存在于目标 UserPool

目标名不能为空

该自定义属性的 Schema 可变性必须是 Mutable

如果自定义属性存在，但其可变性是 AdminMutable 或 Immutable，identity 会拒绝把它作为属性映射目标。

预留部门目标

system.department_assignment 只能用于 DEPARTMENT_ASSIGNMENT。

规则包括：

只能与 MappingType=DEPARTMENT_ASSIGNMENT 一起使用

必须提供 SourceAttributeName

不支持 AdditionalConfig

同一个用户池的所有连接里最多只能有一条这类映射

源属性路径

SourceAttributeName 表示 identity 从上游载荷哪里读取值。

常见路径模式：

模式	示例	含义
直接字段	email	读取顶层 email 字段
嵌套字段	profile.department.name	通过对象路径读取嵌套字段
数组元素	emails[0].value	读取数组里的某个元素
claims 包装路径	claims.email	从把声明包在 claims 下的载荷里读取

运维注意点：

运行时按 gjson 风格解析路径

emails[0].value 这类旧式数组下标写法也是支持的

如果源路径不存在，这条规则会被跳过，而不是让整批映射直接失败

HARDCODED_VALUE 的 AdditionalConfig

HARDCODED_VALUE 通过 AdditionalConfig 携带 JSON。

必需格式如下：

value 键是必需的。空值或非法 JSON 都会被控制面拒绝。

如何编写和修改映射

连接映射是通过对应连接家族的创建或更新 API 写入的。

第一步：先确定目标

先决定数据应该落到：

标准用户字段，例如 user.email

自定义属性，例如 custom.department

部门归属规则 system.department_assignment

第二步：如果要写自定义属性，先创建它

如果目标是自定义属性，请先在目标池里创建对应的自定义属性定义。

可结合自定义属性 Schema 确认字段存在且 Mutability=Mutable。

第三步：在连接创建或更新请求中写入 AttributeMappings

OIDC 创建请求片段示例：

OIDC 更新请求片段示例：

第四步：再读取连接确认

通过对应家族的 GetIdentityProvider* API 读取连接，确认返回结果里的 AttributeMappings 是否符合预期。

典型映射示例

把提供商字段 mail 映射到 identity email

如果提供商 A 返回的是 mail，但 identity 里要落到标准邮箱字段：

最终等效目标：user.email

把提供商字段 displayName 映射到 identity name

把提供商字段 employeeId 映射到自定义属性 employee_id

前提：目标池里已经存在可写的 employee_id 自定义属性。

硬编码一个固定来源标记

如果所有从 provider A 过来的用户都应该写入 custom.source_system=provider_a：

把嵌套字段 profile.department.name 映射到部门自定义字段

最终等效目标：custom.department

基于上游部门外部 ID 做部门归属

如果 provider A 返回了权威的部门外部 ID 或 ID 列表：

这类规则不会写普通用户字段或自定义字段，而是把解析结果当作部门外部 ID 来应用部门成员关系。

SAML 迁移提示

如果旧的 SAML 连接仍在使用遗留的 AttributeMapping 字符串字段，建议把新规则迁移到 AttributeMappings，这样所有连接家族就能统一使用同一种映射模型。

管理 API

目标	连接家族	相关 API
创建连接时写入映射	OIDC、OAuth、SAML、WeCom、Token Exchange	CreateIdentityProviderOIDC、CreateIdentityProviderOAuth、CreateIdentityProviderSAML、CreateIdentityProviderWeCom、CreateIdentityProviderTokenExchange
修改映射	OIDC、OAuth、SAML、WeCom、Token Exchange	UpdateIdentityProviderOIDC、UpdateIdentityProviderOAuth、UpdateIdentityProviderSAML、UpdateIdentityProviderWeCom、UpdateIdentityProviderTokenExchange
校验映射是否已保存	相同家族	GetIdentityProviderOIDC、GetIdentityProviderOAuth、GetIdentityProviderSAML、GetIdentityProviderWeCom、GetIdentityProviderTokenExchange

下一步

连接

OIDC 连接

OAuth 连接

SAML 连接

WeCom 连接

Token Exchange 连接

自定义属性 Schema

用户

智能体身份和权限管理平台