Protect an API by using OAuth 2.0 with Azure Active Directory and API Management

A screenshot of a social media post Description automatically generated
Share on facebook
Share on twitter
Share on linkedin

This is a direct copy of the official Microsoft documentation that you can see here. My goal here is to include some clarifications and images to ease the process. This is a bit of a tedious process and you will need to do each step meticulously and paying attention to detail.

Overview

These are the steps we are going to go through:

  1. Register an application (backend-app) in Azure AD to represent the API.
  2. Register another application (client-app) in Azure AD to represent a client application that needs to call the API.
  3. In Azure AD, grant permissions to allow the client-app to call the backend-app.
  4. Configure the Developer Console to call the API using OAuth 2.0 user authorization.
  5. Add the validate-jwt policy to validate the OAuth token for every incoming request.

In order to achieve our goal, we are going to register (create) two Apps in Azure Active directory. That means we are going to go through the Azure App Registration process twice. The first time to configure our backend app that will represent the API and the next time will be to setup the client app for that backend. Then we will configure the APIM to consume our app.

Note: You need to have the right permissions in order to be able to access the Active Directory management.1. Register an application (backend-app) in Azure AD to represent the API.

To protect an API with Azure AD, the first step is to register an application in Azure AD that represents the API.

  1. Go to the Azure portal to register your application.
  2. Go to the Azure Active Directory option from the sidebar. Then search for and select APP registrations. Select New registration.

A screenshot of a cell phoneDescription automatically generated A screenshot of a cell phoneDescription automatically generated

  1. When the Register an application page appears, enter your application’s registration information:
    • In the Name section, enter a meaningful application name that will be displayed to users of the app, such as backend-app.
    • In the Supported account types section, select an option that suits your scenario.
  2. Leave the Redirect URI section empty.
  3. Select Register to create the application.

A picture containing screenshotDescription automatically generated

  1. On the app Overview page, find the Application (client) ID value and record it for later. A screenshot of a cell phoneDescription automatically generated
  2. Select Expose an API and set the Application ID URI with the default value. Record this value for later.

A screenshot of a cell phoneDescription automatically generated A screenshot of a cell phoneDescription automatically generated

  1. Select the Add a scope button to display the Add a scope page. Then create a new scope that’s supported by the API (for example, User.Read). Finally, select the Add scope button to create the scope. Repeat this step to add all scopes supported by your API.

A screenshot of a social media postDescription automatically generated

  1. When the scopes are created, make a note of them for use in a subsequent step.

A screenshot of a cell phoneDescription automatically generated

2. Register another application (client-app) in Azure AD to represent a client application that will call the API.

Every client application that calls the API needs to be registered as an application in Azure AD as well. In this example, the client application is the Developer Console in the API Management developer portal. Here’s how to register another application in Azure AD to represent the Developer Console.

  1. Go to the Azure portal to register your application. Search for and select APP registrations.
  2. Select New registration.
  3. When the Register an application page appears, enter your application’s registration information:
    • In the Name section, enter a meaningful application name that will be displayed to users of the app, such as client-app.
    • In the Supported account types section, select Accounts in any organizational directory (Any Azure AD directory – Multitenant).
  4. In the Redirect URI section, select Web and leave the URL field empty for now.
  5. Select Register to create the application.

A screenshot of a cell phoneDescription automatically generated

  1. On the app Overview page, find the Application (client) ID value and record it for later.

A screenshot of a cell phoneDescription automatically generated

Now, create a client secret for this application to use in a subsequent step.

  1. Go to Certificates & secrets and select New client secret.

A screenshot of a cell phoneDescription automatically generated

  1. Under Add a client secret, provide a Description. Choose when the key should expire, and select Add.

A screenshot of a cell phoneDescription automatically generated

When the secret is created, note the key value for use in a subsequent step. Copy the new client secret value. KEEP IT IN A SAFE PLACE! You won’t be able to retrieve it after you perform another operation or leave the current screen. A screenshot of a social media postDescription automatically generated

3. In Azure AD, grant permissions to allow the client-app to call the backend-app.

Now that you have registered two applications to represent the API and the Developer Console, you need to grant permissions to allow the client-app to call the backend-app.

  1. Go to the Azure portal to grant permissions to your client application. Search for and select APP registrations.
  2. Choose your client app. Then in the list of pages for the app, select API permissions.
  3. Select Add a Permission.

A close up of a mapDescription automatically generated

  1. Under Select an API, select My APIs, and then find and select your backend-app.

A screenshot of a social media postDescription automatically generated

  1. Under Delegated Permissions, select the appropriate permissions to your backend-app, then select Add permissions.

A screenshot of a social media postDescription automatically generated

  1. Optionally, on the API permissions page, select Grant admin consent for <your-tenant-name> to grant consent on behalf of all users in this directory.

A screenshot of a social media postDescription automatically generated

4. Configure the Developer Console to call the API using OAuth 2.0 user authorization.

At this point, you have created your applications in Azure AD, and have granted proper permissions to allow the client-app to call the backend-app.

In this example, the Developer Console is the client-app. The following steps describe how to enable OAuth 2.0 user authorization in the Developer Console.

  1. In Azure portal, browse to your API Management instance.
  2. Select OAuth 2.0 > Add.

A screenshot of a mapDescription automatically generated

  1. Provide a Display name and Description.
  2. For the Client registration page URL, enter a placeholder value, such as http://localhost. The Client registration page URL points to a page that users can use to create and configure their own accounts for OAuth 2.0 providers that support this. In this example, users do not create and configure their own accounts, so you use a placeholder instead.
  3. For Authorization grant types, select Authorization code.
  4. Specify the Authorization endpoint URL and Token endpoint URL. Retrieve these values from the Endpoints page in your Azure AD tenant. Browse to the App registrations page again, and select Endpoints.
  5. Copy the OAuth 2.0 Authorization Endpoint, and paste it into the Authorization endpoint URL text box. Select POST under Authorization request method.
  6. Copy the OAuth 2.0 Token Endpoint, and paste it into the Token endpoint URL text box.

A screenshot of a social media postDescription automatically generated

  1. If you use v1 endpoints, add a body parameter named resource. For the value of this parameter, use Application ID of the back-end app.
  2. If you use v2 endpoints, use the scope you created for the backend-app in the Default scope field. Also, make sure to set the value for the accessTokenAcceptedVersion property to 2 in your application manifest and make sure to include the backend app id when adding the scope, for example: 28e621fb-78fd-4aee-9e7c-b8e10aed0848/User.Read
  3. Next, specify the client credentials. These are the credentials for the client-app.
  4. For Client ID, use the Application ID of the client-app.

A screenshot of a cell phoneDescription automatically generated

  1. For Client secret, use the key you created for the client-app earlier.

A screenshot of a cell phoneDescription automatically generated

  1. Immediately following the client secret is the redirect_url for the authorization code grant type. Make a note of this URL.

A picture containing birdDescription automatically generated

  1. Select Create.

A screenshot of a cell phoneDescription automatically generated A screenshot of a cell phoneDescription automatically generated A screenshot of a cell phoneDescription automatically generated

  1. Go back to your client-app registration in Azure Active Directory and select Authentication.
  2. Under Platform configurations click on Add a platform, and select the type as Web, paste the redirect_url under Redirect URI, and then click on Configure button to save.

A screenshot of a social media postDescription automatically generated

Now that you have configured an OAuth 2.0 authorization server, the Developer Console can obtain access tokens from Azure AD.

The next step is to enable OAuth 2.0 user authorization for your API. This enables the Developer Console to know that it needs to obtain an access token on behalf of the user, before making calls to your API.

  1. Browse to your API Management instance, and go to APIs.
  2. Select the API you want to protect. For example, Echo API.
  3. Go to Settings.
  4. Under Security, choose OAuth 2.0, and select the OAuth 2.0 server you configured earlier.
  5. Select Save.

A screenshot of a social media postDescription automatically generated

Successfully call the API from the developer portal

Now that the OAuth 2.0 user authorization is enabled on your API, the Developer Console will obtain an access token on behalf of the user, before calling the API.

  1. Browse to any operation under the API in the developer portal, and select Try it. This brings you to the Developer Console.
  2. Note a new item in the Authorization section, corresponding to the authorization server you just added.
  3. Select Authorization code from the authorization drop-down list, and you are prompted to sign in to the Azure AD tenant. If you are already signed in with the account, you might not be prompted.
  4. After successful sign-in, an Authorization header is added to the request, with an access token from Azure AD. The following is a sample token (Base64 encoded):
  5. Select Send to call the API successfully.

You can validate your JWT using this page https://jwt.io/

A screenshot of a social media postDescription automatically generated

5. Add the validate-jwt policy to validate the OAuth token for every incoming request.

At this point, when a user tries to make a call from the Developer Console, the user is prompted to sign in. The Developer Console obtains an access token on behalf of the user, and includes the token in the request made to the API.

A screenshot of a cell phoneDescription automatically generated A screenshot of a social media postDescription automatically generated

However, what if someone calls your API without a token or with an invalid token? For example, try to call the API without the Authorization header, the call will still go through. The reason is that API Management does not validate the access token at this point. It simply passes the Authorization header to the back-end API.

Use the Validate JWT policy to pre-authorize requests in API Management, by validating the access tokens of each incoming request. If a request does not have a valid token, API Management blocks it. For example, add the following policy to the <inbound> policy section of the Echo API. It checks the audience claim in an access token, and returns an error message if the token is not valid. For information on how to configure policies, see Set or edit policies.

I hope you have found this article useful, thanks for your time and I hope you keep reading. If you happen to have any question just @ me on twitter. Good luck.

Did you like the post and would like to leave a reply? You can mention me on twitter @eatskolnikov so we can have a conversation about it

Share it with your friends

Share on facebook
Share on twitter
Share on linkedin

Want to get these post in your inbox?

Type your email down here and you will get a weekly digest of the post here

Other articles on the site

core

Handling Excel Files with NPOI

NPOI is a library for working with Office documents like Word and Excel. I mainly been using it for reading and writing Excel files so that’s what I’m going to write about. It works with .csv and .xlsx formats and is based on the Apache POI project for Java. It

Read More »