Condividi tramite

Configurare la sincronizzazione con ambito da Microsoft Entra ID a Microsoft Entra Domain Services tramite Microsoft Graph PowerShell

  • Articolo

Per fornire servizi di autenticazione, Microsoft Entra Domain Services sincronizza utenti e gruppi da Microsoft Entra ID. In un ambiente ibrido gli utenti e i gruppi di un ambiente Active Directory Domain Services (AD DS) locale possono essere prima sincronizzati con Microsoft Entra ID tramite Microsoft Entra Connect e quindi sincronizzati con Domain Services.

Per impostazione predefinita, tutti gli utenti e i gruppi di una directory Microsoft Entra vengono sincronizzati con un dominio gestito di Domain Services. Se si hanno esigenze specifiche, è invece possibile scegliere di sincronizzare solo un set definito di utenti.

Questo articolo illustra come creare un dominio gestito che usa la sincronizzazione con ambito e quindi modificare o disabilitare il set di utenti con ambito usando MS Graph PowerShell. È anche possibile completare questi passaggi usando l'Interfaccia di amministrazione di Microsoft Entra.

Operazioni preliminari

Per completare le procedure descritte in questo articolo, sono necessari i privilegi e le risorse seguenti:

Panoramica della sincronizzazione con ambito

Per impostazione predefinita, tutti gli utenti e i gruppi di una directory Microsoft Entra vengono sincronizzati con un dominio gestito. Se solo pochi utenti devono accedere al dominio gestito, è possibile sincronizzare solo gli account utente. Questa sincronizzazione con ambito è basata su gruppi. Quando si configura la sincronizzazione con ambito basato su gruppo, solo gli account utente che appartengono ai gruppi specificati vengono sincronizzati con il dominio gestito. Vengono sincronizzati solo i gruppi specifici selezionati, non i gruppi annidati.

È possibile modificare l'ambito di sincronizzazione prima o dopo la creazione del dominio gestito. L'ambito della sincronizzazione è definito da un'entità servizio con l'identificatore dell'applicazione 2565bd9d-da50-47d4-8b85-4c97f669dc36. Per evitare la perdita di ambito, non eliminare o modificare l'entità servizio. Se viene eliminato accidentalmente, l'ambito di sincronizzazione non può essere recuperato.

Tenere presente quanto segue se si modifica l'ambito di sincronizzazione:

  • Viene eseguita una sincronizzazione completa.
  • Gli oggetti non più necessari nel dominio gestito vengono eliminati. Vengono creati nuovi oggetti nel dominio gestito.

Per altre informazioni sul processo di sincronizzazione, vedere Informazioni sulla sincronizzazione in Microsoft Entra Domain Services.

Script di PowerShell per la sincronizzazione con ambito

Per configurare la sincronizzazione con ambito tramite PowerShell, salvare prima lo script seguente in un file denominato Select-GroupsToSync.ps1.

Questo script configura Domain Services per sincronizzare i gruppi selezionati da Microsoft Entra ID. Tutti gli account utente che fanno parte dei gruppi specificati vengono sincronizzati con il dominio gestito.

Questo script viene usato nei passaggi aggiuntivi di questo articolo.

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"

Abilitare sincronizzazione con ambito

Per abilitare la sincronizzazione con ambito gruppo per un dominio gestito, completare la procedura seguente:

  1. Impostare prima "filteredSync" = "Enabled" nella risorsa Domain Services, quindi aggiornare il dominio gestito.

    Per gestire questa funzionalità è necessario un amministratore globale.

    Accedere al tenant di Microsoft Entra usando il 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. Ora specificare l'elenco dei gruppi i cui utenti devono essere sincronizzati nel dominio gestito.

    Eseguire lo script Select-GroupsToSync.ps1 e specificare l'elenco di gruppi da sincronizzare. Nell'esempio seguente i gruppi da sincronizzare sono GroupName1 e GroupName2.

    Avviso

    È necessario includere il gruppo AAD DC Administrators nell'elenco dei gruppi per la sincronizzazione con ambito. Se non si include questo gruppo, il dominio gestito non è utilizzabile.

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

La modifica dell'ambito della sincronizzazione fa sì che il dominio gestito risincronizzi tutti i dati. Gli oggetti non più necessari nel dominio gestito vengono eliminati e la risincronizzazione potrebbe richiedere molto tempo.

Modificare sincronizzazione con ambito

Per modificare l'elenco di gruppi i cui utenti devono essere sincronizzati nel dominio gestito, eseguire lo script Select-GroupsToSync.ps1 e specificare il nuovo elenco di gruppi da sincronizzare.

Nell'esempio seguente i gruppi da sincronizzare non includono più GroupName2 e ora includono GroupName3.

Avviso

È necessario includere il gruppo AAD DC Administrators nell'elenco dei gruppi per la sincronizzazione con ambito. Se non si include questo gruppo, il dominio gestito non è utilizzabile.

Per gestire questa funzionalità è necessario un amministratore globale.

Accedere al tenant di Microsoft Entra usando il cmdlet Connect-MgGraph.

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

La modifica dell'ambito della sincronizzazione fa sì che il dominio gestito risincronizzi tutti i dati. Gli oggetti non più necessari nel dominio gestito vengono eliminati e la risincronizzazione potrebbe richiedere molto tempo.

Disabilitare la sincronizzazione con ambito

Per disabilitare la sincronizzazione con ambito basato su gruppo per un dominio gestito, impostare "filteredSync" = "Disabled" nella risorsa Domain Services, quindi aggiornare il dominio gestito. Al termine tutti gli utenti e i gruppi vengono impostati per la sincronizzazione da Microsoft Entra ID.

Per gestire questa funzionalità è necessario un amministratore globale.

Accedere al tenant di Microsoft Entra usando il 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

La modifica dell'ambito della sincronizzazione fa sì che il dominio gestito risincronizzi tutti i dati. Gli oggetti non più necessari nel dominio gestito vengono eliminati e la risincronizzazione potrebbe richiedere molto tempo.

Passaggi successivi

Per altre informazioni sul processo di sincronizzazione, vedere Informazioni sulla sincronizzazione in Microsoft Entra Domain Services.