Create and assign a custom role in Microsoft Entra ID

  • How-to

This article describes how to create new custom roles in Microsoft Entra ID. 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.

Custom roles can be created in the Roles and administrators page of the Microsoft Entra admin center.

Prerequisites

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

For more information, see Prerequisites to use PowerShell.

Create a role in the Microsoft Entra admin center

Create a new custom role to grant access 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.

    Create or edit roles from the Roles and administrators page

  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.

    provide a name and description for a custom role on the Basics tab

  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.

      Select the permissions for a custom role on the Permissions tab

    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.

Create a role using PowerShell

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 the 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
$allowedResourceAction =
@(
    "microsoft.directory/applications/basic/update",
    "microsoft.directory/applications/credentials/update"
)
$rolePermissions = @(@{AllowedResourceActions= $allowedResourceAction})

# Create new custom admin role
$customAdmin = New-MgRoleManagementDirectoryRoleDefinition -RolePermissions $rolePermissions -DisplayName $displayName -IsEnabled -Description $description -TemplateId $templateId

Assign the custom role using PowerShell

Assign the role using the below PowerShell script:

# Get the user and role definition you want to link
$user = Get-MgUser -Filter "userPrincipalName eq 'user@contoso.com'"
$roleDefinition = Get-MgRoleManagementDirectoryRoleDefinition -Filter "DisplayName eq 'Application Support Administrator'"

# Get app registration and construct resource scope for assignment.
$appRegistration = Get-MgApplication -Filter "Displayname eq 'MyApp1'"
$resourceScope = '/' + $appRegistration.objectId

# Create a scoped role assignment
$roleAssignment = New-MgRoleManagementDirectoryRoleAssignment -DirectoryScopeId $resourcescope -RoleDefinitionId $roledefinition.Id -PrincipalId $user.Id

Create a role with the Microsoft Graph API

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

Assign a custom role scoped to a resource

Like built-in roles, custom roles are assigned by default at the default organization-wide scope to grant access permissions over all app registrations in your organization. Additionally, custom roles and some relevant built-in roles (depending on the type of Microsoft Entra resource) can also be assigned at the scope of a single Microsoft Entra resource. This allows you to give the user the permission to update credentials and basic properties of a single app without having to create a second custom role.

  1. Sign in to the Microsoft Entra admin center as at least a Application Developer.

  2. Browse to Identity > Applications > App registrations.

  3. Select the app registration to which you are granting access to manage. You might have to select All applications to see the complete list of app registrations in your Microsoft Entra organization.

    Select the app registration as a resource scope for a role assignment

  4. In the app registration, select Roles and administrators. If you haven't already created one, instructions are in the preceding procedure.

  5. Select the role to open the Assignments page.

  6. Select Add assignment to add a user. The user will be granted any permissions over only the selected app registration.

Related content