从人力资源来源提供自定义安全属性（预览版）

2025-05-04

自定义安全属性预配使客户能够使用 Microsoft Entra 入站预配功能自动设置自定义安全属性。在此公共预览阶段，您可以从权威来源（例如 HR 系统）获取自定义安全属性的源值。自定义安全属性预配支持以下源：Workday、SAP SuccessFactors 和其他使用 API 驱动的预配的集成 HR 系统。预配的目标是你的 Microsoft Entra ID 租户。

自定义安全属性体系结构的关系图。

注释

我们根据适用于预览版的条款向客户提供公共预览版。这些术语在 Microsoft 产品关于联机服务的总体条款中进行了概述。普通服务级别协议（SLA）不适用于公共预览版，并且只有有限的客户支持可用。此外，此预览版不支持为企业 SaaS 应用或本地 Active Directory 功能预配自定义安全属性。

自定义安全属性

Microsoft Entra ID 中的自定义安全属性是特定于业务的属性（键值对），可以定义和分配给 Microsoft Entra 对象。这些属性可用于存储信息、对对象进行分类，或对特定 Azure 资源强制实施优化访问控制。若要了解有关自定义安全属性的详细信息，请参阅 Microsoft Entra ID 中的自定义安全属性是什么？。

先决条件

若要预配自定义安全属性，必须满足以下先决条件：

Microsoft Entra ID Premium P1 许可证，用于配置以下入站预配应用之一：
在属性映射过程中，激活的自定义安全属性在您的租户中用于进行发现。使用此预览功能之前，必须在 Microsoft Entra ID 租户中创建自定义安全属性集。
若要在入站预配应用的属性映射中配置自定义安全属性，请以分配应用程序管理员和属性预配管理员Microsoft Entra 角色的用户身份登录到 Microsoft Entra 管理中心：
- 创建和更新预配应用需要应用程序管理员。
- 需要属性预配管理员才能在预配应用的属性映射部分中添加或删除自定义安全属性。

已知的限制

预配服务仅支持设置类型为String的自定义安全属性。
不支持预配类型为 Integer 和 Boolean 的自定义安全属性。
不支持预配多值自定义安全属性。
不支持预配已停用的自定义安全属性。
使用 “属性日志读取者 ”角色，无法在预配日志中查看自定义安全属性值。

使用自定义安全属性配置预配应用

在开始之前，请按照以下步骤在 Microsoft Entra ID 租户中添加自定义安全属性，并在入站预配应用中映射自定义安全属性。

在 Microsoft Entra ID 租户中定义自定义安全属性

在 Microsoft Entra 管理中心中，访问从 Entra ID>自定义安全属性添加自定义安全属性的选项。至少需要具有 属性定义管理员 角色才能完成此任务。

此示例包含可添加到租户的自定义安全属性。使用属性集 HRConfidentialData ，然后将以下属性添加到：

EEOStatus
FLSAStatus
PayGrade
薪酬等级类型

映射入站预配应用中的自定义安全属性

以同时具有应用程序管理员和属性预配管理员角色权限的用户身份登录到 Microsoft Entra 管理中心。
转到 企业应用程序，然后打开入站预配应用。
打开 “预配 ”屏幕。

注释

本指南提供 API 驱动的预配过程的屏幕截图，适用于 Microsoft Entra ID。如果使用 Workday 或 SuccessFactors 预配应用，则会看到 Workday 和 SuccessFactors 相关属性和配置。
选择“编辑预配”。
选择 “属性映射 ”以打开属性映射屏幕。
定义要存储敏感数据的源属性，然后选中“ 显示高级选项 ”框以打开属性列表。
选择 “编辑 API 属性列表 ”以标识要测试的属性。
- 通过定义 SCIM 架构命名空间，使用入站预配 API 测试自定义安全属性预配： urn:ietf:params:scim:schemas:extension:microsoft:entra:csa 请务必包含以下属性：
  - urn:ietf:params:scim:schemas:extension:microsoft:entra:csa:EEOStatus
  - urn:ietf:params:scim:schemas:extension:microsoft:entra:csa:FLSAStatus
  - urn:ietf:params:scim:schemas:extension:microsoft:entra:csa:PayGrade
  - urn:ietf:params:scim:schemas:extension:microsoft:entra:csa:PayScaleType
注释

可以定义自己的 SCIM 架构命名空间来表示 SCIM 有效负载中的敏感人力资源数据。请确保它以 urn:ietf:params:scim:schemas:extension 开头。
- 如果使用 Workday 或 SuccessFactors 作为 HR 源，请使用 API 表达式更新属性列表以检索要存储的 HR 数据，该列表位于自定义安全属性列表中。
- 如果要从 SuccessFactors 检索同一组 HR 数据，请使用以下 API 表达式：
  - $.employmentNav.results[0].jobInfoNav.results[0].eeoClass
  - $.employmentNav.results[0].jobInfoNav.results[0].flsaStatus
  - $.employmentNav.results[0].jobInfoNav.results[0].payGradeNav.name
  - $.employmentNav.results[0].jobInfoNav.results[0].payScaleType
保存架构更改。
在 “属性映射 ”屏幕中，选择“ 添加新映射”。
- 自定义安全属性以格式 CustomSecurityAttributes.<AttributeSetName>_<AttributeName>显示。

添加以下映射，然后保存更改：

API 源属性	Microsoft Entra ID 目标属性
urn：ietf：params：scim：schemas：extension：microsoft：entra：csa：EEOStatus	CustomSecurityAttributes.HRConfidentialData_EEOStatus
urn：ietf：params：scim：schemas：extension：microsoft：entra：csa：FLSAStatus	CustomSecurityAttributes.HRConfidentialData_FLSAStatus
urn：ietf：params：scim：schemas：extension：microsoft：entra：csa：PayGrade	自定义安全属性.人力资源机密数据_工资级别
urn：ietf：params：scim：schemas：extension：microsoft：entra：csa：PayScaleType	CustomSecurityAttributes.HRConfidentialData_薪资级别类型

测试自定义安全属性预配

将 HR 源属性映射到自定义安全属性后，使用以下方法来测试自定义安全属性数据的流。选择的方法取决于预配应用类型。

如果作业使用 Workday 或 SuccessFactors 作为其源，请使用按需预配功能测试自定义安全属性数据流。
如果作业使用 API 驱动的预配，则将 SCIM 批量有效负载发送到作业的 bulkUpload API 终结点。

使用 SuccessFactors 预配应用进行测试

在此示例中，SAP SuccessFactors 属性映射到自定义安全属性，如下所示：

SAP 属性映射选项的屏幕截图。

打开 SuccessFactors 预配作业，然后选择 “按需预配”。

Microsoft Entra ID 概述的屏幕截图，其中选择了“按需预配”。

在 “选择用户 ”框中，输入要测试的用户的 personIdExternal 属性。

预配日志显示设置的自定义安全属性。

注释

自定义安全属性的源值和目标值在预配日志中被隐藏。
在用户Microsoft Entra ID 配置文件的 “自定义安全属性 ”屏幕中，可以查看为该用户设置的实际值。至少需要属性分配管理员或属性分配读取者角色才能查看此数据。

使用 API 驱动的预配应用进行测试

创建包含自定义安全属性值的 SCIM 批量请求有效负载。
- 若要访问完整的 SCIM 有效负载，请参阅示例 SCIM 有效负载。
从预配作业概述页复制 bulkUpload API URL。
使用 Graph 资源管理器或 cURL，然后将 SCIM 有效负载发布到 bulkUpload API 终结点。
- 如果 SCIM 有效负载格式中没有错误，则会收到 “接受 ”状态。
- 等待几分钟，然后检查 API 驱动的预配作业的预配日志。
自定义安全属性如以下示例所示。

注释

自定义安全属性的源值和目标值会在预配日志中被删减。若要查看为用户设置的实际值，请转到用户的Microsoft Entra ID 配置文件。
可以在 “自定义安全属性 ”屏幕中查看数据。至少需要属性分配管理员或属性分配读取者角色才能查看此数据。

具有自定义安全属性的示例 SCIM 有效载荷

此示例 SCIM 批量请求包括扩展下的 urn:ietf:params:scim:schemas:extension:microsoft:entra:csa 自定义字段，这些字段可以映射到自定义安全属性。

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [{
            "method": "POST",
            "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",
            "path": "/Users",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:microsoft:entra:csa"],
                "id": "2819c223-7f76-453a-919d-413861904646",
                "externalId": "701984",
                "userName": "bjensen@example.com",
                "name": {
                    "formatted": "Ms. Barbara J Jensen, III",
                    "familyName": "Jensen",
                    "givenName": "Barbara",
                    "middleName": "Jane",
                    "honorificPrefix": "Ms.",
                    "honorificSuffix": "III"
                },
                "displayName": "Babs Jensen",
                "nickName": "Babs",
                "emails": [{
                        "value": "bjensen@example.com",
                        "type": "work",
                        "primary": true
                    }
                ],
                "addresses": [{
                        "type": "work",
                        "streetAddress": "234300 Universal City Plaza",
                        "locality": "Hollywood",
                        "region": "CA",
                        "postalCode": "91608",
                        "country": "USA",
                        "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
                        "primary": true
                    }
                ],
                "phoneNumbers": [{
                        "value": "555-555-5555",
                        "type": "work"
                    }
                ],
                "userType": "Employee",
                "title": "Tour Guide",
                "preferredLanguage": "en-US",
                "locale": "en-US",
                "timezone": "America/Los_Angeles",
                "active": true,
                "password": "t1meMa$heen",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "employeeNumber": "701984",
                    "costCenter": "4130",
                    "organization": "Universal Studios",
                    "division": "Theme Park",
                    "department": "Tour Operations",
                    "manager": {
                        "value": "89607",
                        "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",
                        "displayName": "John Smith"
                    }
                },
                "urn:ietf:params:scim:schemas:extension:microsoft:entra:csa": {
                    "EEOStatus":"Semi-skilled",
                    "FLSAStatus":"Non-exempt",
                    "PayGrade":"IC-Level5",
                    "PayScaleType":"Revenue-based"
                }
            }
        }, {
            "method": "POST",
            "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",
            "path": "/Users",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:microsoft:entra:csa" ],
                "id": "2819c223-7f76-453a-919d-413861904646",
                "externalId": "701985",
                "userName": "Kjensen@example.com",
                "name": {
                    "formatted": "Ms. Kathy J Jensen, III",
                    "familyName": "Jensen",
                    "givenName": "Kathy",
                    "middleName": "Jane",
                    "honorificPrefix": "Ms.",
                    "honorificSuffix": "III"
                },
                "displayName": "Kathy Jensen",
                "nickName": "Kathy",
                "emails": [{
                        "value": "kjensen@example.com",
                        "type": "work",
                        "primary": true
                    }
                ],
                "addresses": [{
                        "type": "work",
                        "streetAddress": "100 Oracle City Plaza",
                        "locality": "Hollywood",
                        "region": "CA",
                        "postalCode": "91618",
                        "country": "USA",
                        "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
                        "primary": true
                    }
                ],
                "phoneNumbers": [{
                        "value": "555-555-5545",
                        "type": "work"
                    }
                ],
                "userType": "Employee",
                "title": "Tour Lead",
                "preferredLanguage": "en-US",
                "locale": "en-US",
                "timezone": "America/Los_Angeles",
                "active": true,
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "employeeNumber": "701984",
                    "costCenter": "4130",
                    "organization": "Universal Studios",
                    "division": "Theme Park",
                    "department": "Tour Operations",
                    "manager": {
                        "value": "89607",
                        "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",
                        "displayName": "John Smith"
                    }
                },
                "urn:ietf:params:scim:schemas:extension:microsoft:entra:csa": {
                    "EEOStatus":"Skilled",
                    "FLSAStatus":"Exempt",
                    "PayGrade":"Manager-Level2",
                    "PayScaleType":"Profit-based"
                }
                
            }
        }
    ],
    "failOnErrors": null
}

为混合用户预配自定义安全属性

混合用户首先从本地 Active Directory 中的 HR 系统预配，然后使用 Entra Connect 同步或云同步同步到 Microsoft Entra ID。可以将自定义安全属性分配给混合用户，并且这些属性仅存在于混合用户的Microsoft Entra ID 配置文件中。

本部分介绍预配拓扑，用于为混合用户自动预配自定义安全属性。它使用 Workday 作为受信任的 HR 源。但是，同一拓扑还可用于 SuccessFactors 和 API 驱动的预配。

假设 Workday 是您的身份信息的记录系统的人力资源系统。若要在来自 Workday 的混合用户上设置自定义安全属性，请配置两个预配应用：

Workday 到本地 Active Directory 预配： 此预配应用在本地 Active Directory 中创建和更新混合用户。它仅处理 Workday 中的正常属性。
Workday 到 Microsoft Entra ID 配置： 将此配置应用配置为仅处理更新操作，并将属性映射限制为仅包含自定义安全属性作为目标属性。

使用此拓扑，下面是端到端流的工作原理：

自定义安全属性映射如何适用于混合用户的流程图。

Workday -to-AD 预配应用从 Workday 导入核心用户配置文件。
应用使用员工 ID 作为匹配标识符在本地 Active Directory 中创建/更新用户帐户。
Microsoft Entra Connect Sync/Cloud Sync 会将用户配置文件同步到 Microsoft Entra ID。
如果您已配置 Workday 写回，电子邮件或电话号码信息将被写回到 Workday。
Workday 到 Microsoft Entra ID 预配应用被配置为仅处理更新，并将机密属性设置为自定义安全属性。使用“显示高级选项”下的架构编辑器删除默认属性映射，例如accountEnabledisSoftDeleted，在此方案中不相关。

混合用户的属性映射的屏幕截图。

此配置将自定义安全属性分配给同步到本地 Active Directory 中的 Microsoft Entra ID 的混合用户。

注释

上述配置依赖于三个不同的同步周期以特定顺序完成。如果混合用户配置文件在 Microsoft Entra ID 中不可用，那么当 Workday 到 Microsoft Entra ID 预配 作业运行时，更新操作会失败，并将在下次执行时重试。如果使用 API 驱动的预配到Microsoft Entra ID 应用，则可以更好地控制自定义安全属性更新的执行时间。

自定义安全属性预配的 API 权限

此预览功能引入了以下新的图形 API 权限。此功能使你能够直接或代表登录用户访问和修改包含自定义安全属性映射的预配应用架构。

CustomSecAttributeProvisioning.ReadWrite.All：此权限授予调用应用读取和写入包含自定义安全属性的属性映射的能力。若要编辑包含自定义安全属性映射的配置应用，需要具有 Application.ReadWrite.OwnedBy、Synchronization.ReadWrite.All 或 Application.ReadWrite.All（从最低权限到最高权限）的此权限。此权限使你能够获取包含自定义安全属性的完整架构，以及使用自定义安全属性更新或重置架构。
CustomSecAttributeProvisioning.Read.All：此权限授予调用应用读取属性映射和包含自定义安全属性的预配日志的能力。要查看受保护资源中的自定义安全属性名称和值，必须具有Synchronization.Read.All或Application.Read.All（从最低权限到最高权限）的权限。

如果应用没有 CustomSecAttributeProvisioning.ReadWrite.All 权限或 CustomSecAttributeProvisioning.Read.All 权限，则无法访问或修改包含自定义安全属性的预配应用。而是会显示错误消息或经过修订的数据。

排查自定义安全属性预配问题

問题	对步骤进行故障排除
自定义安全属性不会显示在 “目标属性映射”下拉列表中。	- 确保向支持自定义安全属性的预配应用添加自定义安全属性。 - 确保已登录用户分配角色属性预配管理员（用于编辑访问权限）或属性预配读取者（用于查看访问权限）。
重置或更新预配应用架构时返回的错误。 `HTTP 403 Forbidden - InsufficientAccountPermission Provisioning schema has custom security attributes. The account does not have sufficient permissions to perform this operation.`	确保已登录用户被指定为角色属性预配管理员。
无法删除属性映射中存在的自定义安全属性。	确保已登录的用户已分配角色属性预配管理员。
属性映射表包含字符串 `redacted` 出现在源属性和目标属性下的行。	如果登录的用户没有属性预配管理员或属性预配读取者角色，则此行为是设计造成的。分配其中一个角色将显示自定义安全属性映射。
返回 `The provisioning service does not support setting custom security attributes of type boolean and integer. Unable to set CSA attribute`的错误。	从预配应用属性映射中删除整数/布尔自定义安全属性。
返回 `The provisioning service does not support setting custom security attributes that are deactivated. Unable to set CSA attribute <attribute name>`的错误。	尝试更新已停用的自定义安全属性。从预配应用属性映射中删除已停用的自定义安全属性。

后续步骤

自定义属性映射

通过