Partilhar via

Configurar a sincronização de escopo do ID do Microsoft Entra para os Serviços de Domínio do Microsoft Entra usando o Microsoft Graph PowerShell

  • Artigo

Para fornecer serviços de autenticação, os Serviços de Domínio do Microsoft Entra sincronizam usuários e grupos a partir da ID do Microsoft Entra. Em um ambiente híbrido, os usuários e grupos de um ambiente local dos Serviços de Domínio Ative Directory (AD DS) podem ser primeiro sincronizados com o ID do Microsoft Entra usando o Microsoft Entra Connect e, em seguida, sincronizados com os Serviços de Domínio.

Por padrão, todos os usuários e grupos de um diretório do Microsoft Entra são sincronizados com um domínio gerenciado pelos Serviços de Domínio. 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 concluir essas etapas usando o centro de administração do Microsoft Entra.

Antes de começar

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

Visão geral da sincronização com escopo

Por padrão, todos os usuários e grupos de um 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ê poderá sincronizar apenas essas contas de usuário. Essa sincronização com escopo é baseada em grupo. Quando você configura a sincronização de escopo baseada em grupo, somente as contas de usuário que pertencem aos grupos especificados são sincronizadas com o domínio gerenciado. Os grupos aninhados não são sincronizados, apenas 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 ele for excluído acidentalmente, o escopo da sincronização não poderá ser recuperado.

Lembre-se das seguintes advertências se você alterar o escopo da sincronização:

  • Ocorre uma sincronização completa.
  • Os objetos que não são mais necessários no domínio gerenciado são excluídos. Novos objetos são criados no domínio gerenciado.

Para saber mais sobre o processo de sincronização, consulte Compreender a sincronização nos Serviços de Domínio do Microsoft Entra.

Script do PowerShell para sincronização com escopo

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

Este script configura os Serviços de Domínio para sincronizar grupos selecionados a partir 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 deste 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 $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"

Habilitar a sincronização com escopo

Para habilitar a sincronização de escopo baseada em grupo para um domínio gerenciado, conclua as seguintes etapas:

  1. Primeiro, defina "filteredSync" = "Enabled" no recurso Serviços de Domínio e, em seguida, atualize o domínio gerenciado.

    É necessário um Administrador Global para gerir esta funcionalidade.

    Entre 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

  2. Agora especifique a lista de grupos cujos usuários devem ser sincronizados com o domínio gerenciado.

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

    Aviso

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

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

Alterar o escopo da sincronização faz com que o domínio gerenciado ressincronize 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 muito tempo para ser concluída.

Modificar a sincronização com escopo

Para modificar a lista de grupos cujos usuários devem ser sincronizados com o domínio gerenciado, execute Select-GroupsToSync.ps1 o script e especifique a nova lista de grupos a serem sincronizados.

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

Aviso

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

É necessário um Administrador Global para gerir esta funcionalidade.

Entre no locatário do Microsoft Entra usando o cmdlet Connect-MgGraph .

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

Alterar o escopo da sincronização faz com que o domínio gerenciado ressincronize 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 muito tempo para ser concluída.

Desativar a sincronização com escopo

Para desativar a sincronização de escopo baseada em grupo para um domínio gerenciado, defina "filteredSync" = "Disabled" no recurso Serviços de Domínio e atualize o domínio gerenciado. Quando concluído, todos os usuários e grupos são definidos para sincronizar a partir do Microsoft Entra ID.

É necessário um Administrador Global para gerir esta funcionalidade.

Entre 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"

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

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

Alterar o escopo da sincronização faz com que o domínio gerenciado ressincronize 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 muito tempo para ser concluída.

Próximos passos

Para saber mais sobre o processo de sincronização, consulte Compreender a sincronização nos Serviços de Domínio do Microsoft Entra.