使用 PowerShell 脚本进行 API 驱动的入站预配

本教程介绍如何使用 PowerShell 脚本实现 Microsoft Entra ID API 驱动的入站预配。 按照本教程中的步骤，可以将包含 HR 数据的 CSV 文件转换为批量请求有效负载，并将其发送到 Microsoft Entra 预配 /bulkUpload API 终结点。 本文还提供了有关如何将同一集成模式用于任何记录系统的指南。

集成方案

业务要求

你的记录系统定期生成包含辅助角色数据的 CSV 文件导出。 你希望实现一种集成，以便从 CSV 文件读取数据，并自动预配目标目录（对于混合用户为本地 Active Directory，对于仅云用户为 Microsoft Entra ID）中的用户账户。

实现要求

从实现的角度来看：

• 你想要使用无人参与的 PowerShell 脚本从 CSV 文件导出读取数据，并将其发送到入站预配 API 终结点。
• 在 PowerShell 脚本中，你不希望实现在记录系统和目标目录之间比较标识数据的复杂逻辑。
• 你想要使用 Microsoft Entra 预配服务来应用 IT 托管的预配规则，以在目标目录（本地 Active Directory 或 Microsoft Entra ID）中自动创建/更新/启用/禁用帐户。

集成方案变体

虽然本教程使用 CSV 文件作为记录系统，但你可以自定义示例 PowerShell 脚本，以从任何记录系统读取数据。 下面是企业集成方案变体的列表，其中 API 驱动的入站预配可以使用 PowerShell 脚本实现。

读取源数据后，应用预处理规则，并将记录系统中的输出转换为批量请求，该请求可发送到 Microsoft Entra 预配 bulkUpload API 终结点。

如何使用本教程

Microsoft Entra 入站预配 GitHub 存储库中发布的 PowerShell 示例脚本可自动执行多个任务。 它具有逻辑用来处理大型 CSV 文件并将批量请求分块，便于在每个请求中发送 50 条记录。 下面介绍如何根据集成要求对其进行测试和自定义。

下载 PowerShell 脚本

1. 访问 GitHub 存储库 entra-id-inbound-provisioning。
2. 使用代码 ->Clone 或 代码 ->Download ZIP 选项将此存储库的内容复制到本地文件夹中。
3. 导航到 PowerShell/CSV2SCIM 文件夹。 它具有以下目录结构：
   • src
     • CSV2SCIM.ps1 (主要脚本)
     • ScimSchemaRepresentations（包含用于验证 AttributeMapping.psd1 文件的标准 SCIM 架构定义的文件夹）
       • EnterpriseUser.json、Group.json、Schema.json、User.json
   • 示例
     • AttributeMapping.psd1（CSV 文件中的列到标准 SCIM 属性的映射示例）
     • csv-with-2-records.csv（带有两条记录的 CSV 文件示例）
     • csv-with-1000-records.csv（包含 1000 条记录的 CSV 文件示例）
     • Test-ScriptCommands.ps1（示例用法命令）
     • UseClientCertificate.ps1（用于生成自签名证书并将其作为服务主体凭据上传以在 OAuth 流中使用的脚本）
     • Sample1（文件夹中具有更多关于如何将 CSV 文件列映射到 SCIM 标准属性的示例。如果为员工、分包商和实习生获得不同 CSV 文件，则可以为每个实体创建单独的 AttributeMapping.psd1 文件。）
4. 下载并安装最新版本的 PowerShell。
5. 运行命令以启用远程签名脚本的执行：

   set-executionpolicy remotesigned
   

6. 安装以下必备模块：

   Install-Module -Name Microsoft.Graph.Applications,Microsoft.Graph.Reports
   

使用标准架构生成批量请求负载

本节介绍如何从 CSV 文件中生成具有标准 SCIM 核心用户和企业用户属性的批量请求有效负载。 使用 CSV 文件 Samples/csv-with-2-records.csv 来说明此过程。

1. 在 Notepad++ 或 Excel 中打开 CSV 文件 Samples/csv-with-2-records.csv 以检查文件中的列。

2. 在 Notepad++ 或 Visual Studio Code 等源代码编辑器中，打开 PowerShell 数据文件 Samples/AttributeMapping.psd1，该文件允许将 CSV 文件列映射到 SCIM 标准架构属性。 现成文件已经预先配置了 CSV 文件列到相应 SCIM 架构属性的映射。

       @{
       externalId   = 'WorkerID'
       name         = @{
           familyName = 'LastName'
           givenName  = 'FirstName'
       }
       active       = { $_.'WorkerStatus' -eq 'Active' }
       userName     = 'UserID'
       displayName  = 'FullName'
       nickName     = 'UserID'
       userType     = 'WorkerType'
       title        = 'JobTitle'
       addresses    = @(
           @{
               type          = { 'work' }
               streetAddress = 'StreetAddress'
               locality      = 'City'
               postalCode    = 'ZipCode'
               country       = 'CountryCode'
           }
       )
       phoneNumbers = @(
           @{
               type  = { 'work' }
               value = 'OfficePhone'
           }
       )
       "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
           employeeNumber = 'WorkerID'
           costCenter     = 'CostCenter'
           organization   = 'Company'
           division       = 'Division'
           department     = 'Department'
           manager        = @{
               value = 'ManagerID'
           }
       }
   }
   

3. 打开 PowerShell 并更改到目录 CSV2SCIM\src。

4. 运行以下命令来初始化 AttributeMapping 变量。

   $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
   

5. 运行以下命令以验证 AttributeMapping 文件是否具有有效 SCIM 架构属性。 如果验证成功，此命令将返回 True。

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
   

6. 假设 AttributeMapping 文件具有名为 userId 的无效 SCIM 属性，那么 ValidateAttributeMapping 模式将显示以下错误。

   

7. 验证 AttributeMapping 文件有效后，运行以下命令在文件 BulkRequestPayload.json 中生成批量请求，该请求包括 CSV 文件中的两条记录。

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json
   

8. 可以打开文件的内容 BulkRequestPayload.json，以验证是否根据文件 AttributeMapping.psd1 中定义的映射设置了 SCIM 属性。

9. 可以使用 Graph 浏览器或 cURL 将上面生成的文件原样发布到与预配应用关联的 /bulkUpload API 端点。 参考：

   • 使用 Graph 浏览器快速入门
   • 使用 cURL 快速入门

10. 要使用相同的 PowerShell 脚本将生成的有效负载直接上传到 API 端点，请参阅下一节。

以管理员用户身份生成并上传批量请求有效负载

本节介绍如何将生成的批量请求有效负载发送到入站预配 API 端点。

1. 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。

2. 导航到“预配应用”>“属性”>“对象 ID”，复制与预配应用关联的 ServicePrincipalId。

   

3. 作为具有全局管理员角色的用户，通过提供 ServicePrincipalId 和 TenantId 的正确值来运行以下命令。 如果此租户的已验证会话不存在，它将提示进行身份验证。 在身份验证期间对提示的权限提供同意。

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com"
   

4. 访问预配应用的预配日志边栏选项卡，以验证上述请求的处理情况。

为服务主体身份验证配置客户端证书

1. 运行以下 PowerShell 脚本以生成新自签名证书。 如果购买了由知名证书颁发机构签名的证书，则可以跳过此步骤。

   $ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My
   $ThumbPrint = $ClientCertificate.ThumbPrint
   

   生成的证书存储在 Current User\Personal\Certificates 中。 可以使用“控制面板 ->管理用户证书”选项查看它。
2. 若要将此证书与有效服务主体关联，请以“应用程序管理员”身份登录到 Microsoft Entra 管理中心。
3. 打开在“应用注册”下配置的服务主体。
4. 从“概览”边栏选项卡中复制对象 ID。 使用值替换字符串 <AppObjectId>。 复制应用程序（客户端）ID。稍后将使用它，它被引用为 <AppClientId>。
5. 运行以下命令将证书上传到注册的服务主体。

   Connect-MgGraph -Scopes "Application.ReadWrite.All"
   Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{
      Type = "AsymmetricX509Cert"
      Usage = "Verify"
      Key = $ClientCertificate.RawData
   }
   

   你应在已注册应用的“证书和机密”边栏选项卡下看到证书。
6. 将以下两个应用程序权限范围添加到服务主体应用：Application.Read.All 和 Synchronization.Read.All。 PowerShell 脚本通过 ServicePrincipalId 查找预配应用并获取预配 JobId 时需要这些功能。

使用客户端证书身份验证上传批量请求有效负载

本节介绍如何使用受信任的客户端证书将生成的批量请求有效负载发送到入站预配 API 端点。

1. 打开配置的 API 驱动预配应用。 从预配应用>属性>对象 ID 复制与预配应用关联的 ServicePrincipalId。

   

2. 通过提供 ServicePrincipalId、ClientId 和 TenantId 的正确值来运行以下命令。

   $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
   $ThumbPrint = $ClientCertificate.ThumbPrint
   
   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -TenantId "contoso.onmicrosoft.com" -ServicePrincipalId "<ProvisioningAppObjectId>" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint)
   

3. 访问预配应用的预配日志边栏选项卡，以验证上述请求的处理情况。

使用自定义 SCIM 架构生成批量请求

本节介绍如何使用由 CSV 文件中的字段组成的自定义 SCIM 架构命名空间生成批量请求。

1. 在 Notepad++ 或 Visual Studio Code 等源代码编辑器中，打开 PowerShell 数据文件 Samples/AttributeMapping.psd1，该文件允许将 CSV 文件列映射到 SCIM 标准架构属性。 现成文件已经预先配置了 CSV 文件列到相应 SCIM 架构属性的映射。

2. 打开 PowerShell 并更改到目录 CSV2SCIM\src。

3. 运行以下命令来初始化 AttributeMapping 变量。

   $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
   

4. 运行以下命令以验证 AttributeMapping 文件是否具有有效 SCIM 架构属性。 如果验证成功，此命令将返回 True。

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
   

5. 除了 SCIM 核心用户和企业用户属性外，要获得自定义 SCIM 架构命名空间 urn:ietf:params:scim:schemas:extension:contoso:1.0:User 下所有 CSV 字段的简单列表，请运行以下命令。

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"  > BulkRequestPayloadWithCustomNamespace.json
   

   CSV 字段将显示在自定义 SCIM 架构命名空间下。

扩展预配作业架构

人力资源团队发送的数据文件通常包含更多在标准 SCIM 模式中没有直接表示的属性。 为了表示这样的属性，建议创建 SCIM 扩展架构，并在此命名空间下添加属性。

CSV2SCIM 脚本提供了名为 UpdateSchema 的执行模式，它读取 CSV 文件中的所有列，将它们添加到扩展架构命名空间下，并更新预配应用模式。

为了说明过程，将使用 CSV2SCIM 文件夹中的 CSV 文件 Samples/csv-with-2-records.csv。

1. 在记事本、Excel 或 TextPad 中打开 CSV 文件 Samples/csv-with-2-records.csv，以检查文件中的列。

   

2. 运行以下命令：

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -UpdateSchema -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"
   

3. 通过打开“属性映射”页面并访问“高级选项”下的“编辑 API 属性列表”选项，可以验证对预配应用架构的更新。

4. “属性列表”显示新命名空间下的属性。

获取最新同步周期的预配日志

发送批量请求后，可以查询 Microsoft Entra ID 处理的最新同步周期的日志。 可以使用 PowerShell 脚本检索同步统计信息和处理详细信息，并将其保存以供分析。

1. 要在控制台上查看日志详细信息和同步统计信息，请运行以下命令：

   .\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1
   

   

   注意

   默认情况下，NumberOfCycles 为 1。 指定数字以检索更多同步周期。

2. 要在控制台上查看同步统计信息并将日志详细信息保存到变量中，请运行以下命令：

   $logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs
   

   要使用客户端证书身份验证运行命令，请通过提供 ServicePrincipalId、ClientId 和 TenantId 的正确值来运行命令：

   $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
   $ThumbPrint = $ClientCertificate.ThumbPrint
   
   $logs=.\CSV2SCIM.ps1 -ServicePrincipalId "<ProvisioningAppObjectId>" -TenantId "contoso.onmicrosoft.com" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint) -GetPreviousCycleLogs -NumberOfCycles 1
   

   • 要查看特定记录的详细信息，可以循环到集合中或选择其特定索引，例如：$logs[0]

     

   • 还可以使用 where-object 语句使用 sourceID 或 DisplayName 搜索特定记录。 在 ProvisioningLogs 属性中，可以找到为该特定记录所做操作的所有详细信息。

     $user = $logs | where sourceId -eq '1222'
     $user.ProvisioningLogs | fl
     

     

   • 可以在 ModifiedProperties 属性上看到受用户影响的特定属性。 $user.ProvisioningLogs.ModifiedProperties

     

附录

CSV2SCIM PowerShell 使用情况详细信息

以下是 CSV2SCIM PowerShell 脚本接受的命令行参数列表。

PS > CSV2SCIM.ps1 -Path <path-to-csv-file> 
[-ScimSchemaNamespace <customSCIMSchemaNamespace>] 
[-AttributeMapping $AttributeMapping] 
[-ServicePrincipalId <spn-guid>] 
[-ValidateAttributeMapping]
[-UpdateSchema]
[-ClientId <client-id>]
[-ClientCertificate <certificate-object>]
[-RestartService]

AttributeMapping.psd 文件

此文件用于将 CSV 文件中的列映射到标准 SCIM 核心用户和企业用户属性架构元素。 文件还生成 CSV 文件内容的适当表示，作为批量请求有效负载。

在下一个示例中，将 CSV 文件中的以下列映射到其对应的 SCIM 核心用户和企业用户属性。

    @{
    externalId   = 'WorkerID'
    name         = @{
        familyName = 'LastName'
        givenName  = 'FirstName'
    }
    active       = { $_.'WorkerStatus' -eq 'Active' }
    userName     = 'UserID'
    displayName  = 'FullName'
    nickName     = 'UserID'
    userType     = 'WorkerType'
    title        = 'JobTitle'
    addresses    = @(
        @{
            type          = { 'work' }
            streetAddress = 'StreetAddress'
            locality      = 'City'
            postalCode    = 'ZipCode'
            country       = 'CountryCode'
        }
    )
    phoneNumbers = @(
        @{
            type  = { 'work' }
            value = 'OfficePhone'
        }
    )
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
        employeeNumber = 'WorkerID'
        costCenter     = 'CostCenter'
        organization   = 'Company'
        division       = 'Division'
        department     = 'Department'
        manager        = @{
            value = 'ManagerID'
        }
    }
}

后续步骤

• 排查入站预配 API 的问题
• API 驱动的入站预配概念
• 有关 API 驱动的入站预配的常见问题