TL;DR

In this post, I highlight recently enhanced capabilities of the Validate JWT policy in Azure API Management and the specific gap that addresses for customers. I also provide related recommendations, tips and policy samples, which are not as yet available in Microsoft documentation.

Validate JWT policy

The Validate JWT API Management policy has been around for a while, supporting validation of JWT tokens signed with either HS256 (symmetric) or RS256 (asymmetric) algorithms. From a security view point, use of the RS256 algorithm over HS256 is generally preferred, as it requires use of separate keys to sign (private key) and validate (public key) tokens. Only the public key needs to be distributed to applications, that want to validate these tokens e.g. the API Management Validate JWT policy in question here. Till recently, with RS256 signed tokens, there was only one way to make the public key available to the policy, by using Open ID Connect Discovery endpoint.

Option - Open ID Connect Discovery endpoint

In this option, the policy requires an Open ID Connect Discovery endpoint to be specified via an openid-config element. API Management expects to browse this endpoint when evaluating the policy, including JSON Web Key URLs in the response, to discover the public key modulus (n) and exponent (e) pair, which will be used for validating incoming RS256 JWT tokens.

In my opinion, this is still the best option, as sourcing the public key from a remote endpoint like this, allows the public/private keys to be rotated, without having to update the Validate JWT policy.

Gap

This option remains unavailable for customers, that either do not have an Open ID Discovery endpoint or have one that is not usable. We have seen this for customers that have custom OAuth solutions, without Open ID Connect Discovery endpoints in place. Or if they have one, a lot of extra work needs to be done to make it resilient and provide API Management a line of sight to it.

Long Term Solution

Most of our customers that are in this situation, are typically early in the cloud adoption journey and have not yet consolidated their Identity and Access Management (IDAM) capabilities onto mature platforms like Azure AD, OKTA etc., which provide global, highly available Open ID Connect Discovery endpoints out of the box. Once they reach this point, it becomes the long term solution, for use with this policy.

Intermediate Solution

The recently released configuration options, provide a way out in the interim, by allowing 2 additional ways to supply the public key to the Validate JWT policy.

Option - Certificate (new)

In this option, the policy can reference a certificate uploaded to Azure API Management, via the certificate-id attribute. For reference, see upload a certificate

Option - Modulus/Exponent (n/e) pair (new)

In this option, the policy can directly reference the token issuer's public key modulus and exponent (n/e) pair in-line via attributes. These are not secrets, so it is safe to have these inline and source controlled.

Azure Portal Tip

At the time of writing, the API Management service in Azure portal does not seem to render the policy correctly when used with new options. After saving the policy, it seems to return to default/blank value, even though, under the hood the policy has been correctly applied. This is likely a bugfix/feature yet to be released. Until then, to be sure what policy has taken effect, you can query the underlying Azure resource definition, via the Azure Portal ('Settings --> Export Template' tab in API Management instance) or Resource Explorer. Alternatively, you can query the policy directly via the Azure PowerShell module Get-AzApiManagementPolicy

Conclusion

As you have seen, use of Open ID Discovery endpoint, with the Azure API Management Validate JWT policy, still remains the best (and recommended) option for validating RSA JWT tokens. However, the recently released options provide a way forward for customers that are unable to do so, without imposing heavy technical and operational burden.

Hopefully you find the insights on scenarios, samples and tips I shared above useful. I will be contributing these samples to API Management repository.