Solving Azure API Management OAuth Unauthorized Exception when Using OAuth Version 2.0

According to Microsoft documentation, to protect an API using OAuth 2.0 with Azure active directory and API management, you need to follow these steps:

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.

You can find all of these steps described in details in this link: Protect an API by using OAuth 2.0 with Azure Active Directory and API Management.

The problem that I encountered occurred after doing all configuration steps and while I was trying to invoke an operation from this API using the developer portal, where I received an HTTP 401 error that the action is unauthorized!

This error was received from APIM validate-JWT policy which validates the sent bearer token in the authorization header attribute, but the actual exception is:

IDX10205: Issuer validation failed

There is a quick solution for this error. It is through configuring the APIM OAuth to use OAuth V1.0 endpoints (authorize and token end points) instead of V2.0 endpoints.

But on reading the actual exception, it simply advises you that the issuer validation has failed. This means that the problem was created from registered apps in the Active Directory; either the client APP or the backend APP or both, and it has failed to validate the token.

After some reading in Microsoft documentation, I found a magical solution!

The problem lies in the fact that AD app registration doesn’t accept the token with version 2.0 format while the default version format is 1.0.

So, to configure app registration for accepting the token version, follow these steps in both registered apps (client app and backend app):

1. Go to Azure Active Directory >> App registration >> click Client app.
2. From the client app blade, click Manifest.
3. According to Microsoft docs, the application manifest contains a definition of all the attributes of an application object in the Microsoft identity platform. It also serves as a mechanism for updating the application object. Here is a link for the full docs: Azure Active Directory app manifest
4. Find a key named “accessTokenAcceptedVersion”. Ensure that the value of the key is “null” so the accepted token version is v1.0 by default (check the below image).

5. Change the value of the “accessTokenAcceptedVersion” from “null” value to “2” (the possible values are 1 or 2, or null to keep using the default access token version)
6. Save the manifest file and repeat all above steps in your backend app registration as well.
7. Try any API operation and it will work perfectly! 

Note: Validate-JWT policy in APIM returns the exception which you stated in the “failed-validation-error-message” attribute. To receive the actual exception, you can simply return the exception message in a custom http header, or in the message body itself. Just use <on-error> in APIM and the context variable to receive the exception will be as in the below image (I used a custom http header named: ActualExcpetion)

Hope this information is useful for you.