Protect a web API backend in Azure API Management using OAuth 2.0 authorization with Azure Active Directory

In this article, you'll learn how to configure your Azure API Management instance to protect an API, by using the OAuth 2.0 protocol with Azure Active Directory (Azure AD).

You can configure authorization for developer accounts using other OAuth 2.0 providers. For more information, see How to authorize developer accounts using OAuth 2.0 in Azure API Management.

Note

This feature is available in the Developer, Basic, Standard, and Premium tiers of API Management.

You can follow every step below in the Consumption tier, except for calling the API from the developer portal.

Prerequisites

Prior to following the steps in this article, you must have:

  • An API Management instance
  • A published API using the API Management instance
  • An Azure AD tenant

Overview

Overview graphic to visually conceptualize the following flow.

  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 in the developer portal 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.

1. Register an application in Azure AD to represent the API

Using the Azure portal, protect an API with Azure AD by registering an application that represents the API in Azure AD.

For details about app registration, see Quickstart: Configure an application to expose a web API.

  1. In the Azure portal, 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 backend-app.
    • In the Supported account types section, select an option that suits your scenario.
  4. Leave the Redirect URI section empty.

  5. Select Register to create the application.

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

  7. Under the Manage section of the side menu, select Expose an API and set the Application ID URI with the default value. Record this value for later.

  8. Select the Add a scope button to display the Add a scope page:

    1. Enter a new Scope name, Admin consent display name, and Admin consent description.
    2. Make sure the Enabled scope state is selected.
  9. Select the Add scope button to create the scope.

  10. Repeat steps 8 and 9 to add all scopes supported by your API.

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

2. Register another application in Azure AD to represent a client application

Register every client application that calls the API as an application in Azure AD. In this example, the client application is the developer console in the API Management developer portal.

To register another application in Azure AD to represent the Developer Console:

  1. In the Azure portal, 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.

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

  7. Create a client secret for this application to use in a subsequent step.

    1. Under the Manage section of the side menu, select Certificates & secrets.
    2. Under Client secrets, select New client secret.
    3. Under Add a client secret, provide a Description and choose when the key should expire.
    4. Select Add.

When the secret is created, note the key value for use in a subsequent step.

3. Grant permissions in Azure AD

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

  1. In the Azure portal, 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.

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

  5. Select Delegated Permissions, then select the appropriate permissions to your backend-app.

  6. Select Add permissions.

Optionally:

  1. Navigate to your client app's API permissions page.

  2. Select Grant admin consent for <your-tenant-name> to grant consent on behalf of all users in this directory.

4. Enable OAuth 2.0 user authorization in the Developer Console

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, you enable OAuth 2.0 user authorization in the developer console (the client app).

  1. In the Azure portal, find the Authorization endpoint URL and Token endpoint URL and save them for later.

    1. Open the App registrations page.
    2. Select Endpoints.
    3. Copy the OAuth 2.0 Authorization Endpoint and the OAuth 2.0 Token Endpoint.
  2. Browse to your API Management instance.

  3. Under the Developer portal section in the side menu, select OAuth 2.0 + OpenID Connect.

  4. Under the OAuth 2.0 tab, select Add.

  5. Provide a Display name and Description.

  6. For the Client registration page URL, enter a placeholder value, such as http://localhost.

    • The Client registration page URL points to a page where users create and configure their own accounts supported by OAuth 2.0 providers.
    • We use a placeholder, since, in this example, users do not create and configure their own accounts.
  7. For Authorization grant types, select Authorization code.

  8. Specify the Authorization endpoint URL and Token endpoint URL you saved earlier:

    1. Copy and paste the OAuth 2.0 Authorization Endpoint into the Authorization endpoint URL text box.
    2. Select POST under Authorization request method.
    3. Enter the OAuth 2.0 Token Endpoint, and paste it into the Token endpoint URL text box.
      • If you use the v1 endpoint:
        • Add a body parameter named resource.
        • Enter the back-end app Application ID for the value.
      • If you use the v2 endpoint:

    Important

    While you can use either v1 or v2 endpoints, we recommend using v2 endpoints.

  9. Specify the client app credentials:

    • For Client ID, use the Application ID of the client-app.
    • For Client secret, use the key you created for the client-app earlier.
  10. Make note of the Redirect URI for the authorization code grant type.

  11. Select Create.

  12. Return to your client-app registration.

  13. Under Manage, select Authentication.

  14. Under Platform configurations:

    • Click on Add a platform.
    • Select the type as Web.
    • Paste the redirect URI you saved earlier under Redirect URIs.
    • Click on Configure button to save.

    Now that the developer console can obtain access tokens from Azure AD via your OAuth 2.0 authorization server, 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.

  15. Browse to your API Management instance, and go to APIs.

  16. Select the API you want to protect. For example, Echo API.

  17. Go to Settings.

  18. Under Security:

    1. Choose OAuth 2.0.
    2. Select the OAuth 2.0 server you configured earlier.
  19. Select Save.

Note

To see the latest configuration of your portal, publish the portal. You can publish the portal in the portal's administrative interface or from the Azure portal.

5. Successfully call the API from the developer portal

Note

This section does not apply to the Consumption tier, as it does not support the developer portal.

Once you've configured your OAuth 2.0 authorization server and configured your API to use that server, you can test it by going to the developer portal and calling an API.

  1. Select Developer portal in the top menu from your Azure API Management instance Overview page.

  2. Browse to any operation under the API in the developer portal.

  3. Select Try it to bring you to the developer console.

  4. Note a new item in the Authorization section, corresponding to the authorization server you just added.

  5. Select Authorization code from the authorization drop-down list.

    Select Authorization code authorization

  6. Once prompted, sign into the Azure AD tenant.

    • If you are already signed into the account, you might not be prompted.
  7. After successful sign-in, an Authorization header is added to the request, with an access token from Azure AD. The following is an abbreviated sample token (Base64 encoded):

    Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
    
  8. Select Send to call the API successfully.

6. Configure a JWT validation policy to pre-authorize requests

So far:

  • You've tried to make a call from the developer console.
  • You've been prompted and have signed into the Azure AD tenant.
  • The developer console obtains an access token on your behalf, and includes the token in the request made to the API.

However, what if someone calls your API without a token or with an invalid token? For example, if you call the API without the Authorization header, the call will still go through, since API Management does not validate the access token. It simply passes the Authorization header to the back-end API.

Pre-authorize requests in API Management with the Validate JWT policy, by validating the access tokens of each incoming request. If a request does not have a valid token, API Management blocks it.

The following example policy, when added to the <inbound> policy section, checks the value of the audience claim in an access token obtained from Azure AD, and returns an error message if the token is not valid.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <required-claims>
        <claim name="aud">
            <value>{backend-api-application-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Note

The above openid-config URL corresponds to the v2 endpoint. For the v1 openid-configendpoint, use https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Tip

Find the {aad-tenant} value as your Azure AD tenant ID in the Azure portal, either on:

  • The overview page of your Azure AD resource, or
  • The Manage > Properties page of your Azure AD resource.

For information on how to configure policies, see Set or edit policies.

Build an application to call the API

In this guide, you used the developer console in API Management as the sample client application to call the Echo API protected by OAuth 2.0. To learn more about how to build an application and implement OAuth 2.0, see Azure AD code samples.

Next steps