使用 Microsoft Graph PowerShell 配置从 Microsoft Entra ID 到 Microsoft Entra 域服务的区分范围的同步

项目
11/11/2024

为了提供身份验证服务，Microsoft Entra 域服务从 Microsoft Entra ID 同步用户和组。在混合环境中，本地 Active Directory 域服务 (AD DS) 环境中的用户和组可以先使用 Microsoft Entra Connect 同步到 Microsoft Entra ID，然后再同步到域服务。

默认情况下，Microsoft Entra 目录中的所有用户和组都同步到域服务托管域。如果有特定需求，可以改为选择只同步所定义的一组用户。

本文说明如何创建使用作用域同步的托管域，然后使用 MS Graph PowerShell 更改或禁用作用域用户的集合。还可以使用 Microsoft Entra 管理中心完成这些步骤。

准备阶段

需有以下资源和特权才能完成本文：

一个有效的 Azure 订阅。
- 如果你没有 Azure 订阅，请创建一个帐户。
与订阅关联的 Microsoft Entra 租户，可以与本地目录或仅限云的目录同步。
- 如果需要，请创建一个 Microsoft Entra 租户或将 Azure 订阅关联到你的帐户。
在 Microsoft Entra 租户中启用和配置的 Microsoft Entra 域服务托管域。
- 请根据需要完成创建并配置 Microsoft Entra 域服务托管域的教程。
需要租户中的应用程序管理员和组管理员 Microsoft Entra 角色才能更改域服务同步范围。

具有作用域的同步概述

默认情况下，Microsoft Entra 目录中的所有用户和组都会同步到托管域。如果只有几个用户需要访问托管域，则可以仅同步这些用户帐户。此具有作用域的同步基于组。配置基于组的具有作用域的同步时，只有属于指定组的用户帐户才会同步到托管域。不同步嵌套组，只同步所选的特定组。

可以在创建托管域之前或之后更改同步范围。同步范围由应用程序标识符为 2565bd9d-da50-47d4-8b85-4c97f669dc36 的服务主体定义。为了防止范围丢失，请不要删除或更改服务主体。如果意外删除了服务主体，则无法恢复同步范围。

如果更改同步范围，请记住以下注意事项：

进行完全同步。
托管域中不再需要的对象会被删除。托管域中会新建对象。

若要详细了解同步过程，请参阅了解 Microsoft Entra 域服务中的同步。

用于具有作用域的同步的 PowerShell 脚本

若要使用 PowerShell 配置具有作用域的同步，请首先将以下脚本保存到名为 Select-GroupsToSync.ps1 的文件中。

此脚本将域服务配置为从 Microsoft Entra ID 同步所选组。属于指定组的所有用户帐户都会同步到托管域。

此脚本将用于本文中的其他步骤。

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

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -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"

启用作用域同步

若要为托管域启用基于组的作用域同步，请完成以下步骤：

首先在域服务资源上设置 "filteredSync" = "Enabled"，然后更新托管域。

需要全局管理员来管理此功能。

使用 Connect-MgGraph cmdlet 登录到你的 Microsoft Entra 租户：

# Connect to your Entra ID tenant
Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -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

现在，指定其用户应同步到托管域的组的列表。

运行 Select-GroupsToSync.ps1 脚本并指定要同步的组的列表。在以下示例中，要同步的组为 GroupName1 和 GroupName2。

警告

必须在具有作用域的同步的组列表中包括“AAD DC 管理员”组。如果未包括此组，将无法使用托管域。
```
.\Select-GroupsToSync.ps1 -groupsToAdd @("AAD DC Administrators", "GroupName1", "GroupName2")
```

更改同步作用域会导致托管域重新同步所有数据。托管域中不再需要的对象会被删除，重新同步可能需要很长时间才能完成。

修改具有作用域的同步

若要修改包含应同步到托管域的用户的组列表，请运行 Select-GroupsToSync.ps1 脚本并指定要同步的新的组列表。

在下面的示例中，要同步的组不再包括 GroupName2，其现在包括 GroupName3。

警告

必须在具有作用域的同步的组列表中包括“AAD DC 管理员”组。如果未包括此组，将无法使用托管域。

需要全局管理员来管理此功能。

使用 Connect-MgGraph cmdlet 登录到你的 Microsoft Entra 租户。

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

更改同步作用域会导致托管域重新同步所有数据。托管域中不再需要的对象会被删除，重新同步可能需要很长时间才能完成。

禁用具有作用域的同步

若要为托管域禁用基于组的具有作用域的同步，请在域服务资源上设置 "filteredSync" = "Disabled"，然后更新托管域。完成后，所有用户和组都设置为从 Microsoft Entra ID 进行同步。

需要全局管理员来管理此功能。

使用 Connect-MgGraph cmdlet 登录到你的 Microsoft Entra 租户：

# Connect to your Entra ID tenant
Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -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

更改同步作用域会导致托管域重新同步所有数据。托管域中不再需要的对象会被删除，重新同步可能需要很长时间才能完成。

后续步骤

若要详细了解同步过程，请参阅了解 Microsoft Entra 域服务中的同步。

通过

使用 Microsoft Graph PowerShell 配置从 Microsoft Entra ID 到 Microsoft Entra 域服务的区分范围的同步

准备阶段

具有作用域的同步概述

用于具有作用域的同步的 PowerShell 脚本

启用作用域同步

修改具有作用域的同步

禁用具有作用域的同步

后续步骤

其他资源