Use AAD and OAuth 2.0 to access the API managed by Azure API Management

5 min readApr 22, 2021

--

Architect Azure API Management service | A Clockwork Engineer (olcay.dev)

Here is the completed official document : Protect a web API backend in Azure API Management by using OAuth 2.0 authorization with Azure AD

What is AAD?

Azure Active Directory (Azure AD) is Microsoft’s cloud-based identity and access management service, which helps your employees sign in and access resources in external resource like Microsoft 365, Azure or another SaaS and internal resource such as apps on your corporate network and intranet, along with any cloud apps developed by your own organization which enable AAD authentication.

What is OAuth?

The OAuth authorization framework enables a third-party
application to obtain limited access to an HTTP service and describe the authentication mechanism.

OAuth defines four roles, include resource owner, resource server, client
and authorization server.

RFC 6749 — The OAuth 2.0 Authorization Framework (ietf.org)

The client requests access to resources controlled by the resource owner and hosted by the resource server. In OAuth, Instead of using the resource owner’s credentials to access protected resources, the client obtains an access token from authorization server with the approval of the resource owner to access the protected resource hosted by the resource server.

Methods to get access tokens from the authorization server are called grants. The same method used to request a token is also used by the resource server to validate a token.

The four basic grant types are Authorization Code, Implicit, Resource Owner Credentials and Client Credentials.

Let’s do it!

Set up App Registration

Through register an app in AAD so the Microsoft identity platform can provide authentication and authorization services for your application and its users.

New an app in AAD, In Azure portal, browse to your Azure Active Director and select New Registration

Leave the URL field empty for now

Note the Client ID on Overview and new the Client Secret on Certificate & secrets

Navigate to Expose an API to Add a scope

(Scope setting would be required at using v2 endpoint)

Remember the Scopes for later used

Get Endpoints from Overview section

Enable OAuth 2.0 in APIM

In your APIM resource and click OAuth 2.0 + OpenID Connect under Developer portal section to create a OAuth2 service.

Specify OAuth 2.0 authorization endpoint (v2), OAuth 2.0 token endpoint (v2), Client ID and Client Secret you noted form previous step.

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

Select POST under Authorization request method

Add default scope got from app registration

Note the Authorization code grant under Redirect URI section

Set Redirect URI for App Registration

Navigate to Authentication and set the Redirect URIs
(Redirect to APIM developer portal when access success)

Fill in the Redirect URI you get last step.

If forget, you also can get the Redirect URI from APIM > OAuth2.0 + OpenID connect > OAuth 2.0 > {OAuth name} > Redirect URI

Finished

Remember to enable Access tokens (used for implicit flows) from Authentication

Navigate to Mainfest and modify “accessTokenAcceptedVersion” from “null” to “2”

Setting APIs policy

https://docs.microsoft.com/en-us/azure/api-management/set-edit-policies

Use OAuth Server

Add code as below to policy inbound section

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

Summary

Now that the OAuth 2.0 user authorization is enabled on your API.

Browse to any operation under the API in the developer portal, and select Try it. Select Authorization code from the authorization drop-down list, and you are prompted to sign in to the Azure AD tenant.