title | description | author | manager | ms.service | ms.topic | ms.subservice | ms.date | ms.author | ms.reviewer | ms.custom |
---|---|---|---|---|---|---|---|---|---|---|
Create or delete administrative units |
Create administrative units to restrict the scope of role permissions in Microsoft Entra ID. |
rolyon |
amycolannino |
entra-id |
how-to |
role-based-access-control |
06/09/2023 |
rolyon |
anandy |
oldportal, it-pro, has-azure-ad-ps-ref |
Important
Restricted management administrative units are currently in PREVIEW. See the Product Terms for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
Administrative units let you subdivide your organization into any unit that you want, and then assign specific administrators that can manage only the members of that unit. For example, you could use administrative units to delegate permissions to administrators of each school at a large university, so they could control access, manage users, and set policies only in the School of Engineering.
This article describes how to create or delete administrative units to restrict the scope of role permissions in Microsoft Entra ID.
- Microsoft Entra ID P1 or P2 license for each administrative unit administrator
- Microsoft Entra ID Free licenses for administrative unit members
- Privileged Role Administrator role
- Microsoft.Graph module when using Microsoft Graph PowerShell
- Azure AD PowerShell module when using PowerShell
- AzureADPreview module when using PowerShell and restricted management administrative units
- Admin consent when using Graph Explorer for Microsoft Graph API
For more information, see Prerequisites to use PowerShell or Graph Explorer.
You can create a new administrative unit by using either the Microsoft Entra admin center, PowerShell or Microsoft Graph.
[!INCLUDE portal updates]
-
Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.
-
Browse to Identity > Roles & admins > Admin units.
-
Select Add.
-
In the Name box, enter the name of the administrative unit. Optionally, add a description of the administrative unit.
-
If you don't want tenant-level administrators to be able to access this administrative unit, set the Restricted management administrative unit toggle to Yes. For more information, see Restricted management administrative units.
-
Optionally, on the Assign roles tab, select a role and then select the users to assign the role to with this administrative unit scope.
-
On the Review + create tab, review the administrative unit and any role assignments.
-
Select the Create button.
Use the Connect-MgGraph command to sign in to your tenant and consent to the required permissions.
Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All"
Use the New-MgDirectoryAdministrativeUnit command to create a new administrative unit.
$params = @{
DisplayName = "Seattle District Technical Schools"
Description = "Seattle district technical schools administration"
Visibility = "HiddenMembership"
}
$adminUnitObj = New-MgDirectoryAdministrativeUnit -BodyParameter $params
Use the New-MgBetaDirectoryAdministrativeUnit command to create a new restricted management administrative unit. Set the IsMemberManagementRestricted
property to $true
.
$params = @{
DisplayName = "Contoso Executive Division"
Description = "Contoso Executive Division administration"
Visibility = "HiddenMembership"
IsMemberManagementRestricted = $true
}
$restrictedAU = New-MgBetaDirectoryAdministrativeUnit -BodyParameter $params
[!INCLUDE Azure AD PowerShell deprecation note]
Use the New-AzureADMSAdministrativeUnit command to create a new administrative unit.
$adminUnitObj = New-AzureADMSAdministrativeUnit -Description "West Coast region" -DisplayName "West Coast"
Use the New-AzureADMSAdministrativeUnit (preview) command to create a new restricted management administrative unit. Set the IsMemberManagementRestricted
parameter to $true
.
$restrictedAU = New-AzureADMSAdministrativeUnit -DisplayName "Contoso Executive Division" -IsMemberManagementRestricted $true
Use the Create administrativeUnit API to create a new administrative unit.
Request
POST https://graph.microsoft.com/v1.0/directory/administrativeUnits
Body
{
"displayName": "North America Operations",
"description": "North America Operations administration"
}
Use the Create administrativeUnit (beta) API to create a new restricted management administrative unit. Set the isMemberManagementRestricted
property to true
.
Request
POST https://graph.microsoft.com/beta/administrativeUnits
Body
{
"displayName": "Contoso Executive Division",
"description": "This administrative unit contains executive accounts of Contoso Corp.",
"isMemberManagementRestricted": true
}
In Microsoft Entra ID, you can delete an administrative unit that you no longer need as a unit of scope for administrative roles. Before you delete the administrative unit, you should remove any role assignments with that administrative unit scope.
-
Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.
-
Browse to Identity > Roles & admins > Admin units.
-
Select the administrative unit you want to delete.
-
Select Roles and administrators, and then open a role to view the role assignments.
-
Remove all the role assignments with the administrative unit scope.
-
Browse to Identity > Roles & admins > Admin units.
-
Add a check mark next to the administrative unit you want to delete.
-
Select Delete.
-
To confirm that you want to delete the administrative unit, select Yes.
Use the Remove-MgDirectoryAdministrativeUnit command to delete an administrative unit.
$adminUnitObj = Get-MgDirectoryAdministrativeUnit -Filter "DisplayName eq 'Seattle District Technical Schools'"
Remove-MgDirectoryAdministrativeUnit -AdministrativeUnitId $adminUnitObj.Id
[!INCLUDE Azure AD PowerShell deprecation note]
Use the Remove-AzureADMSAdministrativeUnit command to delete an administrative unit.
$adminUnitObj = Get-AzureADMSAdministrativeUnit -Filter "DisplayName eq 'Seattle District Technical Schools'"
Remove-AzureADMSAdministrativeUnit -Id $adminUnitObj.Id
Use the Delete administrativeUnit API to delete an administrative unit.
DELETE https://graph.microsoft.com/v1.0/directory/administrativeUnits/{admin-unit-id}