Applications often employ roles based access control (RBAC) to model authorization. In RBAC, a role is a collections of permissions. Roles can be granted to users or collection of users (groups). In a simple RBAC model the developer defines a set of roles that make sense for the application and the administrator of the application assigns those roles to users to manage access.
In Azure Active Directory we have recently turned on the ability for developers to declare a set of roles as part of the application registration in AAD. Once the roles are declared, when a customer admin assigns users/groups to the application in the Azure management portal, they select which application role the user/group is assigned to. Once a user is assigned to an application role (either through a direct assignment or via an assignment to a group that the user is member of), Azure AD includes the roles claim in the token when the user signs in to the application. The application can then authorize the user using constructs like IsInRole(“reader”) or the [Authorize (Roles=”reader”)] of .net.
Application roles is also the quickest way for a developer to integrate access management of their application with AD groups – see the video above in which I have demonstrated a user managing access to my application via AD group membership. A few early adopter ISVs of this feature chose to model their licensing using application roles where for instance their application publishes “Platinum”, “Gold” and “Silver” licenses that their Azure AD customers purchase and assign to users and groups during the assignment experience in the Azure management portal.
In addition to users and groups, application roles can also be assigned to other client application. Azure AD consent framework enables web and mobile applications to request for OAuth2Permissions to WebAPIs (e.g. Office 365 APIs) that Azure AD customers use. Now, Azure AD also allows web applications and web APIs that act as clients and access other resource APIs, to request for application roles of resource API to be assigned to them. The role gets assigned to the client app when it is installed by the Azure AD customers.
Alright, let’s configure Azure AD application roles for your cloud service. The code that I refer to is from the sample application published at: https://github.com/dushyantgill/VipSwapper. The application MVC sample application is running in Azure websites here: http://www.VipSwapper.com/TrainingPoint. We will begin by declaring a set of application roles for the Azure AD integrated web application and then write code to process the roles claim. We will also see how the customers of the application would assigned users, groups and client apps from their organization to the application roles.
Declaring application roles for your application
Either the application owner (developer of the app) or the global administrator of the developer’s directory can declare application roles for an application. In the Azure management portal, navigate to the Active Directory node and go to the Applications tab. Click to open the application for which you wish to enable declare application roles. Click on the Manage Manifest action button on the bottom bar and select to Download Manifest. Open the manifest file in a JSON editor of your choice.
Locate the appRoles setting and insert the appRole definitions in the array.
|id||Generate a new GUID for the id property of the appRole|
|displayName||Provide the displayName of the appRole. This will be displayed in the users and groups assignment experience as well as in the consent experience|
|description||Describe what application privileges the appRole grants. This will help the administrator of the customer’s directory to assess the effect of granting this appRole to users groups and client applications.|
|value||Azure AD will emit this value in the roles claim in the tokens that users and client applications get for the resource application|
|allowedMemberTypes||This property of the appRole dictates when the role can be assigned to users and groups or to client applications or both. To enable the role be assigned to users or groups, specify “User”, and to specify the role be assigned to client applications, specify “Application”.|
|isEnabled||Set this to true for new appRoles|
|origin||This property of appRole will be deprecated. Please set its value to ‘Application’|
Assigning users and groups to application roles
After a global administrator of the customer’s organization has installed your application, either they themselves or a user accounts administrator in their organization can then assign users and groups to your application: navigate to the users tab under the application to which you would like to assign users and groups. Select a user and click on the Assign action on the bottom bar. Here you can assign the desired role to the user.
Note that today only the global administrator or the user administrator of the directory can assign application roles. In a coming release we are planning to also allow the application owner to assign roles to the application (in the case of a single tenant application the developer is the application owner).
If the customers’ organization has AAD premium, they can also assign groups to the application using the same user experience.
Assigning client applications to application roles of resource APIs
Application roles can also be assigned to other web applications that access the resource application as clients. For this, the client application must request the application role using the Azure AD common consent framework and the assignment of the role happens when the client application is installed.
Configuring client application to request application roles of resource API
A confidential client application can now request for application roles of other APIs be assigned to it, when it is being installed by the customer. For this a global administrator of directory in which the client application is registered (developer’s directory) needs to specify the required application roles: in the Azure AD node in the Azure management portal, select the applications tab and then select the application that needs to request application roles. On the configure tab scroll down to the section called ‘permissions to other application’. Here, add a new permission by first selecting the API for which the client application is requesting an application role, and then selecting the desired application role in the Application Permissions drop down.
Assigning an application role to a client application during consent
Once the client application has been configured to request application roles on resource APIs, the global administrator installing the client application can review the application roles request by the application and consent, to assign the application roles to the client application.
Note that once a client application has been configured to request for application roles on resource APIs, it can only be installed by a global administrator of customer’s directory. Directory users can no longer consent to the application.
Processing roles claim
Authentication flows that support roles claim
Auth flow supported by Azure AD
Roles claim issued?
|SAML/WSFed/OpenIdConnect SSO||Yes – in the SAML token and id_token.Value: appRoles of client app that are assigned to the user.|
|OAuth Authorization Code Grant, Implicit Grant Flow, Resource Owner Password Credential Grant, Refresh Token Grant, Access Token Grant and Extension Grants||Yes – in the access token.Value: appRoles of resource app that are assigned to the user.|
|OAuth Client Credential Flow||Yes – in the access token.Value: appRoles of resource app that are assigned to the client app.|
Roles claim type and value
The claim type of the roles claim in the JWT tokens is ‘roles’.
The Attribute Name of roles attribute in the SAML tokens is ‘http://schemas.microsoft.com/ws/2008/06/identity/claims/role’. It is a multi-valued attribute.
The following code in the Startup.Auth.cs file of the sample application configures the roles claim type. From then on the rest of the code in the application can check access using the IsInRole() or the [Authorize] attribute.
TokenValidationParameters = new System.IdentityModel.Tokens.TokenValidationParameters
// we inject our own multitenant validation logic
ValidateIssuer = false,
// map the claimsPrincipal’s roles to the roles claim
RoleClaimType = "roles",
The Training controller (TrainingController.cs file) in the sample application uses a custom Authorize attribute to perform authorization per the user’s roles.
[AuthorizeUser(Roles = "trainer, trainee")]