Retrieve a Certificate by Id in APIM Policy

Question

I have a policy that is generating a JWT token based on a private key certificate. I have placed the certificate in APIM using a reference to it from Key Vault. In the policy though I can only retrieve the certificate using it's thumbprint. However, the thumbprint will change when the certificate in Key Vault is rotated. Which means I have to update the thumbprint used in the policy by using a named value pointing to another Key Vault secret. It would be so much easier to implement the retrieval of APIM certificates using the Id rather than the thumbprint.

In my policy I have to do it this way:

string certificateId = "CERTIFICATETHUMBPRINT";

if (!context.Deployment.Certificates.TryGetValue(certificateId, out var certificate))

{

throw new Exception($"Certificate for Oracle not found. Available certificates: {string.Join(", ", context.Deployment.Certificates.Keys)}");

}

But would be great if I could do something like this:

var certificate = context.Deployment.Certificates["CertificateId"];

Answer 1

Hello Warren Kinley, Thanks for reaching out on Microsoft Q&A and really appreciate your patience while we looked into this.

Currently, APIM policies do not support retrieving certificates by Key Vault Id. The context.Deployment.Certificates dictionary only allows access via the certificate thumbprint. So the approach you suggested (context.Deployment.Certificates["CertificateId"]) is not supported.

However, there are established workarounds to handle certificate rotation more gracefully:

1. Use a Named Value for Thumbprint
   • Create a named value in APIM, e.g., OracleCertThumbprint, containing the certificate thumbprint.
   • Reference the named value in your policy:

           <set-variable name="certificateThumbprint" value="{{OracleCertThumbprint}}" />
     

           string certificateId = context.Variables.GetValueOrDefault<string>("certificateThumbprint");
           context.Deployment.Certificates.TryGetValue(certificateId, out var certificate);
     

     Pros: Keeps your policy code unchanged.
     Cons: You need to update the named value when the certificate rotates.
2. Automate Thumbprint Update
   • Set up an Azure Function, Logic App, or Azure Automation to:
   • Detect Key Vault certificate rotation.
   • Retrieve the new thumbprint.
   • Update the APIM named value automatically.
   • This makes your policy “rotation-proof.”
3. Direct Key Vault Access in Policy (Advanced)
   • You could use <send-request> to fetch the certificate from Key Vault at runtime.
   • Requires APIM managed identity with Key Vault access.
   • Adds latency and complexity, so generally not recommended.

Recommendation:

The best practice is to continue using thumbprints with a named value and automate its update upon Key Vault rotations. This avoids hardcoding thumbprints in your policy and keeps your JWT token generation resilient to certificate changes.

References:

• Certificates in API Management Policies
• Named Values in APIM
• Key Vault Certificate Rotation

Hope the above helps! Thank you.