How to use customer identity and access management (CIAM) with Azure API Management

Background introduction

Microsoft Entra ID for customers is Microsoft’s new customer identity and access management (CIAM) solution designed for businesses that want to make applications available to their customers, using the Microsoft Entra platform for identity and access.

With the introduction of this feature, Microsoft Entra ID now offers a customer tenant, which is a new type of tenant that represents your customer-facing app, resources, and directory of customer accounts. A customer tenant is distinct and separate from your workforce tenant.

Microsoft Entra ID Customer Tenants is still in preview (see: Supported features in customer tenants - Microsoft Entra External ID | Microsoft Learn and Plan CIAM deployment - Microsoft Entra External ID | Microsoft Learn), but authorization token can already be used with Azure API Management (APIM).

Scenario

A consumer application uses Microsoft Entra AD to get an authorization token. The token is passed to APIM in the headers of the HTTP request and validated through a "validate-azure-ad-token" inbound policy.

=> The request is failing with a 401 Unauthorized status code.

Understanding the failure

We proceed to collect an APIM inspector trace to confirm the error obtained.

Analyzing the trace logs for the call, we can verify that the error is due to an "Issuer is not valid" error while executing API policy "validate-azure-ad-token".

We confirmed that the token being sent to APIM trace can be decoded to:  

    "iss": " https://00044076-b4b5-4404-b01f-00ee0c08e825.ciamlogin.com/00044076-b4b5-4404-b01f-00ee0c08e825/"

And we verified the exception on the policy to be due to an Invalid Issuer.

Exception: IDX40001: Issuer: 'https://00044076-b4b5-4404-b01f-00ee0c08e825.ciamlogin.com/00044076-b4b5-4404-b01f-00ee0c08e825/', does not match any of the valid issuers provided for this application.

Setting up a solution

The token endpoints and issuers used by the Microsoft Entra ID customer tenants differ from the Microsoft Entra ID workforce tenants (Tokens and claims overview - Microsoft identity platform | Microsoft Learn), which is the cause for the error we are facing on the “validate-azure-ad-token” policy.

Every Microsoft Entra ID tenant publishes a standards-compliant well-known metadata. This document contains information about the issuer name, the authentication and authorization endpoints, supported scopes and claims. For customer tenants, the document is publicly available at: https://{tenantname}.ciamlogin.com/{tenantid}/v2.0/.well-known/openid-configuration. This endpoint returns an issuer value https://{tenantname}.ciamlogin.com/{tenantid}/v2.0".

Example: 

well-known metadata

Currently the “validate-azure-ad-token” policy does not accept CIAM tenants, but we expect this situation to change once these tenant are out of preview.

As an alternative, we can implement an equivalent "validate-jwt" policy on the APIM service (Protect API in API Management using OAuth 2.0 and Microsoft Entra ID - Azure API Management | Microsoft Learn), which is a more flexible policy to enforce the  existence and validity of a supported JSON web token (JWT). In summary, this is an example for the resulting "validate-jwt" policy (Azure API Management policy reference - validate-jwt | Microsoft Learn) defined on your APIM service:

validate-jwt policy

To allow the calling application to obtain a valid v2.0 token, we must correctly configure the manifest property on the CIAM tenant (under App Registrations > Affected App >> Manifest), to “accessTokenAcceptedVersion”: 2

Example:

manifest

This allows us to obtain the v2.0 token required by APIM.

decoded token

We should note that the "aud" claim in v2 tokens is always the Client ID of the resource API, as documented here: Access token claims reference - Microsoft identity platform | Microsoft Learn.

Also in v2 tokens the "appId" claim is no longer present, and the "azp" claim should be used in its place:

azp claim