You can customize the role claim in the access token that is received after an application is authorized. Use this feature if your application expects custom roles in the token. You can create as many roles as you need.
Prerequisites
A Microsoft Entra subscription with a configured tenant. For more information, see Quickstart: Set up a tenant.
An enterprise application is also referred to as a service principal. Record the appRoles property from the service principal object that was returned. The following example shows the typical appRoles property:
In Graph Explorer, change the method from GET to PATCH.
Copy the appRoles property that was previously recorded into the Request body pane of Graph Explorer, add the new role definition, and then select Run Query to execute the patch operation. A success message confirms the creation of the role. The following example shows the addition of an Admin role:
You must include the msiam_access role object in addition to any new roles in the request body. Failure to include any existing roles in the request body removes them from the appRoles object. Also, you can add as many roles as your organization needs. The value of these roles is sent as the claim value in the SAML response. To generate the GUID values for the ID of new roles use the web tools, such as the Online GUID / UUID Generator. The appRoles property in the response includes what was in the request body of the query.
Edit attributes
Update the attributes to define the role claim that is included in the token.
Locate the application in the Microsoft Entra admin center, and then select Single sign-on in the left menu.
In the Attributes & Claims section, select Edit.
Select Add new claim.
In the Name box, type the attribute name. This example uses Role Name as the claim name.
Leave the Namespace box blank.
From the Source attribute list, select user.assignedroles.
Select Save. The new Role Name attribute should now appear in the Attributes & Claims section. The claim should now be included in the access token when signing into the application.
Assign roles
After the service principal is patched with more roles, you can assign users to the respective roles.
Locate the application to which the role was added in the Microsoft Entra admin center.
Select Users and groups in the left menu and then select the user that you want to assign the new role.
Select Edit assignment at the top of the pane to change the role.
Select None Selected, select the role from the list, and then select Select.
Select Assign to assign the role to the user.
Update roles
To update an existing role, perform the following steps:
Record the appRoles property from the service principal object that was returned.
In Graph Explorer, change the method from GET to PATCH.
Copy the appRoles property that was previously recorded into the Request body pane of Graph Explorer, add update the role definition, and then select Run Query to execute the patch operation.
Delete roles
To delete an existing role, perform the following steps:
Sign in to the Graph Explorer site as a Privileged Role Administrator.
Using the object ID for the application from the overview pane in the Azure portal, replace <objectID> in the following request with it and then run the query:
Record the appRoles property from the service principal object that was returned.
In Graph Explorer, change the method from GET to PATCH.
Copy the appRoles property that was previously recorded into the Request body pane of Graph Explorer, set the IsEnabled value to false for the role that you want to delete, and then select Run Query to execute the patch operation. A role must be disabled before it can be deleted.
After the role is disabled, delete that role block from the appRoles section. Keep the method as PATCH, and select Run Query again.
This module focuses on effectively managing identities and enhancing security in Microsoft Enterprise Identity, ensuring that users, groups, and external identities are protected against security threats and unauthorized access.
Learn how to configure optional claims and attributes in access tokens issued by Microsoft identity platform; optional claims can add useful user information for your app.
Learn how to configure app role definitions and security groups to improve flexibility and control while increasing application zero trust security with least privilege.
Learn about the custom claims policy and claims mapping policy types, which are used to modify the claims emitted in tokens in the Microsoft identity platform.
Learn how to add app roles to an application registered in Microsoft Entra ID. Assign users and groups to these roles, and receive them in the 'roles' claim in the token.