Skip to content

Latest commit

 

History

History
228 lines (163 loc) · 11.7 KB

powershell-scoped-synchronization.md

File metadata and controls

228 lines (163 loc) · 11.7 KB
Raw
title description author manager ms.service ms.subservice ms.topic ms.date ms.author ms.reviewer ms.custom
Scoped synchronization using PowerShell for Microsoft Entra Domain Services | Microsoft Docs
Learn how to use Microsoft Graph PowerShell to configure scoped synchronization from Microsoft Entra ID to a Microsoft Entra Domain Services managed domain
justinha
amycolannino
entra-id
domain-services
how-to
03/13/2024
justinha
wanjikumugo
has-azure-ad-ps-ref, devx-track-azurepowershell, azure-ad-ref-level-one-done

Configure scoped synchronization from Microsoft Entra ID to Microsoft Entra Domain Services using Microsoft Graph PowerShell

To provide authentication services, Microsoft Entra Domain Services synchronizes users and groups from Microsoft Entra ID. In a hybrid environment, users and groups from an on-premises Active Directory Domain Services (AD DS) environment can be first synchronized to Microsoft Entra ID using Microsoft Entra Connect, and then synchronized to Domain Services.

By default, all users and groups from a Microsoft Entra directory are synchronized to a Domain Services managed domain. If you have specific needs, you can instead choose to synchronize only a defined set of users.

This article shows you how to create a managed domain that uses scoped synchronization and then change or disable the set of scoped users using MS Graph PowerShell. You can also complete these steps using the Microsoft Entra admin center.

Before you begin

To complete this article, you need the following resources and privileges:

Scoped synchronization overview

By default, all users and groups from a Microsoft Entra directory are synchronized to a managed domain. If only a few users need to access the managed domain, you can synchronize only those user accounts. This scoped synchronization is group-based. When you configure group-based scoped synchronization, only the user accounts that belong to the groups you specify are synchronized to the managed domain. Nested groups aren't synchronized, only the specific groups you select.

You can change the synchronization scope before or after you create the managed domain. The scope of synchronization is defined by a service principal with the application identifier 2565bd9d-da50-47d4-8b85-4c97f669dc36. To prevent scope loss, don't delete or change the service principal. If it is accidentally deleted, the synchronization scope can't be recovered.

Keep in mind the following caveats if you change the synchronization scope:

  • A full synchronization occurs.
  • Objects that are no longer required in the managed domain are deleted. New objects are created in the managed domain.

To learn more about the synchronization process, see Understand synchronization in Microsoft Entra Domain Services.

PowerShell script for scoped synchronization

To configure scoped synchronization using PowerShell, first save the following script to a file named Select-GroupsToSync.ps1.

This script configures Domain Services to synchronize selected groups from Microsoft Entra ID. All user accounts that are part of the specified groups are synchronized to the managed domain.

This script is used in the additional steps in this article.

param (
    [Parameter(Position = 0)]
    [String[]]$groupsToAdd
)

Connect-MgGraph -Scopes "Directory.Read.All","AppRoleAssignment.ReadWrite.All"
$sp = Get-MgServicePrincipal -Filter "AppId eq '2565bd9d-da50-47d4-8b85-4c97f669dc36'"
$role = $sp.AppRoles | where-object -FilterScript {$_.DisplayName -eq "User"}

Write-Output "`n****************************************************************************"

Write-Output "Total group-assignments need to be added: $($groupsToAdd.Count)"
$newGroupIds = New-Object 'System.Collections.Generic.HashSet[string]'
foreach ($groupName in $groupsToAdd)
{
    try
    {
        $group = Get-MgGroup -Filter "DisplayName eq '$groupName'"
        $newGroupIds.Add($group.Id)

        Write-Output "Group-Name: $groupName, Id: $($group.Id)"
    }
    catch
    {
        Write-Error "Failed to find group: $groupName. Exception: $($_.Exception)."
    }
}

Write-Output "****************************************************************************`n"
Write-Output "`n****************************************************************************"

$currentAssignments = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $sp.Id -All:$true
Write-Output "Total current group-assignments: $($currentAssignments.Count), SP-ObjectId: $($sp.Id)"

$currAssignedObjectIds = New-Object 'System.Collections.Generic.HashSet[string]'
foreach ($assignment in $currentAssignments)
{
    Write-Output "Assignment-ObjectId: $($assignment.PrincipalId)"

    if ($newGroupIds.Contains($assignment.PrincipalId) -eq $false)
    {
        Write-Output "This assignment is not needed anymore. Removing it! Assignment-ObjectId: $($assignment.PrincipalId)"
        Remove-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -AppRoleAssignmentId $assignment.Id
    }
    else
    {
        $currAssignedObjectIds.Add($assignment.PrincipalId)
    }
}

Write-Output "****************************************************************************`n"
Write-Output "`n****************************************************************************"

foreach ($id in $newGroupIds)
{
    try
    {
        if ($currAssignedObjectIds.Contains($id) -eq $false)
        {
            Write-Output "Adding new group-assignment. Role-Id: $($role.Id), Group-Object-Id: $id, ResourceId: $($sp.Id)"
            $appRoleAssignment = @{
                "principalId"= $group.Id
                "resourceId"= $sp.Id
                "appRoleId"= $role.Id
            }
            New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -BodyParameter $appRoleAssignment 
        }
        else
        {
            Write-Output "Group-ObjectId: $id is already assigned."
        }
    }
    catch
    {
        Write-Error "Exception occurred assigning Object-ID: $id. Exception: $($_.Exception)."
    }
}

Write-Output "****************************************************************************`n"

Enable scoped synchronization

To enable group-based scoped synchronization for a managed domain, complete the following steps:

  1. First set "filteredSync" = "Enabled" on the Domain Services resource, then update the managed domain. When prompted, specify the credentials for a Global Administrator to sign in to your Microsoft Entra tenant using the Connect-MgGraph cmdlet:

    # Connect to your Entra ID tenant
Connect-MgGraph -Scopes "Application.ReadWrite.All","Group.ReadWrite.All"

# Retrieve the Microsoft Entra DS resource.
$DomainServicesResource = Get-AzResource -ResourceType "Microsoft.AAD/DomainServices"

# Enable group-based scoped synchronization.
$enableScopedSync = @{"filteredSync" = "Enabled"}

# Update the Microsoft Entra DS resource
Set-AzResource -Id $DomainServicesResource.ResourceId -Properties $enableScopedSync

  2. Now specify the list of groups whose users should be synchronized to the managed domain.

    Run the Select-GroupsToSync.ps1 script and specify the list of groups to sync. In the following example, the groups to synchronize are GroupName1 and GroupName2.

    [!WARNING] You must include the AAD DC Administrators group in the list of groups for scoped synchronization. If you don't include this group, the managed domain is unusable.

    .\Select-GroupsToSync.ps1 -groupsToAdd @("AAD DC Administrators", "GroupName1", "GroupName2")

Changing the scope of synchronization causes the managed domain to resynchronize all data. Objects that are no longer required in the managed domain are deleted, and resynchronization may take a long time to complete.

Modify scoped synchronization

To modify the list of groups whose users should be synchronized to the managed domain, run Select-GroupsToSync.ps1 script and specify the new list of groups to sync.

In the following example, the groups to synchronize no longer includes GroupName2, and now includes GroupName3.

Warning

You must include the AAD DC Administrators group in the list of groups for scoped synchronization. If you don't include this group, the managed domain is unusable.

When prompted, specify the credentials for a Global Administrator to sign in to your Microsoft Entra tenant using the Connect-MgGraph cmdlet:

.\Select-GroupsToSync.ps1 -groupsToAdd @("AAD DC Administrators", "GroupName1", "GroupName3")

Changing the scope of synchronization causes the managed domain to resynchronize all data. Objects that are no longer required in the managed domain are deleted, and resynchronization may take a long time to complete.

Disable scoped synchronization

To disable group-based scoped synchronization for a managed domain, set "filteredSync" = "Disabled" on the Domain Services resource, then update the managed domain. When complete, all users and groups are set to synchronize from Microsoft Entra ID.

When prompted, specify the credentials for a Global Administrator to sign in to your Microsoft Entra tenant using the Connect-MgGraph cmdlet:

# Connect to your Entra ID tenant
Connect-MgGraph -Scopes "Application.ReadWrite.All","Group.ReadWrite.All"

# Retrieve the Microsoft Entra DS resource.
$DomainServicesResource = Get-AzResource -ResourceType "Microsoft.AAD/DomainServices"

# Disable group-based scoped synchronization.
$disableScopedSync = @{"filteredSync" = "Disabled"}

# Update the Microsoft Entra DS resource
Set-AzResource -Id $DomainServicesResource.ResourceId -Properties $disableScopedSync

Changing the scope of synchronization causes the managed domain to resynchronize all data. Objects that are no longer required in the managed domain are deleted, and resynchronization may take a long time to complete.

Next steps

To learn more about the synchronization process, see Understand synchronization in Microsoft Entra Domain Services.