Authenticate with client certificate

  • Article

APPLIES TO: All API Management tiers

Use the authentication-certificate policy to authenticate with a backend service using a client certificate. When the certificate is installed into API Management first, identify it first by its thumbprint or certificate ID (resourcename).

Caution

If the certificate references a certificate stored in Azure Key Vault, identify it using the certificate ID. When a key vault certificate is rotated, its thumbprint in API Management will change, and the policy will not resolve the new certificate if it is identified by thumbprint.

Note

Set a policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

<authentication-certificate thumbprint="thumbprint" certificate-id="resource name" body="certificate byte array" password="optional password"/>

Attributes

Attribute Description Required Default
thumbprint The thumbprint for the client certificate. Policy expressions are allowed. Either thumbprint or certificate-id can be present. N/A
certificate-id The certificate resource name. Policy expressions are allowed. Either thumbprint or certificate-id can be present. N/A
body Client certificate as a byte array. Use if the certificate isn't retrieved from the built-in certificate store. Policy expressions are allowed. No N/A
password Password for the client certificate. Policy expressions are allowed. Use if certificate specified in body is password protected. N/A

Usage

Examples

Client certificate identified by the certificate ID

<authentication-certificate certificate-id="544fe9ddf3b8f30fb490d90f" />

Client certificate identified by thumbprint

<authentication-certificate thumbprint="CA06F56B258B7A0D4F2B05470939478651151984" />

Client certificate set in the policy rather than retrieved from the built-in certificate store

<authentication-certificate body="@(context.Variables.GetValueOrDefault<byte[]>("byteCertificate"))" password="optional-certificate-password" />

Next steps

For more information about working with policies, see: