Authenticate with client certificate

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 (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

• Policy sections: inbound
• Policy scopes: global, workspace, product, API, operation
• Gateways: classic, v2, consumption, self-hosted

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" />

Related policies

• Authentication and authorization

Related content

For more information about working with policies, see:

• Tutorial: Transform and protect your API
• Policy reference for a full list of policy statements and their settings
• Policy expressions
• Set or edit policies
• Reuse policy configurations
• Policy snippets repo
• Author policies using Microsoft Copilot for Azure