Manage administrative unit
In previous blog, I described how to create an administrative unit, add a member to the administrative unit and assign a Microsoft Entra role to a user.
Role assignment
I've used the Graph PowerShell SDK cmdlet New-MgDirectoryAdministrativeUnitScopedRoleMember. The cmdlet internally calls the endpoint
POST /v1.0/directory/administrativeUnits/{id}/scopedRoleMembers
{
"roleId": "roleId",
"roleMemberInfo": {
"id": "userId"
}
}
In the body, you specify the id of the directory role. The list of directory roles can be retrieved from
GET /v1.0/directoryRoles
The response
{
"value": [
{
"id": "18cad318-5464-4f8a-801e-bdcf5b80d4d6",
"displayName": "Global Administrator"
},
{
"id": "238e51eb-2970-4096-a91a-1cb08e4c5420",
"displayName": "Groups Administrator"
},
{
"id": "5280e633-59bf-4018-b20b-25bc3829e469",
"displayName": "Helpdesk Administrator"
},
{
"id": "947ccf23-ee27-4951-8110-96c62c680311",
"displayName": "User Administrator"
},
{
"id": "94ab42b9-b8f0-4dfe-9da4-a458338ff359",
"displayName": "SharePoint Administrator"
},
{
"id": "9d681877-9c99-48fe-80e2-f0f72cc01eff",
"displayName": "License Administrator"
},
{
"id": "a44ede9f-2ee4-4488-a98a-4ef17367ac7d",
"displayName": "Exchange Administrator"
},
{
"id": "a7b41e0c-e9c8-4be7-9449-d8f3c4714fa1",
"displayName": "Authentication Administrator"
},
{
"id": "bcdd3e19-60a9-4b96-993c-5ffc21341fb1",
"displayName": "Directory Readers"
}
]
}
But in the Entra Admin Center you can see more roles that can be used, including custom roles
Comparing roles
| Entra portal roles | Directory roles |
|---|---|
| Authentication Administrator | Authentication Administrator |
| Cloud Device Administrator | - |
| Groups Administrator | Groups Administrator |
| Helpdesk Administrator | Helpdesk Administrator |
| License Administrator | License Administrator |
| Password Administrator | - |
| Printer Administrator | - |
| SharePoint Administrator | SharePoint Administrator |
| Teams Administrator | - |
| Teams Devices Administrator | - |
| User Administrator | User Administrator |
with POST /v1.0/directory/administrativeUnits/{id}/scopedRoleMembers you cannot assign the following roles:
- Cloud Device Administrator
- Password Administrator
- Printer Administrator
- Teams Administrator
- Teams Device Administrator
- Custom roles
Same for retrieving list of scoped role members, the endpoint GET /v1.0/directory/administrativeUnits/{id}/scopedRoleMembers or cmdlet Get-MgDirectoryAdministrativeUnitScopedRoleMember doesn't return the roles above when they are assigned to a user.
Role management
Role assignment
Fortunately, the Graph API provides another endpoint /v1.0/roleManagement/directory/roleAssignments for role assignment to grant access to resources at a particular scope.
PowerShell SDK:
Import-Module Microsoft.Graph.Identity.Governance
$params = @{
roleDefinitionId = "{role-definition-id}"
principalId = "{user-id}"
directoryScopeId = "/administrativeUnits/{administrative-unit-id}"
}
New-MgRoleManagementDirectoryRoleAssignment -BodyParameter $params
In the body, you need to specify the id of role definition.
Role definition
For managing roles definitions, you can use the endpoint /v1.0/roleManagement/directory/roleDefinitions.
How to get a list of built-in roles definitions that you see in the Entra Portal?
Use the cmdlet Get-MgRoleManagementDirectoryRoleDefinition and filter roles one by one (the endpoint doesn't support Or operator in filter query).
Import-Module Microsoft.Graph.Identity.Governance
Get-MgRoleManagementDirectoryRoleDefinition -Filter "displayName eq 'User Administrator'"
The Microsoft Entra built-in roles have the same ids across all tenants, so you can find the role's id in the documentation and in the table below:
| Role | ID |
|---|---|
| Authentication Administrator | c4e39bd9-1100-46d3-8c65-fb160da0071f |
| Cloud Device Administrator | 7698a772-787b-4ac8-901f-60d6b08affd2 |
| Groups Administrator | fdd7a751-b60b-444a-984c-02652fe8fa1c |
| Helpdesk Administrator | 729827e3-9c14-49f7-bb1b-9608f156bbb8 |
| License Administrator | 4d6ac14f-3453-41d0-bef9-a3e0c569773a |
| Password Administrator | 966707d0-3269-4727-9be2-8c3a10f19b9d |
| Printer Administrator | 644ef478-e28f-4e28-b9dc-3fdde9aa0b1f |
| SharePoint Administrator | f28a1f50-f6e7-4571-818b-6a12f2af6b6c |
| Teams Administrator | 69091246-20e8-4a56-aa4d-066075b2a7a8 |
| Teams Devices Administrator | 3d762c5a-1b6c-493f-843e-55a3b42923d4 |
| User Administrator | fe930be7-5e62-47db-91af-98c3a49a38b1 |
For custom roles, the situation is more complicated. The custom roles with administrative unit scope must have permissions allowed for users, groups, or devices. The filter condition to get custom roles with administrative unit scope is:
rolePermissions/any(x:x/allowedResourceActions/any(z:startswith(z,'microsoft.directory/groups')
or startswith(z,'microsoft.directory/users')
or startswith(z,'microsoft.teams/devices/standard/read')
or startswith(z,'microsoft.directory/devices')
or startswith(z,'microsoft.directory/bitlockerKeys')
or startswith(z,'microsoft.azure.print/allEntities/')
or startswith(z,'microsoft.directory/deviceLocalCredentials')))
and isBuiltIn eq false
The filter applied to the cmdlet Get-MgRoleManagementDirectoryRoleDefinition:
Import-Module Microsoft.Graph.Identity.Governance
Get-MgRoleManagementDirectoryRoleDefinition -Filter "rolePermissions/any(x:x/allowedResourceActions/any(z:startswith(z,'microsoft.directory/groups') or startswith(z,'microsoft.directory/users') or startswith(z,'microsoft.teams/devices/standard/read') or startswith(z,'microsoft.directory/devices') or startswith(z,'microsoft.directory/bitlockerKeys') or startswith(z,'microsoft.azure.print/allEntities/') or startswith(z,'microsoft.directory/deviceLocalCredentials'))) and isBuiltIn eq false"
With this filter, you will get a list of custom roles that can be assigned with administrative unit scope.
Example how to assign a role definition specified by id to a user specified by id with an administrative unit scope
Import-Module Microsoft.Graph.Identity.Governance
$administrativeUnitId = "0a22c83d-c4ac-43e2-bb5e-87af3015d49f"
$adeleVanceId = "61b0c52f-a902-4769-9a09-c6628335b00a"
$teamsAdministratorRoleDefinitionId = "69091246-20e8-4a56-aa4d-066075b2a7a8"
$params = @{
roleDefinitionId = $teamsAdministratorRoleDefinitionId
principalId = $adeleVanceId
directoryScopeId = '/administrativeUnits/$administrativeUnitId'
}
New-MgRoleManagementDirectoryRoleAssignment -BodyParameter $params
Conclusion
The Graph API provides two endpoints to assign a role with an administrative unit scope to a user
/v1.0/directory/administrativeUnits/{id}/scopedRoleMembers
/v1.0/roleManagement/directory/roleAssignments
The endpoint /v1.0/directory/administrativeUnits/{id}/scopedRoleMembers is limited to a small subset of roles that can be assigned with that endpoint.
The endpoint /v1.0/roleManagement/directory/roleAssignments is more general for granting access to different resources.
