Create and assign a custom role in Azure Active Directory

10/26/2021
3 minutes to read

This article describes how to create new custom roles in Azure Active Directory (Azure AD). 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 tab on the Azure AD overview page.

Prerequisites

Azure AD Premium P1 or P2 license
Privileged Role Administrator or Global Administrator
AzureADPreview 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.

Create a role in the Azure portal

Create a new custom role to grant access to manage app registrations

Sign in to the Azure portal or Azure AD admin center.
Select Azure Active Directory > Roles and administrators > New custom role.
On the Basics tab, provide a name and description for the role and then click Next.
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 Azure Active Directory.
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.
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

Connect to Azure

To connect to Azure Active Directory, use the following command:

Connect-AzureAD

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-AzureADMSRoleDefinition -RolePermissions $rolePermissions -DisplayName $displayName -Description $description -TemplateId $templateId -IsEnabled $true

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-AzureADUser -Filter "userPrincipalName eq 'cburl@f128.info'"
$roleDefinition = Get-AzureADMSRoleDefinition -Filter "displayName eq 'Application Support Administrator'"

# Get app registration and construct resource scope for assignment.
$appRegistration = Get-AzureADApplication -Filter "displayName eq 'f/128 Filter Photos'"
$resourceScope = '/' + $appRegistration.objectId

# Create a scoped role assignment
$roleAssignment = New-AzureADMSRoleAssignment -DirectoryScopeId $resourceScope -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.objectId

Create a role with the Microsoft Graph API

Create the role definition.

HTTP request to create a custom role definition.

POST

https://graph.microsoft.com/beta/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.

Create the role assignment.