扩展 API 驱动的预配以同步自定义属性

项目
08/13/2024

默认情况下，API 驱动的预配应用支持处理属于标准 SCIM 核心用户和企业用户架构的属性。记录系统可能具有你可能希望将其包含在 API 驱动的预配中的自定义属性。本高级教程介绍如何扩展 API 驱动的预配应用以处理其他自定义属性。

注意

在尝试此高级方案之前，建议使用一个 API 客户端（Graph 浏览器、cURL）验证现成的预配应用配置是否按预期工作。

示例方案

你已配置 API 驱动的预配应用。你成功使用属于标准 SCIM 核心用户和企业用户架构的属性预配应用，并在 Microsoft Entra ID 中预配用户。现在，你希望将两个自定义属性 HireDate 和 JobCode 从 HR 系统发送到入站预配 API 终结点。你想将这两个自定义属性映射到 Microsoft Entra 属性 employeeHireDate 和 jobTitle。

步骤 1 - 扩展预配应用架构

在此步骤中，我们会将不属于标准 SCIM 架构的两个属性“HireDate”和“JobCode”添加到预配应用，并在预配数据流中使用它们。

至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“企业应用程序”。
打开 API 驱动型预配应用。
打开“预配”边栏选项卡。
单击“编辑预配”按钮。
展开“映射”部分，然后单击属性映射链接。
向下滚动“属性映射”页面。选择“显示高级选项”，然后单击“编辑 API 的属性列表”链接。
向下滚动到“编辑属性列表”页的末尾。
将以下两个属性作为 SCIM 架构扩展添加到列表中。可以使用自己的 SCIM 架构命名空间。
urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate
urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode
保存所做的更改

注意

如果只想将几个其他属性添加到预配应用，请使用 Microsoft Entra 管理中心来扩展架构。如果要添加更多自定义属性（假设超过 20 个属性），建议使用 UpdateSchema CSV2SCIM PowerShell 脚本的模式，以自动执行上述手动过程。

步骤 2 - 映射自定义属性

现在，让我们将这些扩展添加到预配应用属性映射。

单击“属性映射”页上的“添加新映射”链接。
将 urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate 属性映射到 employeeHireDate。单击“确定”。
接下来，为 title 选择现有映射，然后单击它以编辑映射。
编辑映射到表达式的属性，以将 urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode 纳入为 jobTitle Microsoft Entra 属性一部分。
```
  Join("", [title], "(", [urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode], ")")
```
使用此表达式映射，如果 title 为“Tour Lead”且 JobCode 为“TL-1001”，则 Microsoft Entra 属性 jobTitle 将设置为“Tour Lead (TL-1001)”。
保存属性映射。

步骤 3 - 上传具有自定义属性的批量请求

打开 API 客户端 (Graph 浏览器/ cURL)。
复制-粘贴具有自定义属性的批量请求。
将批量请求发送到预配 API 终结点 URL。
一段时间后，可以检查预配日志来验证属性更改。
还可以在 Microsoft Entra 用户配置文件中验证更改。 Employee hire date 的值反映租户时区。

附录

具有自定义属性的批量请求

批量请求包括上述步骤中配置的自定义属性。

请求正文

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "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:contoso:1.0:User"],
            "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,
            "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",
                  "displayName": "John Smith"
                 }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2021-05-01T00:00:00-05:00",
                "JobCode": "TG-1001"
            }            
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "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:contoso:1.0:User"],
            "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": "701984",
                "displayName": "Barbara Jensen"
             }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2022-07-15T00:00:00-05:00",
                "JobCode": "TL-1003"
            }            
        }
    }
],
    "failOnErrors": null
}

通过