@@ -1,12 +1,14 @@ --- title: Configure cross-tenant synchronization description: "Configure cross-tenant synchronization using the Microsoft Entra admin center. Step-by-step guide covering trust settings, provisioning scope, attribute mappings, and testing."+author: akhil-potturi+ms.author: potturiakhil ms.topic: how-to-ms.date: 08/06/2026-ms.custom: it-pro, sfi-image-nochange+ms.date: 11/02/2026+ms.custom: it-pro, msecd-doc-authoring-1032 ai-usage: ai-assisted zone_pivot_groups: same-cloud-cross-cloud-synchronization-#Customer intent: As a dev, devops, or it admin, I want to+#customer intent: As an IT administrator, I want to configure cross-tenant synchronization so that I can provision users and groups across tenants in my organization. ---  # Configure cross-tenant synchronization@@ -66,9 +68,11 @@ By the end of this article, you'll be able to:  ::: zone pivot="same-cloud-synchronization" - Microsoft Entra ID P1 or P2 license for cross-tenant user sync. Microsoft Entra ID Governance or Microsoft Entra Suite licenses for cross-tenant group sync. For more information, see [License requirements](cross-tenant-synchronization-overview.md#license-requirements).+- For role-enabled group sync (preview), a role-assignable group in the source tenant. The administrative roles listed here are sufficient to configure role-enabled group sync. - [Security Administrator](../role-based-access-control/permissions-reference.md#security-administrator) role to configure cross-tenant access settings. - [Hybrid Identity Administrator](../role-based-access-control/permissions-reference.md#hybrid-identity-administrator) role to configure cross-tenant synchronization. - [Cloud Application Administrator](../role-based-access-control/permissions-reference.md#cloud-application-administrator) or [Application Administrator](../role-based-access-control/permissions-reference.md#application-administrator) role to assign users to a configuration and to delete a configuration.+ ::: zone-end  ::: zone pivot="cross-cloud-synchronization"@@ -161,9 +165,13 @@ By the end of this article, you'll be able to:      Optionally, select the **Allow group synchronization into this tenant** checkbox. +    To synchronize role-assignable groups, also select **Allow role-enabled group synchronization into this tenant**. Keep both group synchronization checkboxes selected.+     For more information, see [Group synchronization](cross-tenant-synchronization-overview.md#group-synchronization). -    :::image type="content" source="../../media/external-identities/access-settings-users-sync.png" alt-text="Screenshot that shows the Cross-tenant sync tab with the Allow user synchronization into this tenant and Allow group synchronization into this tenant checkboxes." lightbox="../../media/external-identities/access-settings-users-sync.png":::+    :::image type="content" source="../../media/external-identities/allow-role-enabled-groups-inbound.png" alt-text="Screenshot of the Cross-tenant sync tab showing the inbound user, group, and role-enabled group synchronization checkboxes." lightbox="../../media/external-identities/allow-role-enabled-groups-inbound.png":::++    The screenshot identifies the settings. The group and role-enabled group checkboxes aren't selected in this example. ::: zone-end  ::: zone pivot="cross-cloud-synchronization"@@ -295,6 +303,11 @@ The Microsoft Entra provisioning service allows you to define who will be provis  Start small. Test with a small set of users before rolling out to everyone. When the scope for provisioning is set to assigned users and groups, you can control it by assigning one or two users to the configuration. You can further refine who is in scope for provisioning by creating attribute-based scoping filters, described in the [next step](#step-8-optional-define-who-is-in-scope-for-provisioning-with-scoping-filters). +::: zone pivot="same-cloud-synchronization"+> [!IMPORTANT]+> Before assigning role-assignable groups to the configuration, complete [Configure role-enabled group sync](#configure-role-enabled-group-sync). The `isAssignableToRole` mapping applies only when the target group is created. After saving the mapping, return to this step to assign the groups.+::: zone-end+ 1. In the source tenant, on the **Overview** page, select the **Properties** tab.      :::image type="content" source="./media/cross-tenant-synchronization-configure/provisioning-settings.png" alt-text="Screenshot of the Overview page that shows the Properties tab." lightbox="./media/cross-tenant-synchronization-configure/provisioning-settings.png":::@@ -370,7 +383,7 @@ Regardless of the value you selected for **Scope** in the previous step, you can      By default, this toggle is set to **No**. -10. If you want to scoping filters for groups, follow similar previous steps as users.+10. If you want to define scoping filters for groups, follow the previous steps for users. ::: zone-end  ## Step 9: Review attribute mappings@@ -421,9 +434,40 @@ Attribute mappings allow you to define how data should flow between the source t     :::image type="content" source="./media/cross-tenant-synchronization-configure/provisioning-attribute-mapping-displayname-expression.png" alt-text="Screenshot of the Edit Attribute page that shows the displayName attribute with the Expression box." lightbox="./media/cross-tenant-synchronization-configure/provisioning-attribute-mapping-displayname-expression.png":::  ::: zone pivot="same-cloud-synchronization"-9. On the **Provisioning** page, under the **Mappings** section, select **Provision Microsoft Entra ID Groups** to open the **Attribute Mapping** page.+1. On the **Provisioning** page, under the **Mappings** section, select **Provision Microsoft Entra ID Groups** to open the **Attribute Mapping** page.++1. If you want to modify attribute mappings for groups, follow the previous steps for users.++### Configure role-enabled group sync++Role-enabled group sync lets you create role-assignable groups in the target tenant. It doesn't copy the source group's role assignments. Configure the mapping before adding role-assignable groups to the job's scope, including when you add this feature to an existing group synchronization configuration.++1. Confirm that the target tenant allows both group synchronization and role-enabled group synchronization, as described in [step 2](#step-2-enable-user-and-group-synchronization-in-the-target-tenant).++1. In the source tenant, open your cross-tenant synchronization configuration. Select **Attribute mapping** > **Groups**. If your configuration uses the older interface, select **Provisioning** > **Mappings** > **Provision Microsoft Entra ID Groups**.++1. Confirm that group provisioning is enabled, as described in [step 8](#step-8-optional-define-who-is-in-scope-for-provisioning-with-scoping-filters).++1. Select **Add attribute mapping** and configure these settings:++    | Setting | Value |+    | --- | --- |+    | **Mapping type** | **Direct** |+    | **Source attribute** | `isAssignableToRole` |+    | **Target attribute** | `isAssignableToRole` |+    | **Default value (if null)** | Leave blank. |+    | **Apply this mapping** | **Only during object creation** |+    | **Match objects using this attribute** | Leave unchecked. |++    :::image type="content" source="./media/cross-tenant-synchronization-configure/mapping-creation-only.png" alt-text="Screenshot of a direct isAssignableToRole mapping applied only during object creation, with a blank default value and matching unchecked." lightbox="./media/cross-tenant-synchronization-configure/mapping-creation-only.png":::++1. Save the mapping and confirm that the group attribute mapping list includes a direct `isAssignableToRole` to `isAssignableToRole` mapping. Don't use a constant `true` or an expression.++    :::image type="content" source="./media/cross-tenant-synchronization-configure/role-assignable-mapping.png" alt-text="Screenshot of the Groups attribute mapping list showing a direct isAssignableToRole to isAssignableToRole mapping." lightbox="./media/cross-tenant-synchronization-configure/role-assignable-mapping.png":::++1. Return to [step 7](#step-7-define-who-is-in-scope-for-provisioning) to assign the intended source role-assignable groups. Review the group scoping filters in step 8 to ensure those groups are included. -10. If you want to modify attribute mappings for groups, follow similar previous steps as users.+The mapping doesn't convert existing non-role-assignable target groups. If groups were synchronized before you configured this mapping, see [Replace previously synchronized groups](#replace-previously-synchronized-groups). ::: zone-end  > [!TIP]@@ -515,7 +559,7 @@ Once you've started a provisioning job, you can monitor the status.      :::image type="content" source="./media/cross-tenant-synchronization-configure/provisioning-job-start.png" alt-text="Screenshot of the Configurations Overview page that shows the status of the provisioning cycle." lightbox="./media/cross-tenant-synchronization-configure/provisioning-job-start.png"::: -1. Select **Provisioning logs** to determine which users have been provisioned successfully or unsuccessfully. By default, the logs are filtered by the service principal ID of the configuration. For more information, see [Provisioning logs in Microsoft Entra ID](../monitoring-health/concept-provisioning-logs.md?toc=/entra/identity/multi-tenant-organizations/toc.json).+1. Select **Provisioning logs** to determine which objects have been provisioned successfully or unsuccessfully. By default, the logs are filtered by the service principal ID of the configuration. For more information, see [Provisioning logs in Microsoft Entra ID](../monitoring-health/concept-provisioning-logs.md?toc=/entra/identity/multi-tenant-organizations/toc.json).      :::image type="content" source="./media/cross-tenant-synchronization-configure/provisioning-logs.png" alt-text="Screenshot of the Provisioning logs page that lists the log entries and their status." lightbox="./media/cross-tenant-synchronization-configure/provisioning-logs.png"::: @@ -529,6 +573,18 @@ Once you've started a provisioning job, you can monitor the status.      :::image type="content" source="./media/cross-tenant-synchronization-configure/audit-logs-users-target.png" alt-text="Screenshot of the Audit logs page in the target tenant that lists the log entries for user management." lightbox="./media/cross-tenant-synchronization-configure/audit-logs-users-target.png"::: +::: zone pivot="same-cloud-synchronization"+### Verify role-enabled group sync++For role-enabled group sync, verify that the target groups can receive role assignments.++1. In the source tenant, check **Provisioning logs** for the selected groups and resolve any reported errors.+1. In the target tenant, verify that each newly provisioned group is role-assignable.+1. Assign the required roles to the target groups using the target tenant's role-assignment process. For more information, see [Use Microsoft Entra groups to manage role assignments](../role-based-access-control/groups-concept.md).++A role assigned to a source group isn't automatically assigned to its target group.+::: zone-end+ ## Step 14: Configure leave settings  ![Icon for the target tenant.](../../media/common/icons/entra-id.png)<br/>**Target tenant**@@ -541,8 +597,36 @@ Even though users are being provisioned in the target tenant, they still might b  This setting also applies to B2B collaboration and B2B direct connect, so if you set **External user leave settings** to **No**, B2B collaboration users and B2B direct connect users can't leave your organization themselves. For more information, see [Leave an organization as an external user](../../external-id/leave-the-organization.md#more-information-for-administrators). +::: zone pivot="same-cloud-synchronization"+## Replace previously synchronized groups++Groups synchronized before you configured the `isAssignableToRole` mapping might already exist as non-role-assignable groups in the target tenant. Adding the mapping doesn't convert those groups because the property is set only during object creation.++> [!WARNING]+> Replacing these groups requires manually hard-deleting the old target groups. Hard deletion is destructive. Review group dependencies and the impact of replacement with the target tenant administrator before proceeding. Don't delete the source groups.++1. Identify the affected target groups and plan their replacement with the target tenant administrator.+1. Confirm that the inbound policy and creation-only attribute mapping are configured as described in [Configure role-enabled group sync](#configure-role-enabled-group-sync).+1. Follow your approved change process to manually hard-delete the affected old target groups.+1. Provision the source groups again and verify that the replacement target groups are role-assignable before assigning roles.+::: zone-end+ ## Troubleshoot common cross-tenant synchronization scenarios +::: zone pivot="same-cloud-synchronization"+### Role-enabled group sync doesn't produce the expected result++Use the following checks before changing the configuration.++| Symptom | Check |+| --- | --- |+| A new target group isn't role-assignable. | Verify that the source group is role-assignable and that the direct `isAssignableToRole` mapping was saved before target group creation. |+| An existing target group remains non-role-assignable. | Adding the mapping doesn't convert existing groups. See [Replace previously synchronized groups](#replace-previously-synchronized-groups). |+| A group isn't provisioned. | Check inbound group and role-enabled group synchronization permissions, group provisioning enablement, assigned scope, scoping filters, and provisioning logs. |+| The source group's role is missing in the target tenant. | Assign the role separately in the target tenant. Role assignments aren't synchronized. |++::: zone-end+ ### Symptom - Test connection fails with AzureActiveDirectoryCrossTenantSyncPolicyCheckFailure  When configuring cross-tenant synchronization in the source tenant and you test the connection, it fails with one of the following error messages: