Authenticate with client certificate
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: dedicated, 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
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
Feedback
Submit and view feedback for