Partilhar via

Configurar a sincronização com âmbito definido da Identidade do Microsoft Entra para os Serviços de Domínio do Microsoft Entra usando o Microsoft Graph PowerShell

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:

  • Uma subscrição ativa do Azure.
  • Um tenant do Microsoft Entra associado à sua subscrição, sincronizado com um diretório no local ou um diretório apenas na nuvem.
  • Um domínio gerido dos Microsoft Entra Domain Services ativado e configurado no seu locatário do Microsoft Entra.
  • Você precisa das funções do Administrador de Aplicativos e do Administrador de Grupos do Microsoft Entra no seu inquilino para alterar o escopo de sincronização dos Serviços de Domínio.

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 são sincronizados os grupos que você selecionar.

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 o principal 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 delimitada

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"= $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 delimitada

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.

    Inicie sessão no tenant 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 AAD DC Administrators na lista de grupos para sincronização por 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 de âmbito

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 AAD DC Administrators na lista de grupos para sincronização por escopo. Se você não incluir esse grupo, o domínio gerenciado ficará inutilizável.

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

Inicie sessão no tenant 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 delimitação

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 utilizadores e grupos estão configurados para sincronizar a partir do Microsoft Entra ID.

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

Inicie sessão no tenant 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.

  • Last updated on