Administrative units with restricted management
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.
Restricted management administrative units allow you to protect specific users, groups, or devices in your tenant from modification by anyone other than a specific set of people that you designate. This allows you to meet security or compliance requirements without having to remove tenant-level role assignments from your administrators.
What exactly is blocked?
Administrators not explicitly assigned at the restricted management administrative unit scope can't
- modify any Microsoft Entra properties of the user, group, or device
- delete the user, group, or device
- update a password for a user.
Create administrative unit with restricted management
When you create an administrative unit via the Microsoft Graph API, you can set the isMemberManagementRestricted property to true. This will enable restricted management for the administrative unit.
POST https://graph.microsoft.com/v1.0/directory/administrativeUnits
{
"displayName": "Company management",
"description": "Administrative unit with restricted management for company management",
"isMemberManagementRestricted": true
}
Add user to administrative unit
To add a user to the restricted management administrative unit, you can use the following API call.
POST https://graph.microsoft.com/v1.0/directory/administrativeUnits/{id}/members/$ref
{
"@odata.id":"https://graph.microsoft.com/v1.0/users/{user_id}"
}
Once the user is added to the administrative unit with restricted management, nobody (even global administrators) can edit the user properties.
If you try to update the user from restricted management administrative unit via the Microsoft Graph API:
PATCH https://graph.microsoft.com/v1.0/users/{user_id}
{
"displayName": "John Doe"
}
You will get the error message
Target object is a member of a restricted management administrative unit and can only be modified by administrators scoped to that administrative unit. Check that you are assigned a role that has permission to perform the operation for this restricted management administrative unit.
Create a role assignment scoped to the administrative unit
POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
{
"roleDefinitionId": "{role_definition_id}",
"directoryScopeId": "/administrativeUnits/{administrative_unit_id}",
"principalId": "{user_id}"
}
Filter users with restricted management
The user resource contains a property isManagementRestricted that indicates whether the user is managed by an administrative unit with restricted management.
Unfortunately, the isManagementRestricted property is not indexed, so the following query
GET https://graph.microsoft.com/v1.0/users?$filter=isManagementRestricted eq true&$select=id,displayName,userPrincipalName,isManagementRestricted&$count=true
ConsistencyLevel: eventual
will fail with the error message The request uses a filter property that is not indexed.
You will have to return all users and filter them on the client side:
GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,userPrincipalName,isManagementRestricted
Edge cases
If a user is soft-deleted and then restored, he will became a member of administrative unit automatically, so restriction is applied.
If an administrative unit is soft-deleted then the restriction is removed from a user and user's properties can be edited in a standard way. When the administrative unit is restored the user will become the member again and the restriction is applied automatically.
