This article describes how to create a custom role in Microsoft Entra ID using the Microsoft Entra admin center, Microsoft Graph PowerShell, or Microsoft Graph API.
For the basics of custom roles, see the custom roles overview. The role can be assigned either at the directory-level scope or an app registration resource scope only. For information about the maximum number of custom roles that can be created in a Microsoft Entra organization, see Microsoft Entra service limits and restrictions.
For more information, see Prerequisites to use PowerShell.
These steps describe how to create a custom role in the Microsoft Entra admin center to manage app registrations.
提示
Steps in this article might vary slightly based on the portal you start from.
Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.
Browse to Identity > Roles & admins > Roles & admins.
Select New custom role.
On the Basics tab, provide a name and description for the role.
You can clone the baseline permissions from a custom role but you can't clone a built-in role.
On the Permissions tab, select the permissions necessary to manage basic properties and credential properties of app registrations. For a detailed description of each permission, see Application registration subtypes and permissions in Microsoft Entra ID.
First, enter "credentials" in the search bar and select the microsoft.directory/applications/credentials/update permission.
Next, enter "basic" in the search bar, select the microsoft.directory/applications/basic/update permission, and then click Next.
On the Review + create tab, review the permissions and select Create.
Your custom role will show up in the list of available roles to assign.
Use the Connect-MgGraph command to sign in to your tenant.
Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "RoleManagement.ReadWrite.Directory"
Create a new role using the following PowerShell script:
# Basic role information
$displayName = "Application Support Administrator"
$description = "Can manage basic aspects of application registrations."
$templateId = (New-Guid).Guid
# Set of permissions to grant
$rolePermissions = @{
"allowedResourceActions" = @(
"microsoft.directory/applications/basic/update",
"microsoft.directory/applications/credentials/update"
)
}
# Create new custom admin role
$customAdmin = New-MgRoleManagementDirectoryRoleDefinition -RolePermissions $rolePermissions `
-DisplayName $displayName -Description $description -TemplateId $templateId -IsEnabled:$true
# Update role definition
# This works for any writable property on role definition. You can replace display name with other
# valid properties.
Update-MgRoleManagementDirectoryRoleDefinition -UnifiedRoleDefinitionId c4e39bd9-1100-46d3-8c65-fb160da0071f `
-DisplayName "Updated DisplayName"
# Delete role definition
Remove-MgRoleManagementDirectoryRoleDefinition -UnifiedRoleDefinitionId c4e39bd9-1100-46d3-8c65-fb160da0071f
Follow these steps:
Use the Create unifiedRoleDefinition API to create a custom role.
POST https://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleDefinitions
Body
{
"description": "Can manage basic aspects of application registrations.",
"displayName": "Application Support Administrator",
"isEnabled": true,
"templateId": "<GUID>",
"rolePermissions": [
{
"allowedResourceActions": [
"microsoft.directory/applications/basic/update",
"microsoft.directory/applications/credentials/update"
]
}
]
}
注意
The "templateId": "GUID" is an optional parameter that's sent in the body depending on the requirement. If you have a requirement to create multiple different custom roles with common parameters, it's best to create a template and define a templateId value. You can generate a templateId value beforehand by using the PowerShell cmdlet (New-Guid).Guid.
Use the Create unifiedRoleAssignment API to assign the custom role.
POST https://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleAssignments
Body
{
"principalId":"<GUID OF USER>",
"roleDefinitionId":"<GUID OF ROLE DEFINITION>",
"directoryScopeId":"/<GUID OF APPLICATION REGISTRATION>"
}
