使用 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 脚本以从任何记录系统读取数据。 下面是企业集成方案变体的列表，其中可以使用 PowerShell 脚本实现 API 驱动的入站预配。

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

如何使用本教程

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

下载 PowerShell 脚本

1. 访问 GitHub 存储库 entra-id-inbound-provisioning。
2. 使用 “代码>克隆 ”或“ 代码>下载 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. 在记事本++ 或 Excel 中打开 CSV 文件 Samples/csv-with-2-records.csv ，检查文件中存在的列。

2. 在记事本++ 或源代码编辑器（如 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文件有一个无效的SCIM属性，名为userId，那么ValidateAttributeMapping模式会显示以下错误。

   

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

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

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

9. 可以使用 cURL 将上面生成的文件发布到与预配应用关联的 /bulkUpload API 终结点 as-is。 参考：

   • cURL 快速入门

10. 若要使用同一 PowerShell 脚本将生成的有效负载直接上传到 API 终结点，请参阅下一部分。

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

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 -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -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 驱动的预配应用。 ServicePrincipalId复制与您的预配应用相关联的“预配应用>属性>对象 ID”。

   

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.partner.onmschina.cn" -ServicePrincipalId "<ProvisioningAppObjectId>" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint)
   

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

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

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

1. 在记事本++ 或源代码编辑器（如 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 架构命名空间下。

扩展预配作业架构

HR 团队发送的数据文件通常包含更多属性，这些属性在标准 SCIM 架构中没有直接表示形式。 若要表示此类属性，建议创建 SCIM 扩展架构并在此命名空间下添加属性。

CSV2SCIM脚本提供了一种执行模式，该模式调用 UpdateSchema 该模式可读取 CSV 文件中的所有列，在扩展架构命名空间下添加这些列，并更新预配应用架构。

为了说明该过程，我们将使用Samples/csv-with-2-records.csv文件夹中存在的 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.partner.onmschina.cn" -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.partner.onmschina.cn" -GetPreviousCycleLogs -NumberOfCycles 1
   

   

   注释

   NumberOfCycles 默认为 1。 指定用于检索更多同步周期的数字。

2. 若要查看主机上的同步统计信息并将日志详细信息保存到变量，请运行以下命令：

   $logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.partner.onmschina.cn" -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.partner.onmschina.cn" -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 Core 用户和企业用户属性架构元素。 该文件还会生成 CSV 文件内容的相应表示，作为批量请求的有效负载。

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

    @{
    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 驱动的入站预配的常见问题