Edit

Share via

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

Minimize risks of credential exposure when configuring this policy. Microsoft recommends that you use more secure authentication methods if supported by your backend, such as managed identity authentication or credential manager. If you configure sensitive information in policy definitions, we recommend using named values and storing secrets in Azure Key Vault.

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

Usage notes

  • We recommend configuring key vault certificates to manage certificates used to secure access to backend services.
  • If you configure a certificate password in this policy, we recommend using a named value.

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 content

For more information about working with policies, see: