使用 PowerShell 指令碼的 API 驅動輸入佈建
本文內容
整合案例
如何使用本教學課程
下載 PowerShell 指令碼
使用標準結構描述產生大量要求承載
設定服務主體驗證的客戶端憑證
使用客戶端憑證驗證上傳大量要求承載
產生有自訂 SCIM 結構描述的大量要求
擴充佈建工作描述
取得最新同步週期的佈建記錄
附錄
下一步
顯示其他 7 個
本教學課程說明如何使用 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 指令碼來實作。
展開資料表
#
記錄系統
使用 PowerShell 讀取來源資料的整合指導
1
資料庫資料表
如果您使用 Azure SQL 資料庫或內部部署 SQL Server,您可以使用 Read-SqlTableData cmdlet 來讀取儲存在 SQL Database 資料表中的資料。 您可以使用 Invoke-SqlCmd cmdlet 來執行 Transact-SQL 或 XQuery 指令碼。 如果您使用 Oracle / MySQL / Postgres 資料庫,則可以找到由廠商發行或在 PowerShell 資源庫 中提供的 PowerShell 模組。 使用模組從資料庫資料表讀取資料。
2
LDAP 伺服器
使用 PowerShell 資源庫 中可用的 System.DirectoryServices.Protocols
.NET API 或其中一個 LDAP 模組,查詢您的 LDAP 伺服器。 了解 LDAP 結構描述和階層,以從 LDAP 伺服器擷取使用者資料。
3
公開 REST API 的任何系統
若要使用 PowerShell 從 REST API 端點讀取資料,您可以使用 Microsoft.PowerShell.Utility
模組中的 Invoke-RestMethod cmdlet。 查看 REST API 的文件,並找出預期的參數和標頭、傳回的格式,以及它所使用的驗證方法。 然後,您可以據以調整 Invoke-RestMethod
命令。
4
公開 SOAP API 的任何系統
若要使用 PowerShell 從 SOAP API 端點讀取資料,您可以使用 Microsoft.PowerShell.Management
模組中的 New-WebServiceProxy cmdlet。 查看 SOAP API 的文件,並找出預期的參數和標頭、傳回的格式,以及它所使用的驗證方法。 然後,您可以據以調整 New-WebServiceProxy
命令。
讀取來源資料之後,套用前置處理規則,並將記錄系統的輸出轉換成大量要求,以傳送至 Microsoft Entra 佈建 bulkUpload API 端點。
Microsoft Entra 輸入佈建 GitHub 存放庫 中發佈的 PowerShell 範例指令碼,自動執行多項工作。 其邏輯可用來處理大型 CSV 檔案,並將大量要求區塊化,以在每個要求中傳送 50 筆記錄。 以下說明如何測試它,並根據您的整合需求進行自訂。
注意
會以「現況」方式提供範例 PowerShell 指令碼,以供實作參考使用。 如果您有與指令碼有關的問題,或想要增強指令碼,請使用 GitHub 專案存放庫 。
展開資料表
存取 GitHub 存放庫 entra-id-inbound-provisioning
。
使用 [程式碼] ->[複製] 或 [程式碼] ->[下載 ZIP] 選項,將此存放庫的內容複製到本機資料夾。
瀏覽至資料夾 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 (包含 2 筆記錄的 CSV 檔案範例)
csv-with-1000-records.csv (包含 1000 筆記錄的 CSV 檔案範例)
Test-ScriptCommands.ps1 (範例使用方式命令)
UseClientCertificate.ps1 (用來產生自我簽署憑證的指令碼,並將其上傳為服務主體認證以用於 OAuth 流程)
Sample1
(資料夾包含 CSV 檔案資料行如何對應至 SCIM 標準屬性的更多範例。如果您為員工、承包商、實習生取得不同的 CSV 檔案,您可以為每個實體建立個別的 AttributeMapping.psd1 檔案。)
下載並安裝最新版的 PowerShell。
執行命令以啟用執行遠端簽署指令碼:set-executionpolicy remotesigned
安裝下列必要條件模組:Install-Module -Name Microsoft.Graph.Applications,Microsoft.Graph.Reports
本節說明如何從 CSV 檔案產生具有標準 SCIM 核心使用者和企業使用者屬性的大量要求承載。
為了說明程序,讓我們使用 CSV 檔案 Samples/csv-with-2-records.csv
。
在 Notepad++ 或 Excel 中開啟 CSV 檔案 Samples/csv-with-2-records.csv
,以檢查檔案裡的資料行。
在 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'
}
}
}
開啟 PowerShell 並變更為目錄 CSV2SCIM\src 。
執行下列命令來初始化 AttributeMapping
變數。
$AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
執行下列命令來驗證 AttributeMapping
檔案是否具有有效的 SCIM 結構描述屬性。 如果驗證成功,此命令會傳回 True 。
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
假設 AttributeMapping
檔案具有名為 userId 的無效 SCIM 屬性,則 ValidateAttributeMapping
模式會顯示下列錯誤。
驗證 AttributeMapping
檔案是否有效之後,請執行下列命令,以在有包含 CSV 檔案中兩筆記錄的檔案 BulkRequestPayload.json
中產生大量要求。
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json
您可以開啟檔案 BulkRequestPayload.json
的內容,以確認是否根據檔案 AttributeMapping.psd1
中所定義的對應設定 SCIM 屬性。
您可以使用 Graph 總管或 cURL,將上述產生的檔案張貼至 與布建應用程式相關聯的 /bulkUpload API 端點。 參考:
若要使用相同的 PowerShell 指令碼直接將產生的承載上傳至 API 端點,請參閱下一節。
注意
此處的指示示範如何產生自我簽署憑證。 自我簽署憑證會預設為不受信任,而且難以維護。 此外,這些憑證可能會使用過期而安全性不足的雜湊和加密套件。 為獲得更好的安全性,請購買由知名憑證授權單位單位簽署的憑證。
執行下列 PowerShell 指令碼來產生新的自我簽署憑證。 如果您已購買由知名憑證授權機構單位簽署的憑證,則可以略過此步驟。
$ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My
$ThumbPrint = $ClientCertificate.ThumbPrint
產生的憑證會儲存 Current User\Personal\Certificates 。 您可以使用 [控制面板] ->[管理使用者憑證] 選項來檢視它。
若要將此憑證與有效的服務主體產生關聯,請以應用程式管理員身分登入您的 Microsoft Entra 系統管理中心。
開啟您在 [應用程式註冊] 底下 設定的服務主體 。
從 [概觀] 刀鋒視窗複製 [物件識別碼] 。 使用值來取代字串 <AppObjectId>
。 複製 應用程式 (用戶端) 識別碼 。我們稍後會使用它,並參考為 <AppClientId>
。
執行下列命令,將您的憑證上傳至已註冊的服務主體。
Connect-MgGraph -Scopes "Application.ReadWrite.All"
Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{
Type = "AsymmetricX509Cert"
Usage = "Verify"
Key = $ClientCertificate.RawData
}
您應該會在已註冊應用程式的 [憑證與密碼] 刀鋒視窗底下看到憑證。
將下列兩個 應用程式 權限範圍新增至服務主體應用程式:Application.Read.All 和 Synchronization.Read.All 。 PowerShell 指令碼需要這些權限範圍,才能透過 ServicePrincipalId
查閱佈建應用程式,並擷取佈建 JobId
。
本節說明如何使用受信任的用戶端憑證,將產生的大量要求承載傳送至您的輸入佈建 API 端點。
開啟您 設定 的 API 驅動佈建應用程式。 從 [佈建應用程式] >[屬性] >[物件識別碼] ,複製與佈建應用程式相關聯的 ServicePrincipalId
。
為 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)
請前往您的佈建應用程式的 [佈建記錄] 刀鋒視窗,以確認處理上述要求。
本節說明如何使用由 CSV 檔案中的欄位組成的自訂 SCIM 結構描述命名空間產生大量請求。
在 Notepad++ 或 Visual Studio Code 之類的原始程式碼編輯器中,開啟 PowerShell 資料檔案 Samples/AttributeMapping.psd1
,讓 CSV 檔案資料行對應至 SCIM 標準結構描述屬性。 現成隨附的檔案已預先設定 CSV 檔案資料行對應至對應的 SCIM 結構描述屬性。
開啟 PowerShell 並變更為目錄 CSV2SCIM\src 。
執行下列命令來初始化 AttributeMapping
變數。
$AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
執行下列命令來驗證 AttributeMapping
檔案是否具有有效的 SCIM 結構描述屬性。 如果驗證成功,此命令會傳回 True 。
.\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
除了 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 檔案中的所有資料行、在延伸結構描述命名空間下新增它們,以及更新佈建應用程式結構描述。
注意
如果佈建應用程式結構描述中已經有屬性延伸模組,則此模式只會發出屬性延伸已經存在的警告。 因此,如果新的欄位新增至 CSV 檔案,而且您想要將其新增為延伸模組,則在 UpdateSchema 模式中執行 CSV2SCIM 指令碼沒有問題。
為了說明程序,我們將使用存在於 CSV2SCIM 資料夾中的 CSV 檔案 Samples/csv-with-2-records.csv
。
在 Notepad、Excel 或 TextPad 中開啟 CSV 檔案 Samples/csv-with-2-records.csv
,以檢查檔案裡的資料行。
執行以下命令:
.\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"
您可以開啟 [屬性對應] 頁面,並存取 [進階]選項 底下的 [編輯 API 屬性清單] 選項,以驗證是否更新佈建應用程式結構描述。
屬性清單 會顯示新命名空間下的屬性。
傳送大量要求之後,您可以查詢 Microsoft Entra ID 所處理的最新同步處理週期記錄。 您可以使用 PowerShell 指令碼擷取同步統計資料和處理詳細資料,並加以儲存以供分析。
若要檢視主控台上的記錄詳細資料和同步統計資料,請執行下列命令:
.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1
注意
NumberOfCycles 預設為 1。 指定一個數字,以擷取更多同步週期。
若要檢視主控台上的同步統計資料,並將記錄詳細資料儲存至變數,請執行下列命令:
$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
和 ValidateAttributeMapping
命令行參數是指 CSV 資料行屬性與標準 SCIM 結構描述元素的對應。
它不會參考您在來源 SCIM 結構描述元素與目標 Microsoft Entra / 內部部署 Active Directory 屬性之間 Microsoft Entra 系統管理中心佈建應用程式所執行的屬性對應。
展開資料表
參數
描述
處理備註
路徑
CSV 檔案的完整或相對路徑。 例如:.\Samples\csv-with-1000-records.csv
強制:是
ScimSchemaNamespace
自訂 SCIM 結構描述命名空間,用來將 CSV 檔案中的所有資料行傳送為屬於特定命名空間的自訂 SCIM 屬性。 例如,urn:ietf:params:scim:schemas:extension:csv:1.0:User
強制:只有在您想要: - 更新佈建應用程式結構描述或 當您想要在承載中包含自訂 SCIM 屬性時。
AttributeMapping
指向將 CSV 檔案中的資料行對應至 SCIM Core 使用者和企業使用者屬性的 PowerShell 資料 (.psd1 副檔名) 檔案。 請參閱範例:CSV2SCIM 指令碼的 AttributeMapping.psd 檔案 。 例如: powershell $AttributeMapping = Import-PowerShellDataFile '.\Samples\AttributeMapping.psd1'`-AttributeMapping $AttributeMapping
強制:是 使用 UpdateSchema
切換時是唯一不需要指定此情況的案例。
ValidateAttributeMapping
使用此 Switch 旗標來驗證 AttributeMapping 檔案是否包含符合 SCIM Core 和企業使用者結構描述的屬性。
強制:不 建議使用它來確保合規性。
ServicePrincipalId
您可以從 [佈建應用程式] >[屬性] >[物件識別碼] 擷取佈建應用程式服務主體識別碼的 GUID 值
強制:只有在您想要: - 更新佈建應用程式結構描述,或 - 將產生的大量要求傳送至 API 端點。
UpdateSchema
使用此切換可指示指令碼讀取 CSV 資料行,並將其新增為佈建應用程式結構描述中的自訂 SCIM 屬性。
ClientId
要用於 OAuth 驗證流程的 Microsoft Entra 註冊應用程式用戶端識別碼。 此應用程式必須具備有效的憑證認證。
強制:唯有在執行憑證式驗證時。
ClientCertificate
在 OAuth 流程期間使用的用戶端驗證憑證。
強制:唯有在執行憑證式驗證時。
GetPreviousCycleLogs
取得最新同步週期的佈建記錄。
NumberOfCycles
若要指定應該擷取多少個同步週期。 這個值預設為 1。
RestartService
使用此選項時,指令碼會在上傳資料之前暫時暫停佈建作業,它會上傳資料,然後再次啟動工作,以確保立即處理承載。
僅在測試期間使用此選項。
此檔案可用來將 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'
}
}
}