Edit

Authenticate with client certificate

  • Article

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 (resource name).

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 the 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: