Roles based access control in cloud applications using Azure AD

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.

Authorization in Cloud Applications using Azure AD Application Roles

 

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.

Declare Application Roles for an AAD Application - Download Manifest

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’

Sample Application Role that can be assigned to Users and Groups

Sample Application Role that can be assigned to Client Applications

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).

Assign Users and Groups to Application Roles in Azure AD

If the customers’ organization has AAD premium, they can also assign groups to the application using the same user experience.

Assign Groups to Application Roles in Azure AD

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.

Configuring client application to request application roles of resource API

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.

Assigning an application role to a client application during consent

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.

Sample OAuth Request to Trigger Admin Consent

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’.

Roles Claim in Azure AD Tokens - JWT Token

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.

Roles Claim in Azure AD Tokens - SAML Token

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.

[code language=”c”]

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

[/code]

The Training controller (TrainingController.cs file) in the sample application uses a custom Authorize attribute to perform authorization per the user’s roles.

[code]

[AuthorizeUser(Roles = "trainer, trainee")]

[/code]

30 thoughts on “Roles based access control in cloud applications using Azure AD

  1. Evdin URSAN

    According to your JWT example, an user can have multiple roles (which is OK and this is how it should be) but the azure management portal allows only one role per user. Maybe I’m looking in the wrong place but how can I assign more then one role to one user?

    Thanks

    1. dushyantgill Post author

      I missed adding this: Assigning roles to AAD groups requires AAD premium. Once a premium license is assigned to the admin – they will be be able to assign more than one groups to application roles. So using the UI – a user can only be assigned to multiple roles by being a direct member of multiple groups that have been assigned roles.

      That said, this is only a limitation in the UI: Azure AD Graph API can be used to assigned multiple app roles to a user. I shall update the post with the API usage.

      1. evdin ursan

        As I mentioned also on twitter and as I also read, the groups and roles can and should be independent one from eachother. As an example – I have a company which have multiple geographical locations and each location has a set of departments. I need to use groups to separate what data an user can see based on group assignment (only records from his own location) and I need to use roles to give access to different features (hr, financial, warehouse, etc). Please keep in mine that an user can be from one or more groups and can belong to one or more roles.

        Thabk you very much for your time!

        1. dushyantgill Post author

          Evdin – thanks for explaining the scenario.
          let me clarify my earlier response: yes, AAD groups and roles can indeed be used independently. In your example, the application would declare roles (hr, finance etc.) and allow users who own data, to grant access to AAD groups ( e.g. NA_FullTimeEmployees, EU_FullTimeEmployees). Now, the roles (hr, finance) can be assigned by the app admin to users via the portal or by using the Graph API. Portal allows assignment of only one role to the user whereas Graph API allows assigning multiple roles.
          Further, if the organization is using AAD premium, roles can also be assigned to groups (this is different from group claims) – it is a management feature which makes role assigning easier. So if there is a group in AD tht already represents the employees in HR department, the app admin can assign that group to the hr role of the app – then all the members of that group will get the hr role assigned to them. So a user could get multiple roles assigned to them via group membership.
          Hope that clarifies.

          1. Evdin Ursan

            Thank you very much. Yes, is clear now. I have two questions for you (if I may and if you are so kind to answer):
            1) any luck to have the azure portal changed to offer the possibility to assign more then one role to an user?
            2) can you please give me some hints about where to find the complete graph api reference about users and roles assignments (i really don’t mind implementing this functionality in my app using the graph api).

            Than you very much.

  2. Domingo Rossitto

    I’ve enrolled in a Free Trial subscription of Azure along with an AAD Premium trial license. So far, I’ve been unable to find anywhere on manage.windowsazure.com or portal.azure.com that will allow me to select the roles I’ve uploaded to my test website (via the manifest). Has the UI changed since this post was written, or is this functionality limited to paying customers?

    1. dushyantgill Post author

      Domingo, no the Ux hasn’t changed. You should be able to assign users (and groups if you have an AAD Premium license assigned to yourself) to your application in the ‘users’ tab (or ‘users and groups’ tab), under the application. Let me know if you’re still having an issue locating it.

      thanks

      1. Domingo Rossitto

        I wasn’t getting the role dialog to show up during group/user assignment, because I only had one role set up for my application. I didn’t realize that the selection is only available when more than one role is defined. Lesson learned. :)
        Looking to the future, will these settings eventually be exposed in the UI? Is there a feature roadmap for Azure AD? I’m sure I’m not alone in thinking that we shouldn’t have to hack away at the manifest or roll our own admin UI on top of the GraphAPI in order to manage roles.

        1. dushyantgill Post author

          Domingo – managing roles for the application is not a frequent operation – so most of our developers are ok with hacking away at the manifest file to do it. In-fact they check-in the manifest as part of their app code and update it when something changes. Do you have a need to manage these roles for you app often?

          1. Domingo Rossitto

            I work on an internal business application that uses roles to aggregate numerous permission sets for users from Customer Service Level I to Underwriting Manager Level III. These permissions are very granular in nature, and include everything from “CanApproveAccount” to “UserCanSeeCreditScore”. As we add new features, roles tend to emerge that may be cross-departmental in nature. Unfortunately, our homegrown system has become infested with user-level permission assignments that are one step away from, “if John Smith, then…”. Ideally, to implement RBAC, we’d manage permissions only at the role level, even if that means we have an explosion of roles.
            I can accept the process for creating new application roles, but I think our Helpdesk users would require an interface for managing roles at the user level. They would need to be able to see all the of the users in a role and all of the roles for a given user, and have the ability to modify those relationships. Is this something that’s coming down the pike, or is it something we’re expected to build ourselves? Is there a plan to allow for multiple role selection when assigning users/groups?

          2. Brett

            Not exposing the roles just makes the situation lack transparency. It’s confusing for anyone except a developer (and one experienced with azure at that).

    1. dushyantgill Post author

      Ajay, the app roles feature of Azure AD is in preview – however we soon plan to make it generally available. Stay tuned.

  3. Calvin Craig

    Greetings Dushyant,

    Are there REST APIs and/or PowerShell Cmdlets for mapping users and/or groups to Azure website application roles? I just fetched the latest PowerShell bits via the Microsoft Web Platform Installer. But after some sleuthing I don’t any Cmdlets offering such functionality.

    Thanks

    1. dushyantgill Post author

      Hello Calvin,
      You can indeed assigned Azure RBAC roles to users and groups using PowerShell or APIs to grant them access to subscriptions/resource groups/resources. Here’s the reference: http://azure.microsoft.com/en-us/documentation/articles/role-based-access-control-powershell/ and https://msdn.microsoft.com/en-us/library/azure/dn906885.aspx

      If instead you want to assign users and groups to Azure AD Application Roles for an Azure AD integrated application – I am planning to write a blog post on how to assign access using Azure AD Graph API.

      1. Calvin Craig

        Thanks for the response. I’m interested in the latter topic. I would like to programmatically (either via REST APIs or PowerShell) assign/remove users and/or groups to Azure AD Application Roles for an Azure AD integrated application. After searching on the web extensively, I haven’t found any information on this topic. So I was curious if such functionality is even available yet. But since you’re planning to write a blog post, it sounds like this functionality is available. Therefore I would like to know where I can find supporting information. We’ve tried mapping Azure AD groups to application roles and discovered that users who are mapped to more than one AD group only get mapped to one Application Role. Frankly it seems a little buggy at the moment. Therefore we decided as a work around to map users directly to application roles and in lieu of mapping AD groups. Since this is a rather cumbersome process using the portal, we’d like to do it programmatically.

  4. Ashok Kumar Singh

    Hello Dushyant,

    Is their any graph api available which is used to assign user to Azure ad premium or basic license.Yes manually we can do but i want some graph api.

    Regards,
    Ashok

  5. Milen

    Hi Dushyant,

    Have you tried doing the same for Web API endpoint registered as an Azure app? Should there be any differences?

    Cheers,
    Milen

  6. Keith

    Hi Dushyant,
    Thanks for the great post ! I just want to be clear on something. In the case of OpenID Connect, do the roles come back in the id_token itself or are they in another signed JWT access token ? Is the JWT token shown above the id_token or another token coming back from AD ?
    Thanks,
    Keith

    1. dushyantgill Post author

      You’re welcome Keith. Yes – roles claim is indeed returned in the idtoken too. My example shows roles claim in an access token.

    1. dushyantgill Post author

      AAD integrated app employing app roles can be running anywhere – on a dev box/company data center/or cloud … Not sure if I understood the question.

  7. Ajay

    Is this Feature work in progress or generally available?
    Where can i find the documentation in azure site in-case it is generally available?

  8. Lewis

    Hi Dushyant,

    I followed the instructions and was able to assign application roles in the AAD but when I debug my website it appears the roles are not pulled down with the rest of the user data. Where can I look to verify the roles are actually being included with the User?

    1. Lewis

      Never mind, I found it in the ClaimsPrincipal. I didn’t realize it was case-sensitive to the “value” attribute. It’s working now, thanks for the great post!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>