Protecting Your APIs in Azure API Management using OAuth - A Step-by-Step Tutorial

Introduction to Azure API Management and OAuth

Azure API Management is a fully managed service that assists in creating, publishing, and managing APIs for your applications. It offers various tools and features to ensure your APIs are secure, scalable, and user-friendly.

On the other hand, OAuth is an open standard for authorization, enabling third-party applications to access your APIs securely without sharing user credentials. By employing OAuth, you can provide granular access to your APIs, ensuring that only authorized users and applications can access your protected resources.

OAuth Workflow

In an OAuth workflow, the client does not use the username and password to access the backend API. Instead, the client uses an access token obtained from the identity provider. This involves passing the client ID and client secret to the identity provider to secure the access token. The client then passes this access token to API management. If the access token is valid, the request is served; otherwise, it is denied.

Step-by-Step Demonstration

Prerequisites

You will need below resources created in Azure to follow this tutorial:

1. An Azure API Management Service.
2. A simple API Azure function, which returns a simple JSON response message.

We will be fronting this backend API with Azure API Management and protect it using OAuth.

Registering Client Applications

First, we need to register the client applications. Navigate to Azure Active Directory in app registration.

We’ll need to register two applications:

1. The first application represents Azure API Management. Let’s name it “apim-resource”. Register the application and leave everything to default.

2. Next, set the Application ID URI in the ‘Expose an API’ section and create some App Roles.

# Example of App Roles
{"allowedMemberTypes": ["Application"],"description": "Read messages","displayName": "Reader","id": "32028ccd-3212-4f39-3212-e6b3c34334d0","isEnabled": true,"lang": null,"origin": "Application","value": "Reader"}

In our case, we are simply reading the message, so we’ll set it to “Reader”. These role details will be passed to the backend API as part of your access token.

3. The second application represents the actual client, let’s name it “APIM User”. Register this application and leave everything to default.

4. Assign permissions to our backend API on the APIM resource application. We’ll give it “Reader” access.

Obtaining Access Tokens

To obtain an access token, we’ll pass the client ID and the client secret to the identity provider (in our case, Azure Active Directory).

To obtain the client secret:

1. Go to “Certificates & secrets” under the ‘APIM User’ application.
2. Click on ”+ New client secret”.
3. Add a description and choose an expiry period. Then click “Add”.
4. Make sure to copy the secret because you won’t be able to see it again.

We also need to give access to Microsoft Graph:

1. Go to “API permissions” and click ”+ Add a permission”.
2. Search for “Microsoft Graph” and add the required permissions.

Configuring API Management

Having obtained the client ID and secret, and given access to Microsoft Graph, we can now configure Azure API Management.

To protect this API using OAuth, go to the “Design” section of the API in APIm and in the “Inbound Policy” block, add the following policy:

<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/{tenant}/v2.0/.well-known/openid-configuration" />
    <required-claims>
        <claim name="aud">
            <value>api://{value}</value>
        </claim>
    </required-claims>
</validate-jwt>

Now, let’s break down the above policy:

1. The “validate-jwt” policy validates the JWT token passed in the request header. If the token is valid, the request is served; otherwise, it is denied.
2. The “openid-config” element specifies the OpenID configuration endpoint. This endpoint is used to obtain the public key to validate the JWT token.
3. The “required-claims” element specifies the claims that must be present in the JWT token. In our case, we are checking for the “aud” claim, which represents the audience. The audience is the resource that the token is intended for. In our case, it is the backend API.

Testing the API

Get Access Token:

curl --location 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={clientId}' \
--data-urlencode 'client_secret={clientSecret}' \
--data-urlencode 'scope=api://{resourceId}/.default'

Pass the access token as Bearear token in the request header:

curl -X GET \
  https://your-api-management-url/your-api-endpoint \
  -H 'Authorization: Bearer your-access-token'