使用 PowerShell 或 Microsoft Graph API 設定跨租使用者同步處理
本文說明使用 Microsoft Graph PowerShell 或 Microsoft Graph API 設定跨租使用者同步處理的重要步驟。 設定時,Microsoft Entra ID 會自動在您的目標租使用者中布建和取消布建 B2B 使用者。 如需使用 Microsoft Entra 系統管理中心的詳細步驟,請參閱 設定跨租使用者同步處理。
必要條件
來源租使用者
- Microsoft Entra ID P1 或 P2 授權。 如需詳細資訊,請參閱授權需求。
- 安全性 管理員 istrator 角色,以設定跨租使用者存取設定。
- 混合式身分識別 管理員 istrator 角色,以設定跨租使用者同步處理。
- Cloud Application 管理員 istrator 或 Application 管理員 istrator 角色,將使用者指派給設定,以及刪除設定。
- 全域 管理員 istrator 角色,以同意所需的許可權。
目標租使用者
- Microsoft Entra ID P1 或 P2 授權。 如需詳細資訊,請參閱授權需求。
- 安全性 管理員 istrator 角色,以設定跨租使用者存取設定。
- 全域 管理員 istrator 角色,以同意所需的許可權。
步驟 1:登入目標租使用者
目標租使用者
啟動 PowerShell。
如有必要,請安裝 Microsoft Graph PowerShell SDK。
取得來源和目標租使用者的租用戶標識碼,並初始化變數。
$SourceTenantId = "<SourceTenantId>" $TargetTenantId = "<TargetTenantId>"
使用 連線-MgGraph 命令來登入目標租使用者,並同意下列必要許可權。
Policy.Read.All
Policy.ReadWrite.CrossTenantAccess
Connect-MgGraph -TenantId $TargetTenantId -Scopes "Policy.Read.All","Policy.ReadWrite.CrossTenantAccess"
步驟 2:在目標租用戶中啟用使用者同步處理
目標租使用者
在目標租使用者中,使用 New-MgPolicyCrossTenantAccessPolicyPartner 命令,在目標租使用者與來源租用戶之間的跨租使用者存取原則中建立新的合作夥伴設定。 在要求中使用來源租用戶標識碼。
如果您收到錯誤
New-MgPolicyCrossTenantAccessPolicyPartner_Create: Another object with the same value for property tenantId already exists
,您可能已經有現有的組態。 如需詳細資訊,請參閱 徵兆 - 新增MgPolicyCrossTenantAccessPolicyPartner_Create錯誤。$Params = @{ TenantId = $SourceTenantId } New-MgPolicyCrossTenantAccessPolicyPartner -BodyParameter $Params | Format-List
AutomaticUserConsentSettings : Microsoft.Graph.PowerShell.Models.MicrosoftGraphInboundOutboundPolicyConfiguration B2BCollaborationInbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting B2BCollaborationOutbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting B2BDirectConnectInbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting B2BDirectConnectOutbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting IdentitySynchronization : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantIdentitySyncPolicyPartner InboundTrust : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyInboundTrust IsServiceProvider : TenantId : <SourceTenantId> TenantRestrictions : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyTenantRestrictions AdditionalProperties : {[@odata.context, https://graph.microsoft.com/v1.0/$metadata#policies/crossTenantAccessPolicy/partners/$entity], [crossCloudMeetingConfiguration, System.Collections.Generic.Dictionary`2[System.String,System.Object]], [protectedContentSharing, System.Collections.Generic.Dictionary`2[System.String,System.Object]]}
使用 Invoke-MgGraphRequest 命令,在目標租用戶中啟用使用者同步處理。
如果您收到
Request_MultipleObjectsWithSameKeyValue
錯誤,您可能已經有現有的原則。 如需詳細資訊,請參閱 徵兆 - Request_MultipleObjectsWithSameKeyValue錯誤。$Params = @{ userSyncInbound = @{ isSyncAllowed = $true } } Invoke-MgGraphRequest -Method PUT -Uri "https://graph.microsoft.com/v1.0/policies/crossTenantAccessPolicy/partners/$SourceTenantId/identitySynchronization" -Body $Params
使用 Get-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization 命令來確認
IsSyncAllowed
是否已設定為 True。(Get-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization -CrossTenantAccessPolicyConfigurationPartnerTenantId $SourceTenantId).UserSyncInbound
IsSyncAllowed ------------- True
步驟 3:在目標租用戶中自動兌換邀請
目標租使用者
在目標租使用者中,使用 Update-MgPolicyCrossTenantAccessPolicyPartner 命令來自動兌換邀請,並隱藏輸入存取的同意提示。
$AutomaticUserConsentSettings = @{ "InboundAllowed"="True" } Update-MgPolicyCrossTenantAccessPolicyPartner -CrossTenantAccessPolicyConfigurationPartnerTenantId $SourceTenantId -AutomaticUserConsentSettings $AutomaticUserConsentSettings
步驟 4:登入來源租使用者
來源租使用者
啟動 PowerShell 的實例。
取得來源和目標租使用者的租用戶標識碼,並初始化變數。
$SourceTenantId = "<SourceTenantId>" $TargetTenantId = "<TargetTenantId>"
使用 連線-MgGraph 命令登入來源租使用者,並同意下列必要許可權。
Policy.Read.All
Policy.ReadWrite.CrossTenantAccess
Application.ReadWrite.All
Directory.ReadWrite.All
AuditLog.Read.All
Connect-MgGraph -TenantId $SourceTenantId -Scopes "Policy.Read.All","Policy.ReadWrite.CrossTenantAccess","Application.ReadWrite.All","Directory.ReadWrite.All","AuditLog.Read.All"
步驟 5:在來源租用戶中自動兌換邀請
來源租使用者
在來源租使用者中,使用 New-MgPolicyCrossTenantAccessPolicyPartner 命令,在來源租使用者與目標租用戶之間的跨租使用者存取原則中建立新的合作夥伴設定。 在要求中使用目標租用戶標識碼。
如果您收到錯誤
New-MgPolicyCrossTenantAccessPolicyPartner_Create: Another object with the same value for property tenantId already exists
,您可能已經有現有的組態。 如需詳細資訊,請參閱 徵兆 - 新增MgPolicyCrossTenantAccessPolicyPartner_Create錯誤。$Params = @{ TenantId = $TargetTenantId } New-MgPolicyCrossTenantAccessPolicyPartner -BodyParameter $Params | Format-List
AutomaticUserConsentSettings : Microsoft.Graph.PowerShell.Models.MicrosoftGraphInboundOutboundPolicyConfiguration B2BCollaborationInbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting B2BCollaborationOutbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting B2BDirectConnectInbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting B2BDirectConnectOutbound : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyB2BSetting IdentitySynchronization : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantIdentitySyncPolicyPartner InboundTrust : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyInboundTrust IsServiceProvider : TenantId : <TargetTenantId> TenantRestrictions : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessPolicyTenantRestrictions AdditionalProperties : {[@odata.context, https://graph.microsoft.com/v1.0/$metadata#policies/crossTenantAccessPolicy/partners/$entity], [crossCloudMeetingConfiguration, System.Collections.Generic.Dictionary`2[System.String,System.Object]], [protectedContentSharing, System.Collections.Generic.Dictionary`2[System.String,System.Object]]}
使用 Update-MgPolicyCrossTenantAccessPolicyPartner 命令來自動兌換邀請,並隱藏輸出存取的同意提示。
$AutomaticUserConsentSettings = @{ "OutboundAllowed"="True" } Update-MgPolicyCrossTenantAccessPolicyPartner -CrossTenantAccessPolicyConfigurationPartnerTenantId $TargetTenantId -AutomaticUserConsentSettings $AutomaticUserConsentSettings
步驟 6:在來源租使用者中建立設定應用程式
來源租使用者
在來源租使用者中,使用 Invoke-MgInstantiateApplicationTemplate 命令,將組態應用程式的實例從 Microsoft Entra 應用連結庫新增至您的租使用者。
Invoke-MgInstantiateApplicationTemplate -ApplicationTemplateId "518e5f48-1fc8-4c48-9387-9fdf28b0dfe7" -DisplayName "Fabrikam"
使用 Get-MgServicePrincipal 命令來取得服務主體標識碼和應用程式角色識別碼。
Get-MgServicePrincipal -Filter "DisplayName eq 'Fabrikam'" | Format-List
AccountEnabled : True AddIns : {} AlternativeNames : {} AppDescription : AppDisplayName : Fabrikam AppId : <AppId> AppManagementPolicies : AppOwnerOrganizationId : <AppOwnerOrganizationId> AppRoleAssignedTo : AppRoleAssignmentRequired : True AppRoleAssignments : AppRoles : {<AppRoleId>} ApplicationTemplateId : 518e5f48-1fc8-4c48-9387-9fdf28b0dfe7 ClaimsMappingPolicies : CreatedObjects : CustomSecurityAttributes : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue DelegatedPermissionClassifications : DeletedDateTime : Description : DisabledByMicrosoftStatus : DisplayName : Fabrikam Endpoints : ErrorUrl : FederatedIdentityCredentials : HomeRealmDiscoveryPolicies : Homepage : https://account.activedirectory.windowsazure.com:444/applications/default.aspx?metadata=aad2aadsync|ISV9.1|primary|z Id : <ServicePrincipalId> Info : Microsoft.Graph.PowerShell.Models.MicrosoftGraphInformationalUrl KeyCredentials : {} LicenseDetails : ...
初始化服務主體標識碼的變數。
請務必使用服務主體標識碼,而不是應用程式標識碼。
$ServicePrincipalId = "<ServicePrincipalId>"
初始化應用程式角色識別碼的變數。
$AppRoleId= "<AppRoleId>"
步驟 7:測試與目標租用戶的連線
來源租使用者
在來源租使用者中 ,使用 Invoke-MgGraphRequest 命令來測試與目標租用戶的連線,並驗證認證。
$Params = @{ "useSavedCredentials" = $false "templateId" = "Azure2Azure" "credentials" = @( @{ "key" = "CompanyId" "value" = $TargetTenantId } @{ "key" = "AuthenticationType" "value" = "SyncPolicy" } ) } Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$ServicePrincipalId/synchronization/jobs/validateCredentials" -Body $Params
步驟 8:在來源租使用者中建立布建作業
來源租使用者
在來源租使用者中,若要啟用布建,請建立布建作業。
判斷要使用的同步處理範本,例如
Azure2Azure
。範本已預先設定同步處理設定。
在來源租使用者中 ,使用 New-MgServicePrincipalSynchronizationJob 命令,根據範本建立布建作業。
New-MgServicePrincipalSynchronizationJob -ServicePrincipalId $ServicePrincipalId -TemplateId "Azure2Azure" | Format-List
Id : <JobId> Schedule : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSchedule Schema : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSchema Status : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationStatus SynchronizationJobSettings : {AzureIngestionAttributeOptimization, LookaheadQueryEnabled} TemplateId : Azure2Azure AdditionalProperties : {[@odata.context, https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('<ServicePrincipalId>')/synchro nization/jobs/$entity]}
初始化作業標識碼的變數。
$JobId = "<JobId>"
步驟 9:儲存您的認證
來源租使用者
在來源租使用者中 ,使用 Invoke-MgGraphRequest 命令來儲存您的認證。
$Params = @{ "value" = @( @{ "key" = "AuthenticationType" "value" = "SyncPolicy" } @{ "key" = "CompanyId" "value" = $TargetTenantId } ) } Invoke-MgGraphRequest -Method PUT -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$ServicePrincipalId/synchronization/secrets" -Body $Params
步驟 10:將使用者指派給設定
來源租使用者
若要讓跨租使用者同步處理能夠運作,至少必須指派一個內部使用者給設定。
在來源租使用者中,使用 New-MgServicePrincipalAppRoleAssignedTo 命令將內部使用者指派給組態。
$Params = @{ PrincipalId = "<PrincipalId>" ResourceId = $ServicePrincipalId AppRoleId = $AppRoleId } New-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $ServicePrincipalId -BodyParameter $Params | Format-List
AppRoleId : <AppRoleId> CreatedDateTime : 7/31/2023 10:27:12 PM DeletedDateTime : Id : <Id> PrincipalDisplayName : User1 PrincipalId : <PrincipalId> PrincipalType : User ResourceDisplayName : Fabrikam ResourceId : <ServicePrincipalId> AdditionalProperties : {[@odata.context, https://graph.microsoft.com/v1.0/$metadata#appRoleAssignments/$entity]}
步驟 11:依需求測試布建
來源租使用者
現在您已設定好,您可以透過其中一位用戶測試隨選布建。
在來源租使用者中,使用 Get-MgServicePrincipalSynchronizationJobSchema 命令來取得架構規則標識碼。
$SynchronizationSchema = Get-MgServicePrincipalSynchronizationJobSchema -ServicePrincipalId $ServicePrincipalId -SynchronizationJobId $JobId $SynchronizationSchema.SynchronizationRules | Format-List
ContainerFilter : Microsoft.Graph.PowerShell.Models.MicrosoftGraphContainerFilter Editable : True GroupFilter : Microsoft.Graph.PowerShell.Models.MicrosoftGraphGroupFilter Id : <RuleId> Metadata : {defaultSourceObjectMappings, supportsProvisionOnDemand} Name : USER_INBOUND_USER ObjectMappings : {Provision Azure Active Directory Users, , , …} Priority : 1 SourceDirectoryName : Azure Active Directory TargetDirectoryName : Azure Active Directory (target tenant) AdditionalProperties : {}
初始化規則識別碼的變數。
$RuleId = "<RuleId>"
使用 New-MgServicePrincipalSynchronizationJobOnDemand 命令,隨選布建測試使用者。
$Params = @{ Parameters = @( @{ Subjects = @( @{ ObjectId = "<UserObjectId>" ObjectTypeName = "User" } ) RuleId = $RuleId } ) } New-MgServicePrincipalSynchronizationJobOnDemand -ServicePrincipalId $ServicePrincipalId -SynchronizationJobId $JobId -BodyParameter $Params | Format-List
Key : Microsoft.Identity.Health.CPP.Common.DataContracts.SyncFabric.StatusInfo Value : [{"provisioningSteps":[{"name":"EntryImport","type":"Import","status":"Success","description":"Retrieved User 'user1@fabrikam.com' from Azure Active Directory","timestamp":"2023-07-31T22:31:15.9116590Z","details":{"objectId": "<UserObjectId>","accountEnabled":"True","displayName":"User1","mailNickname":"user1","userPrincipalName":"use ... AdditionalProperties : {[@odata.context, https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.stringKeyStringValuePair]}
步驟 12:啟動布建作業
來源租使用者
現在已設定布建作業,請在來源租使用者中,使用 Start-MgServicePrincipalSynchronizationJob 命令來啟動布建作業。
Start-MgServicePrincipalSynchronizationJob -ServicePrincipalId $ServicePrincipalId -SynchronizationJobId $JobId
步驟 13:監視布建
來源租使用者
現在,布建作業正在執行,請在來源租使用者中使用 Get-MgServicePrincipalSynchronizationJob 命令來監視目前布建周期的進度,以及迄今為止的統計數據,例如已在目標系統中建立的使用者和群組數目。
Get-MgServicePrincipalSynchronizationJob -ServicePrincipalId $ServicePrincipalId -SynchronizationJobId $JobId | Format-List
Id : <JobId> Schedule : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSchedule Schema : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationSchema Status : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSynchronizationStatus SynchronizationJobSettings : {AzureIngestionAttributeOptimization, LookaheadQueryEnabled} TemplateId : Azure2Azure AdditionalProperties : {[@odata.context, https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('<ServicePrincipalId>')/synchro nization/jobs/$entity]}
除了監視布建作業的狀態之外,請使用 Get-MgAuditLogProvisioning 命令來擷取布建記錄,並取得所有發生的布建事件。 例如,查詢特定使用者,並判斷是否已成功布建。
Get-MgAuditLogDirectoryAudit | Select -First 10 | Format-List
ActivityDateTime : 7/31/2023 12:08:17 AM ActivityDisplayName : Export AdditionalDetails : {Details, ErrorCode, EventName, ipaddr...} Category : ProvisioningManagement CorrelationId : aaaa0000-bb11-2222-33cc-444444dddddd Id : Sync_aaaa0000-bb11-2222-33cc-444444dddddd_L5BFV_161778479 InitiatedBy : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAuditActivityInitiator1 LoggedByService : Account Provisioning OperationType : Result : success ResultReason : User 'user2@fabrikam.com' was created in Azure Active Directory (target tenant) TargetResources : {<ServicePrincipalId>, } AdditionalProperties : {} ActivityDateTime : 7/31/2023 12:08:17 AM ActivityDisplayName : Export AdditionalDetails : {Details, ErrorCode, EventName, ipaddr...} Category : ProvisioningManagement CorrelationId : aaaa0000-bb11-2222-33cc-444444dddddd Id : Sync_aaaa0000-bb11-2222-33cc-444444dddddd_L5BFV_161778264 InitiatedBy : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAuditActivityInitiator1 LoggedByService : Account Provisioning OperationType : Result : success ResultReason : User 'user2@fabrikam.com' was updated in Azure Active Directory (target tenant) TargetResources : {<ServicePrincipalId>, } AdditionalProperties : {} ActivityDateTime : 7/31/2023 12:08:14 AM ActivityDisplayName : Synchronization rule action AdditionalDetails : {Details, ErrorCode, EventName, ipaddr...} Category : ProvisioningManagement CorrelationId : aaaa0000-bb11-2222-33cc-444444dddddd Id : Sync_aaaa0000-bb11-2222-33cc-444444dddddd_L5BFV_161778395 InitiatedBy : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAuditActivityInitiator1 LoggedByService : Account Provisioning OperationType : Result : success ResultReason : User 'user2@fabrikam.com' will be created in Azure Active Directory (target tenant) (User is active and assigned in Azure Active Directory, but no matching User was found in Azure Active Directory (target tenant)) TargetResources : {<ServicePrincipalId>, } AdditionalProperties : {}
疑難排解秘訣
徵兆 - 許可權不足錯誤
當您嘗試執行動作時,您會收到類似下列的錯誤訊息:
code: Authorization_RequestDenied
message: Insufficient privileges to complete the operation.
原因
登入的用戶沒有足夠的許可權,或您需要同意其中一個必要的許可權。
方案
請確定您已獲派必要的角色。 請參閱 本文稍早的必要條件 。
當您使用 連線-MgGraph 登入時,請確定您指定必要的範圍。 請參閱 本文稍早的步驟 1:登入目標租 使用者和 步驟 4:登入來源租使用者 。
徵兆 - 新MgPolicyCrossTenantAccessPolicyPartner_Create錯誤
當您嘗試建立新的合作夥伴組態時,您會收到類似下列的錯誤訊息:
New-MgPolicyCrossTenantAccessPolicyPartner_Create: Another object with the same value for property tenantId already exists.
原因
您可能嘗試建立已經存在的組態或物件,可能來自先前的組態。
方案
確認您的語法,以及您使用的是正確的租用戶標識符。
使用 Get-MgPolicyCrossTenantAccessPolicyPartner 命令來列出現有的物件。
如果您有現有的物件,您可能需要使用 Update-MgPolicyCrossTenantAccessPolicyPartner 進行更新
徵兆 - Request_MultipleObjectsWithSameKeyValue錯誤
當您試著啟用使用者同步處理時,會收到類似下列的錯誤訊息:
Invoke-MgGraphRequest: PUT https://graph.microsoft.com/v1.0/policies/crossTenantAccessPolicy/partners/<SourceTenantId>/identitySynchronization
HTTP/1.1 409 Conflict
...
{"error":{"code":"Request_MultipleObjectsWithSameKeyValue","message":"A conflicting object with one or more of the specified property values is present in the directory.","details":[{"code":"ConflictingObjects","message":"A conflicting object with one or more of the specified property values is present in the directory.", ... }}}
原因
您可能嘗試建立已經存在的原則,可能來自先前的設定。
方案
確認您的語法,以及您使用的是正確的租用戶標識符。
使用 Get-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization 命令來列出
IsSyncAllowed
設定。(Get-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization -CrossTenantAccessPolicyConfigurationPartnerTenantId $SourceTenantId).UserSyncInbound
如果您有現有的原則,您可能需要使用 Set-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization 命令進行更新,以啟用使用者同步處理。
$Params = @{ userSyncInbound = @{ isSyncAllowed = $true } } Set-MgPolicyCrossTenantAccessPolicyPartnerIdentitySynchronization -CrossTenantAccessPolicyConfigurationPartnerTenantId $SourceTenantId -BodyParameter $Params