Create a custom role in Microsoft Entra ID

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.

Prerequisites

• Microsoft Entra ID P1 or P2 license
• Privileged Role Administrator
• Microsoft Graph PowerShell module when using PowerShell
• Admin consent when using Graph explorer for Microsoft Graph API

For more information, see Prerequisites to use PowerShell or Graph Explorer.

Admin center

Create a custom role

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

Tip

Steps in this article might vary slightly based on the portal you start from.

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.

PowerShell

Sign in

Use the Connect-MgGraph command to sign in to your tenant.

Connect-MgGraph -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

Graph API

Create a custom role

Follow these steps:

1. Use the Create unifiedRoleDefinition API to create a custom role.

   POST https://graph.microsoft.com/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://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
   

   Body

   {
   "principalId":"<GUID OF USER>",
   "roleDefinitionId":"<GUID OF ROLE DEFINITION>",
   "directoryScopeId":"/<GUID OF APPLICATION REGISTRATION>"
   }
   

Related content

• Microsoft Entra administrative roles forum
• Microsoft Entra built-in roles
• Comparison of default guest and member user permissions