Microsoft Graph PowerShell を使用して、Microsoft Entra ID から Microsoft Entra Domain Services への範囲指定された同期を構成する

[アーティクル]
10/14/2024

Microsoft Entra Domain Services は、認証サービスを提供するために Microsoft Entra ID からユーザーとグループを同期します。ハイブリッド環境では、最初にオンプレミスの Active Directory Domain Services (AD DS) 環境のユーザーとグループが Microsoft Entra Connect を使用して Microsoft Entra ID に同期された後、Domain Services に同期されます。

既定では、Microsoft Entra ディレクトリのすべてのユーザーとグループが Domain Services マネージドドメインに同期されます。特定のニーズがある場合は、代わりに、定義したユーザーセットのみを同期することを選択できます。

この記事では、範囲指定された同期を使用するマネージドドメインを作成した後、MS Graph PowerShell を使用して、範囲指定されたユーザーセットを変更したり、無効にしたりする方法について説明します。 Microsoft Entra 管理センターを使用して、これらの手順を完了することもできます。

開始する前に

この記事を完了するには、以下のリソースと特権が必要です。

有効な Azure サブスクリプション
- Azure サブスクリプションをお持ちでない場合は、アカウントを作成してください。
ご利用のサブスクリプションに関連付けられた Microsoft Entra テナント (オンプレミスディレクトリまたはクラウド専用ディレクトリと同期されていること)。
- 必要に応じて、Microsoft Entra テナントを作成するか、ご利用のアカウントに Azure サブスクリプションを関連付けます。
Microsoft Entra テナントで有効にされていて、構成されている Microsoft Entra Domain Services マネージドドメイン。
- 必要に応じて、Microsoft Entra Domain Services マネージドドメインを作成して構成するチュートリアルを完了します。
Domain Services の同期スコープを変更するには、テナントでアプリケーション管理者とグループ管理者の Microsoft Entra ロールが必要です。

範囲指定された同期の概要

既定では、Microsoft Entra ディレクトリのすべてのユーザーとグループがマネージドドメインに同期されます。マネージドドメインにアクセスする必要のあるユーザーが少数しかいない場合は、それらのユーザーアカウントのみを同期することができます。この範囲指定された同期はグループベースです。グループベースの範囲指定された同期を構成した場合、指定したグループに属するユーザーアカウントのみがマネージドドメインに同期されます。入れ子になったグループは同期されません。選択した特定のグループのみが同期されます。

同期スコープは、マネージドドメインを作成する前または後に変更できます。同期のスコープは、アプリケーション識別子 2565bd9d-da50-47d4-8b85-4c97f669dc36 を使用してサービスプリンシパルによって定義されます。スコープが失われないようにするには、サービスプリンシパルを削除または変更しないでください。誤って削除された場合、同期スコープを復旧できません。

同期スコープを変更する場合は、次の点にご注意ください。

完全同期が行われます。
マネージドドメインで不要になったオブジェクトは削除されます。新しいオブジェクトは、マネージドドメインに作成されます。

同期プロセスの詳細については、Microsoft Entra Domain Services での同期の理解に関する記事を参照してください。

範囲指定された同期に関する PowerShell スクリプト

範囲指定された同期を PowerShell を使用して構成するには、まず、次のスクリプトを Select-GroupsToSync.ps1 という名前のファイルに保存します。

このスクリプトでは、Microsoft Entra ID から選択されたグループを同期するように Domain Services を構成します。指定されたグループに属しているユーザーアカウントはすべて、マネージドドメインに同期されます。

このスクリプトは、この記事の追加の手順で使用します。

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"

範囲指定された同期を有効にする

マネージドドメインのグループベースの範囲指定された同期を有効にするには、次の手順を実行します。

最初に Domain Services リソースに "filteredSync" = "Enabled" を設定してから、マネージドドメインを更新します。

この機能を管理するには、全体管理者が必要です。

Connect-MgGraph コマンドレットを使って Microsoft Entra テナントにサインインします。

# 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

次に、マネージドドメインにユーザーを同期するグループの一覧を指定します。

Select-GroupsToSync.ps1 スクリプトを実行し、同期するグループの一覧を指定します。次の例で、同期するグループは GroupName1 と GroupName2 です。

警告

範囲指定された同期用のグループの一覧には、AAD DC Administrators グループを含める必要があります。このグループを含めないと、マネージドドメインは使用できません。
```
.\Select-GroupsToSync.ps1 -groupsToAdd @("AAD DC Administrators", "GroupName1", "GroupName2")
```

同期のスコープを変更すると、マネージドドメインですべてのデータが再同期されます。マネージドドメインで不要になったオブジェクトは削除されます。また、再同期が完了するまでには時間がかかる場合があります。

範囲指定された同期を変更する

マネージドドメインにユーザーを同期するグループの一覧を変更するには、Select-GroupsToSync.ps1 スクリプトを実行し、同期する新しいグループの一覧を指定します。

次の例では、同期対象のグループに GroupName2 が含まれなくなり、GroupName3 が含まれるようになりました。

警告

範囲指定された同期用のグループの一覧には、AAD DC Administrators グループを含める必要があります。このグループを含めないと、マネージドドメインは使用できません。

この機能を管理するには、全体管理者が必要です。

Connect-MgGraph コマンドレットを使って Microsoft Entra テナントにサインインします。

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

範囲指定された同期を無効にする

マネージドドメインのグループベースの範囲指定された同期を無効にするには、Domain Services リソース上で "filteredSync" = "Disabled" を設定してから、マネージドドメインを更新します。完了すると、すべてのユーザーとグループが Microsoft Entra ID から同期されるように設定されます。

この機能を管理するには、全体管理者が必要です。

Connect-MgGraph コマンドレットを使って Microsoft Entra テナントにサインインします。

# 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

次のステップ

同期プロセスの詳細については、Microsoft Entra Domain Services での同期の理解に関する記事を参照してください。

次の方法で共有

Microsoft Graph PowerShell を使用して、Microsoft Entra ID から Microsoft Entra Domain Services への範囲指定された同期を構成する

開始する前に

範囲指定された同期の概要

範囲指定された同期に関する PowerShell スクリプト

範囲指定された同期を有効にする

範囲指定された同期を変更する

範囲指定された同期を無効にする

次のステップ

フィードバック

その他のリソース