Edit

Share via

Manage administrative units

Managing administrative units in Microsoft Entra ID lets IT admins delegate permissions more granularly in an organization. Administrative units are containers for users, groups, or devices, and help with role-based access control for specific organizational segments. For an overview of administrative units in Microsoft Entra ID, see Administrative units.

This article shows you how to use Microsoft Entra PowerShell to manage administrative units with scripts that form a complete demo. By following this guide, you learn how to:

  • Create administrative units
  • Assign roles to administrative units
  • Add members to administrative units
  • Update properties of administrative units
  • Clean up the resources

Prerequisites

Create administrative units

Create an administrative unit in Microsoft Entra ID by using the New-EntraAdministrativeUnit cmdlet. Administrative units let you delegate permissions for users, groups, and devices within a specific organizational segment.

To create an administrative unit, run:

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
New-EntraAdministrativeUnit -DisplayName 'Pacific Administrative Unit' -Description 'Administrative Unit for Pacific region'    

DeletedDateTime Id                                   Description                           DisplayName                IsMemberManagementRestricted Membersh
                                                                                                                                                   ipRule
--------------- --                                   -----------                           -----------                ---------------------------- --------
                bbbbbbbb-1111-2222-3333-cccccccccccc Administrative Unit for Pacific region Pacific Administrative Unit

Assign roles to administrative units

Scoped role membership in Microsoft Entra ID allows you to assign administrative roles to users with permissions limited to specific administrative units.

Assign scoped role membership to an administrative unit by using the Add-EntraScopedRoleMembership cmdlet. The following example shows how to add a user to a role in an administrative unit.

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$user = Get-EntraUser -UserId 'SawyerM@contoso.com'
$role = Get-EntraDirectoryRole -Filter "DisplayName eq 'Helpdesk Administrator'" 
$administrativeUnit = Get-EntraAdministrativeUnit -Filter "DisplayName eq 'Pacific Administrative Unit'"
$roleMember = New-Object -TypeName Microsoft.Open.MSGraph.Model.MsRoleMemberInfo
$roleMember.Id = $user.Id
Add-EntraScopedRoleMembership -AdministrativeUnitId $administrativeUnit.Id -RoleObjectId $role.Id -RoleMemberInfo $roleMember

Id                                         AdministrativeUnitId                 RoleId
--                                         --------------------                 ------
Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2   aaaaaaaa-bbbb-aaaa-bbbb-cccccccccccc bbbbbbbb-1111-2222-3333-cccccccccccc

Add members to administrative units

Add users, groups, or devices to an administrative unit with the Add-EntraAdministrativeUnitMember cmdlet. This cmdlet lets you specify the administrative unit and the member to add.

The following example shows how to add a user as an administrative unit member. Use Get-EntraAdministrativeUnit to find the administrative unit ID and Get-EntraUser to find the user ID. The MemberId parameter specifies the ID of the user, group, or device to add as a member of the administrative unit.

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
$administrativeUnit = Get-EntraAdministrativeUnit -Filter "DisplayName eq '<administrativeunit-display-name>'"
$user = Get-EntraUser -UserId 'SawyerM@contoso.com'
Add-EntraAdministrativeUnitMember -AdministrativeUnitId $administrativeUnit.Id -MemberId $user.Id

Update properties of administrative units

Update an existing administrative unit with the Set-EntraAdministrativeUnit cmdlet. Use this cmdlet to change properties like display name and description.

To update the display name of an administrative unit, run:

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
$administrativeUnit = Get-EntraAdministrativeUnit -Filter "DisplayName eq 'Pacific Administrative Unit'"
Set-EntraAdministrativeUnit -AdministrativeUnitId $administrativeUnit.Id -DisplayName 'Pacific Admin Unit' -Description 'Pacific Admin Unit Description' -MembershipType 'Assigned'

Clean up resources

To clean up resources, you can remove scoped role memberships, administrative unit members, and the administrative unit itself.

Remove scoped role memberships

When a scoped role is removed, the user's ability to manage resources within that administrative unit is revoked. This ensures that administrative control is tightly bound to administrative unit membership and reinforces the principle of least privilege.

Remove a scoped role membership from Microsoft Entra ID by running the Remove-EntraScopedRoleMembership cmdlet. Get the administrative unit ID with the Get-EntraAdministrativeUnit command. Get details of a scoped role membership for the ScopedRoleMembershipId parameter with the Get-EntraScopedRoleMembership command.

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$role = Get-EntraDirectoryRole -Filter "DisplayName eq 'Helpdesk Administrator'" 
$administrativeUnit = Get-EntraAdministrativeUnit -Filter "DisplayName eq 'Pacific Administrative Unit'"
$roleMembership = Get-EntraScopedRoleMembership -AdministrativeUnitId $administrativeUnit.Id | Where-Object {$_.RoleId -eq $role.Id}
Remove-EntraScopedRoleMembership -AdministrativeUnitId $administrativeUnit.Id -ScopedRoleMembershipId $roleMembership.Id

Remove administrative unit members

Remove an administrative unit member from Microsoft Entra ID by running the Remove-EntraAdministrativeUnitMember cmdlet.

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
$administrativeUnit = Get-EntraAdministrativeUnit -Filter "DisplayName eq 'Pacific Administrative Unit'"
$adminUnitMember = Get-EntraAdministrativeUnitMember -AdministrativeUnitId $administrativeUnit.Id | Select-Object Id, DisplayName,'@odata.type' | Where-Object {$_.DisplayName -eq 'Sawyer Miller'}
Remove-EntraAdministrativeUnitMember -AdministrativeUnitId $administrativeUnit.Id -MemberId $adminUnitMember.Id

Remove administrative units

Remove an administrative unit from Microsoft Entra ID by running the Remove-EntraAdministrativeUnit cmdlet.

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
$administrativeUnit = Get-EntraAdministrativeUnit -Filter "DisplayName eq '<administrative-unit-display-name>'"
Remove-EntraAdministrativeUnit -AdministrativeUnitId $administrativeUnit.Id
  • Last updated on