DEV Community: ockamey

Configuring Roles in Azure Active Directory

ockamey — Thu, 15 Oct 2020 04:53:00 +0000

Intro

In my previous articles I've uncovered how to configure scopes in Azure Active Directory (If you haven't seen them, you can find the first part here and the second part here). In this tutorial, we'll work on roles, which is a great mechanism, used for authorization. Firstly I'll explain the basics of the RBAC concept, and then by using an example, I'll walk through the main features related to roles in AAD. So let's get started.

Concept

In the concept of scopes, the user allows the client's application to perform particular actions on behalf of them in a resource application. The RBAC (Roles Based Access Control) concept states what a user/application is allowed to do in a resource application, based on the particular roles they have. It means that, for example, the user that has the role of Reader can read books, but they can't moderate them because they don't have the role of Moderator. This means it's more focused on what the end-user/application can and cannot do. This is a really rough definition, thus, I encourage you to read some articles on the internet about it if you don't feel confident about RBAC. There are plenty of articles but this is one I can highly recommend.

Creating applications

First of all, we're going to need to create two applications in AAD(the same as in my Scopes tutorial): both a Client and a Resource application. You can do this by following these steps:

Your Azure Active Directory instance -> App registration -> New registration:

You need to fill in the Name textbox (you can provide a different name, of course, but I suggest using the same one, because I’ll continue to use the same name throughout this tutorial):

The same requirement needs to be completed for the Resource Application. As shown in the screenshot below:

We’ve created two different applications in AAD (these are not WebService or Azure Function applications or any other — both are only representations of physical applications in AAD):

ClientApp — this application represents the service that communicates with the Resource application directly, for example, service to service (e.g. an Azure Function communicates with another Azure Function). This is why we'll use this application when assigning roles to the application, and acquiring token using Client Credentials. For flow where a user is present I'll use OpenID Connect in which using the ClientApp isn't needed, but won't feel afraid, I'll present the example step by step. If you aren't familiar with OpenID Connect, in my first tutorial about scopes I've attached great video about it, so feel free to watch it.
BooksCollectionApp — this application represents the Resource Application that may have sensitive information belonging to the User (e.g. WEB API could contain a User’s secret books).

We need to set up a few things before we go on to creating roles. Firstly, we have to add a redirect URL to both our applications. Second, we have to enable ID tokens for the BooksCollectionApp, as we want to use OpenID Connect to authenticate users.

Let's go to the Authentication option in the ClientApp by following:

Your Azure Active Directory instance -> App registration -> ClientApp -> Authentication

Click the "Add a platform" button, and on the panel on the right hand side, select "Web block":

Next, fill in the Redirect URLs as shown in the screen below:

Then click the "Configure" button. You may notice that I've put the localhost there. This is because it's for testing purposes, and I don't want to be redirected (my code being sent) to other websites. In the real case scenario, you should provide the address to your real hosted application.

We almost have to replicate the same actions for the BooksCollectionApp, however, the ID tokens checkbox must also be selected, as shown:

Again click the "Configure" button.
Now the prerequsites have been completed, we can start to focus on, the main point of this tutorial, roles in our applications.

Creating roles

In the Azure Active Directory we can differentiate two types of roles: one for users, and another for applications. While this tutorial was being created, the only way to define roles in an application was to do it in the application's Manifest (application definition in JSON format). Let's go ahead and create one for a user and one for an application.

To get to the Manifest, you have to follow:

Your Azure Active Directory instance -> App registration -> BooksCollectionApp -> Manifest

Once completed, you should see a similar screen, as below:

The red underlined part shows the definitions of the roles, this means there haven't been any roles defined in our application yet. Let's create one by adding an item into the array, as shown in the snippet below:



    {
        "allowedMemberTypes": [
            "User"
        ],
        "description": "Enables a user to read books",
        "displayName": "Reader",
        "id": "2ef66a29-eaa8-4b0d-8763-aaafb2002a5a",
        "isEnabled": true,
        "lang": null,
        "origin": "Application",
        "value": "Reader"
    }

We've created a Reader role that only exists for users (because we've inserted a User value into the allowedMemberTypes array). In the final application (e.g. WebAPI or Azure Function) this role can be used to permit all users that have the Reader role to read books.
Next, we'll create another role, this time for applications only:



    {
        "allowedMemberTypes": [
            "Application"
        ],
        "description": "Enables an application to create/edit/delete books",
        "displayName": "Moderator",
        "id": "67d25112-7487-4cce-a131-d933adb7ff95",
        "isEnabled": true,
        "lang": null,
        "origin": "Application",
        "value": "Moderator"
    }

In the snippet above, we've created the role Moderator which can only be used by applications (the value Application can be seen in the allowedMemberTypes). This could mean that, only applications that contain a token with the role of Moderator, can moderate books in the end application.
After our changes, the appRoles part of the Manifest file in the Portal should look like this:

Keep in mind that, when you create a new role, you have to provide a unique id every time. I encourage you to use a GUID generator for this purpose. The second thing that I'd like to point out is, you can create a role that can be assigned to both users and applications. You can do this by adding two items to the array.

Assigning user roles

In order to assign a role to a user, you first have to go to:

Your Azure Active Directory instance -> Enterprise applications-> BooksCollectionApp -> Users and groups

Then, click the button "Add user" as shown in the screen below:

In the next screen, you can specify what role should be assigned to the user. For the non-testing solutions, I wouldn't recommend assigning a role to single users, hovever, I would instead assign a role to the whole group as it ensures less maintenance work in the future. For this tutorial though, we'll only assign a simple role to the user, namely the Reader role.

In the "Add Assignment" view select the user that you want to assign the Reader role to, and as far as the role is concerned, you don't need to select anything because we've only specified this one specific role for the users purposes. The assignment should resemble the screen below:

After clicking the "Assign" button, you should be redirected to the "Users and groups" view, which shows the assignment that we've made:

Perfect, so now we can check if the Reader role is visible in the user's token. In my previous tutorial, I've shown you how to get a token via Authorization Code and Client Credential flow, but now we'll take advantage of Open ID Connect to get a token for the user.
Let's prepare the request in the Postman, as shown below:

Remember that in place of the black box (between domain name and ouath2 element in the URL) you have to place your tenant id and in place of the client_id value, you must insert the Client ID of your BooksCollectionApp. The parameters response_type and scope show that we want to obtain a token using Open ID Connect. The redirect_uri that was provided at the start of this tutorial must be inserted in the same way during the creation of the application. The nonce parameter is there for security reasons, to prevent token replay attacks (it should be a random value, but in our case I've chosen a pretty round one).
Copy the request's URL and paste it to the browser, then you'll be redirected to the login page.
Remember that you have to log in as the user that you've specified in the role assignment view. After logging in, you should be able to see the consent view:

If you give the application consent, you'll be redirected to a localhost and in the query parameters you'll be able to see the token, as shown in bold below:

https://localhost:44327/signin-oidc#id_token={TOKEN}&session_state=7d973d4b-3c74-49be-c180abf

Copy the token, and paste it into the input box, from this page: https://jwt.ms which will allow us to decode the token and to see what's inside. After doing that you should be able to see a view, similar to this one:

You can see, that our token has two very important claims: aud which points to the BooksCollectionApp, and roles which states what roles have been assigned to us. Based on this information, the end application e.g. Azure Function or WebAPI is able to authorize the action that we want to perform. In our case, it means that we're able to read books.

Try getting a token for other users that haven't been assigned to this role, and check to see if they also have the same Reader role in their token!

In this tutorial, we've used OpenID Connect to get the token, hovever, it should be noted, that you can also use Authorization Code flow, just as we've used in the previous tutorials. You can treat this as homework ;)

Assigning application roles

In this scenario, we would like to assign the role of Moderator to the ClientApp. This can be extremely helpful when, there are for example, many services that connect to one service and we only want to allow certain services to perform particular actions, in this case, role based access control fits well. To configure it in AAD, first of all, you have to go to the "API Permissions" view in your ClientApp:

Your Azure Active Directory instance -> App registration -> ClientApp -> API Permissions

Firstly, click the "Add a permission" button, subsequently the panel on the right-hand side should be displayed. The "My APIs" button must be selected and the "BooksCollectionApp" clicked, as shown in the screen below:

The panel should change to the one presented below.

On the panel, you can see two types of permissions: Delegated and Application. In the previous articles about scopes, I've explained that "Delegated permissions" are related to scopes. Application permissions though are related to the different roles that can be assigned to applications. This means that if you click "Application permissions", you'll get a list which shows all the roles from the selected application that are defined by "Application" in the allowedMemberTypes contained within Manifest. This is why you can only see the Moderator role, without the Reader role.

Let's select Application permissions, check Moderator role, and click the "Add permissions" button.

After that you should see the list of scopes and roles, as presented below, that have been assigned to the ClientApp application:

You can see that the ClientApp application has two permissions assigned:

User.Read - which is a scope (this is because the type column is "Delegated").
Moderator - the role that we've just assigned.

All application roles require "Admin consent", this means that the Global Administrator has to click the button "Grant admin consent for..." to make these roles work with the application. Go ahead and click the button "Grant admin consent for..." which can be seen above in the permissions table. After clicking it, you should see that the status of the permission has changed to allow access, as can be seen with the green tick. A similar view is shown below:

The last step to ensure you have the "Moderator" role is to get a token to check if the "Moderator" role is contained. We'll use the Client Credentials flow, because this is an OAuth flow that doesn't require a user. So let's generate a request in the Postman:

Keep in mind that the client_id and the client_secret are the Client ID and the Client Secret of your ClientApp. The grant_type parameter specifies that we're using the Client Credentials flow, and the scope parameter should be either {{Application ID URI}}/.default or {{Resource application ClientID}}/.default (I've described it better in my previous tutorial). In your case you should provide {{Your BooksCollectionApp ClientID}}/.default. As can be seen below:

Send the request, copy the token and paste it to the following: https://jwt.ms. If you've done everything correctly, the Moderator role should be visible in your JWT. The token that has been obtained in jwt.ms looks like this:

If the role in the token contains Moderator, then you have correctly assigned it to the ClientApp. Additionaly, you can create another application in AAD and try to obtain a token for it, to ensure that there is no Moderator role included.

Summary

We've now finished my basic tutorial on how to configure roles in Azure Active Directory. I hope that I have enlightened you on the Roles concept in AAD and it is now more familiar to you. If you want more information I advice you to check out Microsoft's documentation to get more details. If you have any further questions, feel free to write some comments below.

Configuring Scopes in Azure Active Directory (Part 2)

ockamey — Mon, 08 Jun 2020 08:06:07 +0000

Intro

Welcome to the second part of my tutorial about scopes in Azure Active Directory. During the first part, I described the basics about scopes e.g. how to get a token that contains specific scopes or how to add scopes into your application. You can find a link to it here.
In this part, I'll cover how to complete more advanced features or setup features that you don't normally configure on a daily basis. If you haven't looked at the first part of my tutorial, I highly recommend doing it because in this part I'll continue working on the applications that have already been created. In addition, I'll sometimes briefly mention procedures that are expanded upon in more detail in the first part. E.g. the first request required for getting a token means "sending GET request in your browser", and a second request means "sending POST request to exchange the authorization code for a token".
Let's begin once again from approving consent scopes.

Administrator only consent scopes - another way to approve

There is another way that an administrator can give consent to a scope. If the Global Administrator clicks the link below:

https://login.microsoftonline.com/{tenant_id}/adminconsent?client_id={client_id}

They'll be redirected to another consent view, and after giving consent, the status of the scope should change to green. Bear in mind that in place of {tenant_id} in the above link you need to place your Tenant ID and similarly in place of {client_id}, the Client ID of your ClientApp should be placed.
The outcome will be the same as clicking the button "Grant consent for …" as I presented in the "Scopes that only Administrators can consent to" section in the first part.

It's also possible to enable users to send a request to the administrator, requesting them to Grant permission using the build-in flow. In order to turn on this feature, you need to go to:

Your Azure Active Directory instance -> Enterprise applications -> User settings -> set "Users can request admin consent to apps they are unable to consent to" to Yes.

After the administrator who will receive requests to their email is selected, the window stating that administrator approval is required will change slightly, as can be seen below:

Manifest

There is another way to create scopes. If you go to:

Your Azure Active Directory instance -> App registration -> BooksCollectionApp -> Manifest

You'll see the following Manifest file, it's in JSON format and contains the whole configuration of your application. In this JSON there is an oauth2Permissions array, underlined below, which contains all scopes in your application. You can easily create scopes by just adding items to the array, it must be remembered, that every single scope needs to have a unique property id and you can use any kind of GUID generator to generate this id. Below it can be seen how the Books.Read scope is set out in the BooksCollectionApp manifest.

Authorized Client Applications

In the "Expose an API" view there is another feature, apart from Scopes definitions, that I'd like to cover here. This feature is called "Authorized Client Applications", which is found below the table of scopes:

To analyze this feature, let's create another scope in the BooksCollectionApp (bear in mind that this process is contained within the BooksCollectionApp, not in the ClientApp):

Now let's add in an authorized client application, you do this by clicking the "Add a client application" button in the "Expose an API" view. As can be seen below, you need to paste the ClientApp's Client ID into the Client ID input and then tick the box: Books.ReadWrite.

And click the "Add application" button.

Please note, you should wait a couple of minutes before trying to get the token. After waiting a few minutes, send the request to obtain an Authorization Code in your browser, be sure to use the Books.ReadWrite scope and the ClientApp's Client ID and Client Secret. It can be seen that the consent window didn't show up at all, even though this action was performed for the first time. While not being apparently obvious, you were redirected to the localhost and provided with an Authorization Code immediately. This is the main idea of this feature. As long as you trust the BooksCollectionApp, and the BooksCollectionApp trusts the ClientApp (by adding it to the Authorized client applications), thus, there was no need to show you the consent view. It was made in a more granular way, meaning enabling specific scopes for the ClientApp but not all of them.

I have discovered the following: when you add any scope in the "Authorized client applications" section, then you can't get a scope that requires administrator consent for a user. To display this, leave "Authorized client applications" with the Books.ReadWrite scope ticked, and try to get a token which specifies the Books.Read.All scope in the request. You should receive an error message which states that you need to be provided with admin consent. Once you remove the scope Books.ReadWrite from the "Authorized client applications", you'll once again be able to get the token.

Disabling the option that allows users to consent

If you'd like to disable the future user from being able to give consent in your organization. You can read Microsoft's recommendations here.

To carry out the above, go to:

Your Azure Active Directory instance -> Enterprise applications -> User settings -> set "Users can consent to apps accessing company data on their behalf" to No.

As below:

To see this feature in action, one additional scope in the BooksCollectionApp should be added:

Fill in the inputs like above and click the "Add scope" button. Let's try to get a new token, using the new scope, firstly compose the Authorization Code request and copy this from the Postman to your browser:

After sending the request, the consent window should look like below:

Now you can see, despite the fact that the scope is set for admins and users, only a Global Administrator can give consent to the ClientApp. Since a regular user can't, the only way to allow regular users to get a token containing the specific scope is to add the application and scope to the "Authorized client applications" as found in the "Authorized Client Applications" section. This option gives the owner of the BooksCollectionApp control over which applications can have access to which scopes.
Note that we have seen this feature in action, to continue this tutorial switch "Users can consent to apps accessing company data on their behalf" back to "Yes". Please note, it can take a while to make this particular option work properly, in my case it took about 10min.

Prompt Query Parameter

After you give consent to a scope, the consent window won't pop up again, asking you to give your consent, a second time for the same scope. To force AAD to show a user the consent window every single time, you have to add one additional query parameter into the first request, the parameter's name is prompt. Go ahead and send the same request from your browser as in the example provided at the beginning of the first part tutorial with the modification that is shown below. Another important consideration, is that you shouldn't have any Authorized client application scopes in the BooksCollectionApp.

As you may have probably noticed, every single time you send the request you receive the consent window, even though you have consented already earlier.
There are a few different options for the prompt parameter, these include, e.g.: login, none and select_account. You can read about them here.

Display names

While creating scopes, you should know that you need to provide display names and descriptions for the scope (actually, only the display name and description for administrators are required). The display name and description for users are displayed on the regular consent window. The administrator’s display name and description will only show up when the administrator grants consent for the client's app using the following link:

https://login.microsoftonline.com/{tenant_id}/adminconsent?client_id={client_id}

If you'd like more information on the granting consent by following a link process, you'll find it in the section "Administrator only consent scopes - another way to approve".

Scopes in Authorization Endpoint V1 and V2

In the "API permission" view we didn't have to add any scopes to our client's application that didn't require administrator consent, because we used Azure AD V2 Authorization Endpoint, instead we specified them in the request's query parameters (dynamic consent). If we had used V1, we would have had to specify all scopes in the "Api permission" view (static consent) instead of in the request's query parameter, this is because in V1 there is a resource query parameter (where you add Application URI or Client ID), not the scope query parameter. You can find more information by clicking the following link.

Client Credentials flow

In the Client Credentials flow, in comparison to the Authorization Code flow, a user can't be present, therefore, this flow is popular in the case of service to service connections (e.g. One Azure Function sends a request to a different Azure Function). In order to obtain an access token, only one request is required. On the screen below, you can find the details of the request:

As you may have probably noticed, this request is similar to the JWT exchange request, not only is it a POST request, it also has the /token endpoint. The two main differences are shown above, in the grant_type parameter Client Credentials flow can be easily seen. What about Scopes? I'll give a detailed explanation below.

In case of the Client Credentials flow scopes aren't possible, this is because it is not feasible for a user to be able to give consent, this is especially because, as was mentioned before, there is no user in this flow. It must be mentioned, however, that a scope parameter is required in a request, so in order to comply with this rule, the value of the scope parameter should be either {{Application ID URI}}/.default or {{Resource application ClientID}}/.default.
If you decide to send the above request and decode the access token using e.g. https://jwt.ms, you'll discover that there is actually no "scp" claim at all, because it's not relevant in this scenario.
In the next article I'll explain Roles in the Azure Active Directory, these will be able to be assigned to both applications and users, that being said, they can be visible in the JWT for both cases.

More than one scope

There is a possibility to specify more than one scope, in the scope parameter in the request you can add another scope by inserting a space between them. If you look closely you can see this below:

The space is the separator between scopes, however, they must be from the same application e.g. https://bookscollectionapp.com. You'll receive an error message if you specify more than one scope from different applications:

Client ID instead of Application ID URI

Whenever you send a scope in the request, there is another way to specify the resource application. Up until now, we have always used {{Application ID URI}}/{{scope}} pattern, but instead of providing the Application ID URI we can just use {{Resource application ClientID}}/{{scope}}. So in our case, the first request should look like below:

Bear in mind that in your case, the value of the BooksCollectionApp Client ID must equal your BooksCollectionApp Client ID. Using this approach has one consequence that comes to my mind. If you exchange the Authorization Code for the JWT, and decode it (I've shown how to obtain it in the first part of the tutorial), it should be apparent, that instead of the Application ID URI in the "aud" claim, you'll see your Resource Client ID in your token. Below you can find the specific fragment of my access token:

Summary

We've now finished the second part of my scope tutorial. In the next coming weeks, I'm going to release a similar tutorial to this one which will cover Roles in Azure Active Directory. I hope that scopes are now more familiar to you than at the beginning of the tutorial. If you have any further questions feel free to write some comments below.

Configuring Scopes in Azure Active Directory (Part 1)

ockamey — Mon, 20 Apr 2020 17:12:44 +0000

Intro

When I started learning Azure Active Directory, I was pretty overwhelmed by the Microsoft documentation, which in my opinion was pretty complicated (especially for people who don’t have much experience at configuring any OAuth Authorization Servers — like me). Since I’ve spent a lot of time reading Microsoft documents, blogs, and have experimented by myself and with my teammates (thanks Tim!), I’d like to share with you what I’ve learned about AAD during this time.

I’ve always been a big fan of the “Example first” way. Using this idea, I’m going to walk you through some examples and, hopefully, after reading this tutorial, you can approach Microsoft Documentation fearlessly.

This article assumes that you already have a good understanding of OAuth 2.0, especially Authorization Code flow. If you don’t, I highly recommend you watch this great video:

Here is the OAuth terminology that will be used throughout this tutorial.

I also assume that you have your own tenant in Azure and it’s associated with the valid subscription. If not, you can find tutorials how to do it here and here.

Throughout this tutorial I’ll be using only Azure AD Endpoint V2, however, in one section I’ll add in some basic differences between V1 and V2.

Creating applications

First, we’ll create two applications in AAD, that will represent both Client and Resource Applications. You can do this by following these steps:

Your Azure Active Directory instance -> App registration -> New registration:

You need to fill in the Name textbox and the Redirect URI as shown on the screenshot below (you can provide different names, of course, but I suggest using the same ones, because I’ll use these during this tutorial):

The same requirement needs to be completed for the Resource Application. Here is the screenshot below:

We’ve created two applications in AAD (these are neither WebService nor Azure Function applications and so on — both are only representations of physical applications in AAD):

ClientApp — this application represents the application that communicates with the user directly (e.g. ASP.NET application) and acts on behalf of the User when communicating with the BooksCollectionApp.
BooksCollectionApp — this application represents the Resource Application that may have sensitive information belonging to the User (e.g. WEB API contains User’s data).

Creating scopes

Now, let’s create scopes. To do this, let’s first go to the details of the BooksCollectionApp in App Registrations. Next, select Expose an API, then click the “Add a scope” button.

When you click this button for the first time, you should see a new window stating that you need to add an “Application ID URI” before proceeding. Let’s assign a URI that will represent your application (like Domain Name). I’ve used https://bookscollectionapp.com. You can pick any valid URI, that’s unique across your tenant; you don’t need to buy a domain.

Next fill in the panel like below:

It means that this scope is meant for everybody, not only for administrators. These administrators won’t have to give consent to enable this scope for users (I’ll explain it better later on). Both the Display name and the Description input above, will be shown on the consent page while getting JWT.

Getting access token

Now let’s use Postman to get a token which will contain the scope created above. Normally, a web app or mobile app would redirect you to log-in to the Microsoft website to receive an Authorization Code. Then the app would exchange the Authorization Code for a JWT. Exchange for a JWT only occurs during Authorization Code flow. To keep things simple and to better understand, we won’t build an app, we’ll just use Postman.

In order to get a JWT, there will be two stages:

1. Getting an Authorization Code

During this stage, we actually don’t need Postman at all, only a browser. However, I use Postman to generate URLs that are copied and pasted to a browser later.

To create a GET request like in the screen below, you need to paste your Tenant ID in the black box. I’ve changed my Tenant ID to black in the hope that you won’t hack me :D. Second, change the client_id value to your ClientApp Client ID. Then, change the scope value in a way that replicates the following:
{{your BooksCollectionApp Application ID URI}}/Books.Read

You can find your Client ID and Tenant ID in the Overview of your application in the Application Registration panel.

Following on, copy the link from the Postman (the one that is underlined in red above) to your browser. After sending the request, you should be able to see the following screen:

The consent view shows the user what the ClientApp will be able to do on behalf of them.

Next, press accept and you should be redirected to https://localhost:44327/signin-oidc, and in the query parameter code your Authorization Code will be contained:

https://localhost:44237/signin-oidc?code=AQABAAIAAAAm-06blBE1TpVMil8KPQ41DmEwZFwyAM06SoXS0-M0oC2oKw85100IlRqALFCc8x3_XbOql3smPubHvda7WBiUNRIAxYnnCRWj7WBXD0QGK-1xDtuBxzCauxKd5N9ZEEKv_vn4I4x4tC6EsU7SlH81Abmlxw8njiHtuVszhQiRonSP7xLubXYvJ0MEvit_YExvfx0EkPPQh1nZlN8KQwde05zIvXvpgHFqyw1QxH52bs7bgFGauhFBnd8tn1iwmE74BKLufGOwCtBT4dqhpTK17s49s-FzRckDeKGQJouD758Pf0qsyTzdIUNst2rWNk2A7IL_Hv_BX1vb9T_KCpyzphPre7iVCLJdm3cGNrYUzVVUFwMrOPBWyHtsdei8Zf4BJqFYSFvVBs5Xa6CSuDWfVy0HVWJlTYnSRUBz6hFYsgP4sAlrMpT4IAA&session_state=c67ad588-c6b5-4419

Copy the code, but be careful not to press Shift + End because there is one more query parameter at the very end.

2. Exchanging Authorization code for an access token (JWT)

The next step is to exchange the access code for JWT. We must send a POST request from Postman as shown in the screenshot below. The value of {{client_id}} is the ClientApp’s Client ID. You can generate the {{client_secret}} by going to “Certificates & secrets” in the ClientApp view, and {{tenant_id}} is your Tenant ID. You can take advantage of the Environments feature in Postman, the same as what I’ve used. During the last step you must insert your Authorization code in place of “HERE PASTE YOUR AUTHORIZATION CODE”.

After clicking the Send button, your response should resemble below:

After generating your Client Secret, it may take some time to propagate the changes, thus, if you receive the error that states the Client Secret value is invalid, you should consider sending the request again in about 1–2min.

Copy the value of the access_token property (it’s a JWT), ensuring not to include the quotation marks, and paste the token at https://jwt.ms. Now you should be able to see that your token has been decoded. The parts you should focus on are the “aud”, “appid” and “scp” properties. Below, you can see some parts of my token (I’ve removed parts of it for security reasons):

The “aud” claim is the abbreviation for Audience and its value is the BooksCollectionApp’s Application ID URI — AAD takes the Application ID URI from the scopes parameter from the first request. The “appid” is the ClientApp’s Client ID. The “scp” above is the space separated scope (there can be more than one value). As you can see, the scope is exactly the same value that we had previously used in our BooksCollectionApp.

This means that when the ClientApp (e.g. ASP.NET application) passes our token to the BooksCollectionApp (e.g. WEB API), the BooksCollectionApp knows that it shouldn’t allow the ClientApp to perform any other action than reading the user’s books. The ClientApp, on behalf of us, won’t be able to write anything to the BooksCollectionApp. This can only happen if we trust the BooksCollectionApp to follow the scopes provided in your token.

An alternative way to get an access token from Postman

In the previous section, I showed you how to get an access token using Postman, however, there is actually an easier and quicker way to receive it from there. If you select any request in Postman, you’ll be able to see an Authorization tab, like in the screen below:

In order to get JWT from AAD, you should select OAuth 2.0 from the type menu and click the “Get New Access Token” button. After the pop-up window has appeared, you’ll need to fill in the inputs as shown in the screen below:

After accomplishing the above, click the “Request Token” button. A new window will pop up, containing the consent view. If it’s accepted, the Access Token input in the request will be filled in with the desired JWT. Please be advised, if you ask for the same scope as in the previous section, you won’t get the consent view, because you’ll have already given consent for this scope.
The result of the above will be the same as the method described in the previous section, but if something goes wrong (e.g. if you pass a wrong parameter), this method won’t provide you with many details about the error. Taking everything into consideration, this is why I prefer the explicit (previous) flow.
One important thing that should be remembered is the following difference between Auth URL and Access Token URL. These are both similar, but not the same. The first endpoint points to the function of actually getting the Authorization Code, and the second one points to the function of exchanging the Authorization Code for JWT.

Scopes that only Administrators can consent to

Now, let’s create a different scope that requires administrator’s consent. Return to the BooksCollectionApp and to the “Expose an API” panel and add a new scope (make sure to select “Admins only” in the “Who can consent option”).

Let’s now try to get a new token using the new scope:

You should probably get the token without any problems; you might ask yourself why? Since it’s been changed so that only administrators can consent! The answer to your possible question is that you are probably a Global Administrator. In order to get a better idea of this option, you should be a regular User. If you don’t have any regular users in your tenant, you can add them in by creating a new one by going to:

Your tenant -> Users -> All users -> New user.

After completing the above, let’s now try getting an Authorization Code by logging in as a regular user. After logging in as a regular user you should see the view below:

This means that the user wants to use the admin only scope. We’ve created the scope Book.Read.All for this reason, it means that everybody who uses the scope, will also be able to read all users books (not just the logged-in user’s books), of course, only if the physical application is implemented in this way. In a real scenario, the Owner of the ClientApp (the Owner is the person who has created the application — you can see the list of owners in the Owners panel contained within your application) should ask a Global Administrator to give consent, if the ClientApp needs to use this scope. In order to allow an administrator to give consent, the Owner must go to the ClientApp and add the scope to the API Permissions panel. Let’s go ahead and do this.

Go to:
ClientApp in App Registrations -> ClientApp -> API permissions -> Add a permission -> My API’s -> BooksCollectionApp -> Delegated permissions -> Check “Books.Read.All”. As below:

As you may have noticed, there are two different types of permissions: Delegated and Application. When thinking about scopes, these are Delegated permissions. Application permissions are App Roles which contains an Application allowed member type (I’ll write a similar tutorial for App Roles in the future). After the scope has been added, you should see the table below:

In a real case scenario, the Owner of the ClientApp should ask the Global Administrator to grant permission to the ClientApp application, this can be done by clicking the button “Grant admin consent for…”. The Global Administrator, after validating the request, should click “Grant admin consent for…” button, giving consent for the application. In our case the button “Grant admin consent for…” only needs to be clicked. After completing this, the following should be visible below:

Once again, let’s try to get a token as a regular user. If you have copied everything provided in this tutorial correctly, you will be presented with the JWT which contains the Books.Read.All scope.

Hold on, how was I able to get the token with the proper scope without the consent view showing up?! This has happened because you’re not an administrator and as it has been shown previously, this specific scope requires Administrator Consent to obtain. At first, it may be a little bit confusing, especially because the purpose of scopes is to show the user what the Client can do on behalf of them and now there is no consent view, however, there is logic behind this concept. The scope requires administrator consent and it must be remembered that you don’t have administrator privileges. It took me some time to clarify this and I recommend you to go over this section a few times to ensure it’s clear :D.

Now in your JWT there should be more than one scope, as can be seen below:

Summary

I hope that this tutorial has helped you better understand Scopes in Azure Active Directory. It hasn’t comprehensively covered everything required to understand all details related to scopes. In the next coming weeks, I plan to release the second part of this tutorial, which includes more features that you can perform with Scopes. In the meantime, if you have any questions feel free to get in touch with messages and comments below.