Create a custom role in Microsoft Entra ID

Create a custom role

These steps describe how to create a custom role in the Microsoft Entra admin center to manage app registrations.

1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.

2. Browse to Identity > Roles & admins > Roles & admins.

3. Select New custom role.

   

4. 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.

   

5. 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.

   1. First, enter "credentials" in the search bar and select the microsoft.directory/applications/credentials/update permission.

      

   2. Next, enter "basic" in the search bar, select the microsoft.directory/applications/basic/update permission, and then click Next.

6. 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.

Sign in

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 custom role

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 a custom role

# 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 a custom role

# Delete role definition
Remove-MgRoleManagementDirectoryRoleDefinition -UnifiedRoleDefinitionId c4e39bd9-1100-46d3-8c65-fb160da0071f

Create a custom role

Follow these steps:

1. 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"
               ]
           }
       ]
   }
   

   Note

   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.

2. 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>"
   }