Edit

Add app roles to your application and receive them in the token

  • Article
  • 7 minutes to read

Role-based access control (RBAC) is a popular mechanism to enforce authorization in applications. RBAC allows administrators to grant permissions to roles rather than to specific users or groups. The administrator can then assign roles to different users and groups to control who has access to what content and functionality.

By using RBAC with application role and role claims, developers can securely enforce authorization in their apps with less effort.

Another approach is to use Azure Active Directory (Azure AD) groups and group claims as shown in the active-directory-aspnetcore-webapp-openidconnect-v2 code sample on GitHub. Azure AD groups and application roles aren't mutually exclusive; they can be used together to provide even finer-grained access control.

Declare roles for an application

You define app roles by using the Azure portal during the app registration process. App roles are defined on an application registration representing a service, app or API. When a user signs in to the application, Azure AD emits a roles claim for each role that the user or service principal has been granted. This can be used to implement claim-based authorization. App roles can be assigned to a user or a group of users. App roles can also be assigned to the service principal for another application, or to the service principal for a managed identity.

Currently, if you add a service principal to a group, and then assign an app role to that group, Azure AD doesn't add the roles claim to tokens it issues.

App roles are declared using App roles UI in the Azure portal:

The number of roles you add counts toward application manifest limits enforced by Azure AD. For information about these limits, see the Manifest limits section of Azure Active Directory app manifest reference.

App roles UI

To create an app role by using the Azure portal's user interface:

  1. Sign in to the Azure portal.

  2. If you have access to multiple tenants, use the Directories + subscriptions filter in the top menu to switch to the tenant that contains the app registration to which you want to add an app role.

  3. Search for and select Azure Active Directory.

  4. Under Manage, select App registrations, and then select the application you want to define app roles in.

  5. Select App roles, and then select Create app role.

    An app registration's app roles pane in the Azure portal

  6. In the Create app role pane, enter the settings for the role. The table following the image describes each setting and their parameters.

    An app registration's app roles create context pane in the Azure portal

    Field Description Example
    Display name Display name for the app role that appears in the admin consent and app assignment experiences. This value may contain spaces. Survey Writer
    Allowed member types Specifies whether this app role can be assigned to users, applications, or both.

    When available to applications, app roles appear as application permissions in an app registration's Manage section > API permissions > Add a permission > My APIs > Choose an API > Application permissions.    		 Users/Groups
    Value Specifies the value of the roles claim that the application should expect in the token. The value should exactly match the string referenced in the application's code. The value can't contain spaces. Survey.Create
    Description A more detailed description of the app role displayed during admin app assignment and consent experiences. Writers can create surveys.
    Do you want to enable this app role? Specifies whether the app role is enabled. To delete an app role, deselect this checkbox and apply the change before attempting the delete operation. Checked

  7. Select Apply to save your changes.

Assign users and groups to roles

Once you've added app roles in your application, you can assign users and groups to the roles. Assignment of users and groups to roles can be done through the portal's UI, or programmatically using Microsoft Graph. When the users assigned to the various app roles sign in to the application, their tokens will have their assigned roles in the roles claim.

To assign users and groups to roles by using the Azure portal:

  1. Sign in to the Azure portal.
  2. In Azure Active Directory, select Enterprise applications in the left-hand navigation menu.
  3. Select All applications to view a list of all your applications. If your application doesn't appear in the list, use the filters at the top of the All applications list to restrict the list, or scroll down the list to locate your application.
  4. Select the application in which you want to assign users or security group to roles.
  5. Under Manage, select Users and groups.
  6. Select Add user to open the Add Assignment pane.
  7. Select the Users and groups selector from the Add Assignment pane. A list of users and security groups is displayed. You can search for a certain user or group and select multiple users and groups that appear in the list.
  8. Once you've selected users and groups, select the Select button to proceed.
  9. Select Select a role in the Add assignment pane. All the roles that you've defined for the application are displayed.
  10. Choose a role and select the Select button.
  11. Select the Assign button to finish the assignment of users and groups to the app.

Confirm that the users and groups you added appear in the Users and groups list.

Assign app roles to applications

Once you've added app roles in your application, you can assign an app role to a client app by using the Azure portal or programmatically by using Microsoft Graph.

When you assign app roles to an application, you create application permissions. Application permissions are typically used by daemon apps or back-end services that need to authenticate and make authorized API call as themselves, without the interaction of a user.

To assign app roles to an application by using the Azure portal:

  1. Sign in to the Azure portal.
  2. In Azure Active Directory, select App registrations in the left-hand navigation menu.
  3. Select All applications to view a list of all your applications. If your application doesn't appear in the list, use the filters at the top of the All applications list to restrict the list, or scroll down the list to locate your application.
  4. Select the application to which you want to assign an app role.
  5. Select API permissions > Add a permission.
  6. Select the My APIs tab, and then select the app for which you defined app roles.
  7. Select Application permissions.
  8. Select the role(s) you want to assign.
  9. Select the Add permissions button complete addition of the role(s).

The newly added roles should appear in your app registration's API permissions pane.

Because these are application permissions, not delegated permissions, an admin must grant consent to use the app roles assigned to the application.

  1. In the app registration's API permissions pane, select Grant admin consent for <tenant name>.
  2. Select Yes when prompted to grant consent for the requested permissions.

The Status column should reflect that consent has been Granted for <tenant name>.

Usage scenario of app roles

If you're implementing app role business logic that signs in the users in your application scenario, first define the app roles in App registrations. Then, an admin assigns them to users and groups in the Enterprise applications pane. These assigned app roles are included with any token that's issued for your application, either access tokens when your app is the API being called by an app or ID tokens when your app is signing in a user.

If you're implementing app role business logic in an app-calling-API scenario, you have two app registrations. One app registration is for the app, and a second app registration is for the API. In this case, define the app roles and assign them to the user or group in the app registration of the API. When the user authenticates with the app and requests an ID token to call the API, a roles claim is included in the ID token. Your next step is to add code to your web API to check for those roles when the API is called.

To learn how to add authorization to your web API, see Protected web API: Verify scopes and app roles.

App roles vs. groups

Though you can use app roles or groups for authorization, key differences between them can influence which you decide to use for your scenario.

App roles Groups
They're specific to an application and are defined in the app registration. They move with the application. They aren't specific to an app, but to an Azure AD tenant.
App roles are removed when their app registration is removed. Groups remain intact even if the app is removed.
Provided in the roles claim. Provided in groups claim.

Developers can use app roles to control whether a user can sign in to an app or an app can obtain an access token for a web API. To extend this security control to groups, developers and admins can also assign security groups to app roles.

App roles are preferred by developers when they want to describe and control the parameters of authorization in their app themselves. For example, an app using groups for authorization will break in the next tenant as both the group ID and name could be different. An app using app roles remains safe. In fact, assigning groups to app roles is popular with SaaS apps for the same reasons as it allows the SaaS app to be provisioned in multiple tenants.

Next steps

Learn more about app roles with the following resources.