Entra ID Cross-Tenant Synchronization

Introduction

In today's interconnected business landscape, organizations frequently collaborate with partners, subsidiaries, or acquire new entities. This often necessitates sharing resources, applications, and facilitating user access across distinct Microsoft Entra ID tenants. While Entra ID B2B collaboration revolutionized external user management, managing multiple B2B guest accounts for the same user across different partner tenants can become an administrative burden, leading to identity sprawl, friction in access, and challenges in lifecycle management.

Entra ID Cross-Tenant Synchronization emerges as a powerful capability designed to streamline this process. It enables automatic synchronization of Entra ID users between two different Entra ID tenants, creating them as members in the target tenant rather than guests. This capability is particularly beneficial for multi-tenant organizations experiencing mergers, acquisitions, joint ventures, or needing a more integrated identity experience between tightly coupled Entra ID environments.

This article provides a comprehensive technical deep-dive into Entra ID Cross-Tenant Synchronization, outlining its core concepts, implementation steps, and best practices. It is intended for Entra ID administrators, architects, and security professionals responsible for identity management in complex multi-tenant Microsoft 365 environments.

Why this matters

Managing identities across tenant boundaries presents numerous challenges that directly impact business operations, security posture, and administrative overhead. Cross-Tenant Synchronization directly addresses these pain points. From a technical perspective, it eliminates the need for manual B2B invitation and redemption processes for integrated users, reducing human error and improving user experience. Importantly, synchronized users appear as members in the target tenant, granting them a more integrated identity and allowing for direct assignment of licenses, Intune policies, and access to resources as if they were native users.

From a business perspective, this capability significantly enhances productivity during mergers and acquisitions by rapidly integrating user populations and enabling seamless access to shared applications and data. It reduces compliance risk by providing a single source of truth for user lifecycle management across tenants, ensuring that access is provisioned and de-provisioned consistently. This streamlined process also reduces operational costs associated with manual user management and helpdesk tickets related to B2B guest account issues. Furthermore, by consolidating identity management, organizations can better adhere to Zero Trust principles, ensuring every access request is explicitly verified, regardless of originating tenant.

Key concepts

• Source Tenant & Target Tenant: The Entra ID tenant from which users are synchronized (Source) and the Entra ID tenant to which users are provisioned (Target).
• Cross-Tenant Synchronization Settings: Configuration object within the source tenant that defines the synchronization scope, attributes, and target tenant details.
• Synchronization Job: The automated process that runs periodically, querying for changes in the source tenant based on the defined scope and provisioning/updating/de-provisioning users in the target tenant.
• User Provisioning: The act of creating, updating, or deleting user accounts in the target tenant based on changes detected in the source tenant. Unlike B2B guest accounts, these users are synchronized as members.
• ExternalUserID: A critical attribute used to match users across tenants and ensure that existing B2B guest accounts can be converted to synchronized member accounts or that new users are created without duplication. This attribute is stored in the target tenant and links back to the source user's object ID.
• Attribute Mapping: Defines how attributes from the source user object (e.g., userPrincipalName, displayName, jobTitle) are mapped to corresponding attributes in the target user object.
• Scoping Filters: Conditions applied to the source tenant's user population to determine which users are eligible for synchronization (e.g., users in a specific group, users with a particular attribute value).
• Admin Consent: Required on both source and target tenants to authorize the synchronization application to read user data from the source and manage users in the target.

Step-by-step implementation

Implementing Entra ID Cross-Tenant Synchronization involves configuring both the source and target tenants.

1. Grant Admin Consent in the Target Tenant:

As a Global Administrator in the target tenant, navigate to the Entra admin center (entra.microsoft.com). Go to External Identities > Cross-tenant access settings. Click on Organizational settings and add the source tenant. Configure the inbound settings for the source tenant. Under Trust settings, enable Trust multifactor authentication from Microsoft Entra tenants (if desired for seamless SSO). Under Cross-tenant synchronization, click Customize settings. On the Synchronization configuration tab, select Allow users to sync into this tenant*. This grant allows the source tenant to synchronize users into this target tenant.

1. Configure Cross-Tenant Synchronization in the Source Tenant:

As a Global Administrator in the source tenant, navigate to the Entra admin center (entra.microsoft.com). Go to External Identities > Cross-tenant access settings. Click on Organizational settings and add the target tenant. Configure the outbound settings for the target tenant. Under Cross-tenant synchronization, click Customize settings. On the Users and groups tab, select Synchronize users to this configuration. This enables synchronization for this specific configuration. Go to Provisioning > Add provisioning. Select Cross-tenant synchronization. Provide a meaningful Provisioning name. For Target tenant ID, enter the Tenant ID of the target Entra ID. This can be found in the target tenant's Entra admin center under Overview > Tenant ID. Click Review + create and then Create*. This creates the synchronization job.

1. Configure Attribute Mappings and Scoping:

Once the synchronization job is created in the source tenant: Navigate back to the synchronization job under External Identities > Cross-tenant access settings > Organizational settings > (Target Tenant) > Cross-tenant synchronization > Customize settings > Provisioning > (Your Synchronization Job). Under Mappings, review and configure the attribute mappings. Ensure essential attributes like userPrincipalName, displayName, and mail are mapped correctly. You can also map custom extensions or other standard attributes. Under Source Object Scoping, define which users should be synchronized. A common approach is to use a specific group: Change Scope to Sync only assigned users and groups. Under Users and groups, add the security group(s) containing the users you wish to synchronize to the target tenant. Review the synchronization rules, especially the matching precedence and object matching for existing users. Ensure userPrincipalName is typically used as the primary matching attribute and that the externalId attribute in the target is correctly populated/matched to the source user's objectId.

1. Start Synchronization:

Once mappings and scoping are configured, go back to the Overview page of your synchronization job. Set Provisioning Status to On. Click Save. The synchronization job will now begin its initial cycle. You can monitor its progress under Provisioning logs*.

# PowerShell to grant outbound cross-tenant synchronization consent from Source Tenant
# Requires Microsoft.Graph.Identity.CrossTenantAccess module
# Ensure you are connected to the Source Tenant

# Define the Target Tenant ID
$targetTenantId = "YOUR_TARGET_TENANT_ID_HERE"

# Ensure the required module is installed and connected
# Install-Module Microsoft.Graph.Identity.CrossTenantAccess -AllowClobber -Force
# Connect-MgGraph -Scopes "CrossTenantAccessSettings.ReadWrite.All"

# Get current cross-tenant access settings
$crossTenantAccessSettings = Get-MgBetaPolicyCrossTenantAccessSetting

# Check if target tenant already exists in organizational settings
$targetOrg = $crossTenantAccessSettings.Partners | Where-Object { $_.TenantId -eq $targetTenantId }

if (-not $targetOrg) {
    # If not, add the target tenant to organizational settings
    $targetOrg = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessUserConsentSettingPair
    $targetOrg.tenantId = $targetTenantId

    Update-MgBetaPolicyCrossTenantAccessSetting -Body @{
        Partners = $crossTenantAccessSettings.Partners + $targetOrg
    }
    Write-Host "Added $targetTenantId to organizational settings."
    $crossTenantAccessSettings = Get-MgBetaPolicyCrossTenantAccessSetting # Refresh
}

# Configure outbound synchronization for the target tenant
$outboundSyncSetting = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessSynchronizationOutbound
$outboundSyncSetting.B2BManagementPolicy = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessGroupMemberSynchronizationPolicy
$outboundSyncSetting.B2BManagementPolicy.UsersAndGroups = New-Object -TypeName Microsoft.Graph.PowerShell.Models.MicrosoftGraphCrossTenantAccessInboundOrOutboundPolicyConfiguration
$outboundSyncSetting.B2BManagementPolicy.UsersAndGroups.SynchronizeAllUsers = "false" # Set to true to sync all users, or false and use scoping filters in UI

# Update the partner settings for the target tenant
$targetOrg.SynchronizationOutbound = $outboundSyncSetting

Update-MgBetaPolicyCrossTenantAccessSetting -TenantId $targetTenantId -Body $targetOrg

Write-Host "Configured outbound cross-tenant synchronization settings for tenant $targetTenantId."

Example configuration

This JSON snippet represents a part of the attribute mapping configuration for a Cross-Tenant Synchronization job. It illustrates how source attributes are mapped to target attributes, including a common scenario for userPrincipalName and mail.

{
  "active": true,
  "attributeMappings": [
    {
      "source": { "name": "userPrincipalName", "type": "String", "isReference": false },
      "target": { "name": "userPrincipalName", "type": "String", "isReference": false },
      "mappingType": "Direct",
      "exportMissingReferences": false
    },
    {
      "source": { "name": "mail", "type": "String", "isReference": false },
      "target": { "name": "mail", "type": "String", "isReference": false },
      "mappingType": "Direct",
      "exportMissingReferences": false
    },
    {
      "source": { "name": "displayName", "type": "String", "isReference": false },
      "target": { "name": "displayName", "type": "String", "isReference": false },
      "mappingType": "Direct",
      "exportMissingReferences": false
    },
    {
      "source": { "name": "givenName", "type": "String", "isReference": false },
      "target": { "name": "givenName", "type": "String", "isReference": false },
      "mappingType": "Direct",
      "exportMissingReferences": false
    },
    {
      "source": { "name": "surname", "type": "String", "isReference": false },
      "target": { "name": "surname", "type": "String", "isReference": false },
      "mappingType": "Direct",
      "exportMissingReferences": false
    },
    {
      "source": { "name": "jobTitle", "type": "String", "isReference": false },
      "target": { "name": "jobTitle", "type": "String", "isReference": false },
      "mappingType": "Direct",
      "exportMissingReferences": false
    },
    {
      "source": { "name": "objectId", "type": "String", "isReference": false },
      "target": { "name": "externalId", "type": "String", "isReference": false },
      "mappingType": "Direct",
      "exportMissingReferences": false,
      "matchOn": true,
      "matchingPriorities": [1]
    }
  ],
  "name": "UserAccountProvisioning",
  "objectType": "user",
  "scope": {
    "type": "Group",
    "value": "a1b2c3d4-e5f6-7890-1234-567890abcdef" // Example Group ID for scoping
  }
}

Common pitfalls

• Forgetting Admin Consent in Both Tenants: This is a fundamental requirement. Synchronization will fail or never start if consent hasn't been granted appropriately in both the source and target tenants as a Global Administrator.
• Incorrect Scoping Filters: Overly broad filters can lead to unintended users being synchronized, while overly restrictive filters can prevent necessary users from being provisioned. Always test with a small, dedicated group first.
• Duplicate User Principal Names (UPNs) in Target: If a synchronized user's UPN from the source tenant already exists in the target tenant, synchronization will fail for that user unless a different matching attribute or suffix is used. Plan for UPN uniqueness.
• Misconfigured Attribute Mappings: Incorrect attribute mappings can lead to incomplete user profiles or issues with authentication/authorization in the target tenant. Pay close attention to attributes like mail and userPrincipalName.
• Not converting B2B guests to members: If users already exist as B2B guests in the target tenant, the synchronization needs to be configured correctly to match and convert them to members rather than attempting to create new, duplicate accounts.
• Relying solely on Delta Sync: While the service performs delta synchronization, always confirm the initial full sync is successful and understand the potential delays before all users appear.

Best practices

• Phased Rollout: Begin with a small pilot group of users and applications before expanding to larger populations. This allows for early detection and mitigation of issues.
• Clear Ownership and Communication: Define clear administrative responsibilities for managing the synchronization job in both the source and target tenants. Communicate the changes to affected users.
• Robust Scoping Mechanisms: Implement group-based scoping for better control and easier management. Utilize dynamic groups where appropriate to automate user inclusion/exclusion.
• Consistent Attribute Mapping: Ensure critical attributes like ImmutableId, userPrincipalName, mail, and displayName are consistently mapped. Consider leveraging extension attributes for custom data that needs to traverse tenants.
• Monitor Synchronization Logs: Regularly review the provisioning logs in the Entra admin center (entra.microsoft.com > Identity > Monitoring & health > Provisioning logs) to identify and troubleshoot any synchronization errors. Set up alerts for critical failures.
• Zero Trust Integration: When trusting MFA from the source tenant, ensure the source tenant has strong MFA policies and conditional access controls aligned with your Zero Trust strategy. This helps maintain a strong security posture.

Further reading

• What is cross-tenant synchronization?
• Configure cross-tenant synchronization
• Plan cross-tenant synchronization for external access
• Microsoft Entra cross-tenant synchronization FAQ