Configurar a sincronização com escopo do Microsoft Entra ID para o Microsoft Entra Domain Services usando o PowerShell do Microsoft Graph

Artigo
03/18/2024

Para fornecer serviços de autenticação, o Microsoft Entra Domain Services sincroniza usuários e grupos do Microsoft Entra ID. Em um ambiente híbrido, os usuários e grupos de um ambiente do Active Directory Domain Services (AD DS) local podem ser sincronizados primeiro com o Microsoft Entra ID usando o Microsoft Entra Connect e, em seguida, sincronizados com o Domain Services.

Por padrão, todos os usuários e grupos no diretório do Microsoft Entra são sincronizados com um domínio gerenciado pelo Domain Services. Se você tiver necessidades específicas, poderá optar por sincronizar apenas um conjunto definido de usuários.

Este artigo mostra como criar um domínio gerenciado que usa a sincronização com escopo e, em seguida, alterar ou desabilitar o conjunto de usuários com escopo usando o MS Graph PowerShell. Você também pode completar essas etapas utilizando o centro de administração do Microsoft Entra.

Antes de começar

Para concluir este artigo, você precisará dos seguintes recursos e privilégios:

Uma assinatura ativa do Azure.
- Caso não tenha uma assinatura do Azure, crie uma conta.
Um locatário do Microsoft Entra associado com a assinatura, sincronizado com um diretório local ou somente em nuvem.
- Se necessário, crie um locatário do Microsoft Entra ou associe uma assinatura do Azure à sua conta.
Um domínio gerenciado do Microsoft Entra Domain Services habilitado e configurado em seu locatário do Microsoft Entra.
- Se necessário, conclua o tutorial Criar e configurar um domínio gerenciado do Microsoft Entra Domain Services.
Você precisa das funções de Administrador de aplicativos e Administrador de grupos do Microsoft Entra em seu locatário para alterar o escopo de sincronização do Domain Services.

Visão geral da sincronização com escopo

Por padrão, todos os usuários e grupos no diretório do Microsoft Entra são sincronizados com um domínio gerenciado. Se apenas alguns usuários precisarem acessar o domínio gerenciado, você pode sincronizar apenas essas contas de usuário. Essa sincronização no escopo é baseada em grupo. Quando você configura a sincronização com escopo baseada em grupo, somente as contas de usuário que pertencem aos grupos especificados são sincronizadas com o domínio gerenciado. Grupos aninhados não são sincronizados, somente os grupos específicos selecionados.

Você pode alterar o escopo de sincronização antes ou depois de criar o domínio gerenciado. O escopo da sincronização é definido por uma entidade de serviço com o identificador de aplicativo 2565bd9d-da50-47d4-8b85-4c97f669dc36. Para evitar a perda de escopo, não exclua nem altere a entidade de serviço. Se for excluído acidentalmente, o escopo de sincronização não poderá ser recuperado.

Tenha em mente as seguintes advertências se você alterar o escopo de sincronização:

É executado um ciclo de sincronização completo.
Os objetos que não forem mais necessários no domínio gerenciado serão excluídos. Novos objetos são criados no domínio gerenciado.

Para saber mais sobre o processo de sincronização, confira Entender a sincronização no Microsoft Entra Domain Services.

Script do PowerShell para sincronização com escopo

Para configurar a sincronização com escopo usando o PowerShell, primeiro salve o script a seguir em um arquivo chamado Select-GroupsToSync.ps1.

Esse script configura o Domain Services para sincronizar grupos selecionados do Microsoft Entra ID. Todas as contas de usuário que fazem parte dos grupos especificados são sincronizadas com o domínio gerenciado.

Esse script é usado nas etapas adicionais neste artigo.

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 $true)
    {
        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"

Habilitar sincronização com escopo

Conclua as seguintes etapas para habilitar a sincronização de escopo com base em grupo para um domínio gerenciado:

Primeiro, defina "filteredSync" = "Enabled" no recurso do Domain Services e, em seguida, atualize o domínio gerenciado. Quando solicitado, especifique as credenciais de um Administrador Global entrar no locatário do Microsoft Entra usando o cmdlet Connect-MgGraph:

# 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

Agora, especifique a lista de grupos cujos usuários deverão ser sincronizados para o domínio gerenciado.

Execute o script Select-GroupsToSync.ps1 e especifique a lista de grupos a sincronizar. No exemplo a seguir, os grupos a sincronizar são Select-GroupsToSync.ps1 e GroupName2.

Aviso

Você deve incluir o grupo Administradores do AAD DC na lista de grupos para sincronização com escopo. Se você não incluir esse grupo, o domínio gerenciado não poderá ser usado.
```
.\Select-GroupsToSync.ps1 -groupsToAdd @("AAD DC Administrators", "GroupName1", "GroupName2")
```

Alterar o escopo da sincronização faz com que o domínio gerenciado sincronize novamente todos os dados. Os objetos que não são mais necessários no domínio gerenciado são excluídos e a ressincronização pode levar algum tempo para ser concluída.

Modificar sincronização com escopo

Para modificar a lista de grupos cujos usuários devem ser sincronizados para o domínio gerenciado, execute o script Select-GroupsToSync.ps1e especifique a nova lista de grupos a sincronizar.

No exemplo a seguir, os grupos a sincronizar não incluem mais GroupName2 e agora incluem GroupName3.

Aviso

Você deve incluir o grupo Administradores do AAD DC na lista de grupos para sincronização com escopo. Se você não incluir esse grupo, o domínio gerenciado não poderá ser usado.

Quando solicitado, especifique as credenciais de um Administrador Global entrar no locatário do Microsoft Entra usando o cmdlet Connect-MgGraph:

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

Desabilitar sincronização com escopo

Para desabilitar a sincronização com escopo baseado em grupo para um domínio gerenciado, defina "filteredSync" = "Disabled" no recurso do Domain Services e, em seguida, atualize o domínio gerenciado. Ao concluir, todos os usuários e grupos serão definidos para sincronizar a partir do Microsoft Entra ID.