Manage Administrative Unit with the Microsoft Graph PowerShell SDK

Administrative Unit

An administrative unit is a Microsoft Entra resource that can be a container for other Microsoft Entra resources. An administrative unit can contain only users, groups, or devices.

Administrative units restrict permissions in a role to any portion of your organization that you define.

An administrative unit provides a conceptual container for user, group, and device directory objects. Using administrative units, a company administrator can now delegate administrative responsibilities to manage the users, groups, and devices contained within or scoped to an administrative unit to a regional or departmental administrator. This resource is an open type that allows other properties to be passed in.

I will demonstrate the management of an administrative unit by using the Microsoft Graph PowerShell SDK.

In my developer tenant I will create the Marketing Department administrative unit and add two users: Alex Wilber and Megan Bowen.

User administrator of this administrative unit will be Adele Vance, who is not a member of the Marketing Department administrative unit.

Create administrative unit

To create a new administrative unit, connect with the scope AdministrativeUnit.ReadWrite.All and New-MgDirectoryAdministrativeUnit cmdlet.

Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All"
Import-Module Microsoft.Graph.Identity.DirectoryManagement

$params = @{
	displayName = "Marketing Department"
	description = "Marketing Department Administration"
	visibility = "HiddenMembership"

New-MgDirectoryAdministrativeUnit -BodyParameter $params

The visibility is set to HiddenMembership which means that only members of the administrative unit can list other members of the administrative unit.

Add member

To add a new member, use New-MgDirectoryAdministrativeUnitMemberByRef cmdlet.

Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All"
Import-Module Microsoft.Graph.Identity.DirectoryManagement

$administrativeUnitId = "0a22c83d-c4ac-43e2-bb5e-87af3015d49f"
$alexWilberUserId = "52f26d18-d151-434f-ae14-a4a83122b2b2"
$meganBowenUserId = "b848d7dc-7161-4628-b308-5cca9c9fe784"

$paramsUser1 = @{
	"" = "$alexWilberUserId"

New-MgDirectoryAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -BodyParameter $paramsUser1

$paramsUser2 = @{
	"" = "$meganBowenUserId"

New-MgDirectoryAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -BodyParameter $paramsUser2

Get members

To read members of the administrative unit, call Get-MgDirectoryAdministrativeUnitMemberAsUser cmdlet. Because the administrative unit is hidden, you need the Member.Read.Hidden permission. The Directory.Read.All permission is required to be able to read basic users properties like name or displayName.

Connect-MgGraph -Scopes "AdministrativeUnit.Read.All", "Member.Read.Hidden", "Directory.Read.All"
Import-Module Microsoft.Graph.Identity.DirectoryManagement

$administrativeUnitId = "0a22c83d-c4ac-43e2-bb5e-87af3015d49f"

Get-MgDirectoryAdministrativeUnitMemberAsUser -AdministrativeUnitId $administrativeUnitId

Assign role

To assign the User Administrator role, we need to know its id. You can use the Get-MgDirectoryRole cmdlet to find the correct role id.

The New-MgDirectoryAdministrativeUnitScopedRoleMember requires the RoleManagement.ReadWrite.Directory scope.

Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory"
Import-Module Microsoft.Graph.Identity.DirectoryManagement

$administrativeUnitId = "0a22c83d-c4ac-43e2-bb5e-87af3015d49f"
$adeleVanceId = "61b0c52f-a902-4769-9a09-c6628335b00a"
$userAdministratorRoleId = "947ccf23-ee27-4951-8110-96c62c680311"
$params = @{
	roleId = $userAdministratorRoleId
	roleMemberInfo = @{
		id = $adeleVanceId

New-MgDirectoryAdministrativeUnitScopedRoleMember -AdministrativeUnitId $administrativeUnitId -BodyParameter $params

Checking the result

Let's check the result and login in the Entra admin center as Adele Vance. Find the user Alex Wilber, she can edit his properties, because Wilber is the member of the Marketing Department administrative unit and Adele is the User Administrator of this unit.

But Adele cannot edit properties of users who are not members of the Marketing Department administrative unit.

Buy Me a Coffee at
An error has occurred. This application may no longer respond until reloaded. Reload x