使用 PowerShell 或 Microsoft Graph API 來設定跨租用戶同步處理
本文說明使用 Microsoft Graph PowerShell 或 Microsoft Graph API 設定跨租使用者同步處理的重要步驟。 設定時，Microsoft Entra ID 會自動佈建和取消佈建目標租用戶中的 B2B 使用者。 如需使用 Microsoft Entra 系統管理中心的詳細步驟，請參閱 設定跨租用戶同步處理。
必要條件
來源租用戶
- Microsoft Entra ID P1 或 P2 授權。 如需詳細資訊，請參閱授權需求。
- 以安全性系統管理員角色設定跨租用戶存取設定。
- 以混合式身分識別系統管理員角色設定跨租用戶同步處理。
- 以雲端應用程式管理員或應用程式管理員角色，將使用者指派給設定並刪除設定。
- 以全域管理員角色同意所需的權限。
目標租用戶
步驟 1：登入目標租用戶
目標租用戶
啟動 PowerShell。
取得來源和目標租用戶的租用戶識別碼，並初始化變數。
$SourceTenantId = "<SourceTenantId>" $TargetTenantId = "<TargetTenantId>"使用 Connect-MgGraph 命令來登入目標租用戶，並同意以下所需的權限。
Policy.Read.AllPolicy.ReadWrite.CrossTenantAccess
Connect-MgGraph -TenantId $TargetTenantId -Scopes "Policy.Read.All","Policy.ReadWrite.CrossTenantAccess"
![Microsoft Graph 總管設定檔的螢幕擷取畫面，其中包含 [同意權限] 連結。](media/cross-tenant-synchronization-configure-graph/graph-explorer-profile.png#lightbox)
步驟 2：在目標租用戶中啟用使用者同步處理
目標租用戶
在目標租用戶中，使用 New-MgPolicyCrossTenantAccessPolicyPartner 命令，在目標租用戶與來源租用戶之間的跨租用戶存取原則中建立新的合作夥伴設定。 在要求中使用來源租用戶識別碼。
如果您收到錯誤
New-MgPolicyCrossTenantAccessPolicyPartner_Create: Another object with the same value for property tenantId already exists，您可能已經有現有的設定。 如需詳細資訊，請參閱 Symptom - New-MgPolicyCrossTenantAccessPolicyPartner_Create error。$Params = @{ TenantId = $SourceTenantId } New-MgPolicyCrossTenantAccessPolicyPartner -BodyParameter $Params | Format-ListAutomaticUserConsentSettings : 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錯誤，您可能已經有現有的原則。 如需詳細資訊，請參閱 Symptom - Request_MultipleObjectsWithSameKeyValue error。$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).UserSyncInboundIsSyncAllowed ------------- True
步驟 3：在目標租用戶中自動兌換邀請
目標租用戶
在目標租用戶中，使用 Update-MgPolicyCrossTenantAccessPolicyPartner 命令來自動兌換邀請，並隱藏輸入存取的同意提示。
$AutomaticUserConsentSettings = @{ "InboundAllowed"="True" } Update-MgPolicyCrossTenantAccessPolicyPartner -CrossTenantAccessPolicyConfigurationPartnerTenantId $SourceTenantId -AutomaticUserConsentSettings $AutomaticUserConsentSettings
步驟 4：登入來源租用戶
來源租用戶
啟動 PowerShell 的執行個體。
取得來源和目標租用戶的租用戶識別碼，並初始化變數。
$SourceTenantId = "<SourceTenantId>" $TargetTenantId = "<TargetTenantId>"使用 Connect-MgGraph 命令來登入來源租用戶，並同意以下所需的權限。
Policy.Read.AllPolicy.ReadWrite.CrossTenantAccessApplication.ReadWrite.AllDirectory.ReadWrite.AllAuditLog.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，您可能已經有現有的設定。 如需詳細資訊，請參閱 Symptom - New-MgPolicyCrossTenantAccessPolicyPartner_Create error。$Params = @{ TenantId = $TargetTenantId } New-MgPolicyCrossTenantAccessPolicyPartner -BodyParameter $Params | Format-ListAutomaticUserConsentSettings : 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-ListAccountEnabled : 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-ListId : <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-ListAppRoleId : <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-ListContainerFilter : 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-ListKey : 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-ListId : <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-ListActivityDateTime : 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.
原因
登入的使用者沒有足夠的權限，或您需要同意其中一個必要的權限。
方案
請確定您已指派必要的角色。 請參閱本文稍早之前的 必要條件。
當您使用 Connect-MgGraph 登入時，請確定您指定必要的範圍。 請參閱本文稍早的步驟 1：登入目標租用戶和步驟 4：登入來源租用戶。
徵兆 - New-MgPolicyCrossTenantAccessPolicyPartner_Create error
當您嘗試建立新的合作夥伴設定時，您會收到類似下列的錯誤訊息：
New-MgPolicyCrossTenantAccessPolicyPartner_Create: Another object with the same value for property tenantId already exists.
原因
您可能嘗試建立已經存在的設定或物件，可能來自先前的設定。
方案
確認您的語法，以及您使用的是正確的租用戶識別碼。
使用 Get-MgPolicyCrossTenantAccessPolicyPartner 命令來列出現有的物件。
如果您有現有的物件，您可能需要使用 Update-MgPolicyCrossTenantAccessPolicyPartner 進行更新
徵兆 - Request_MultipleObjectsWithSameKeyValue error
當您試著啟用使用者同步處理時，會收到類似下列的錯誤訊息：
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