Validate client certificate
validate-client-certificate policy to enforce that a certificate presented by a client to an API Management instance matches specified validation rules and claims such as subject or issuer for one or more certificate identities.
To be considered valid, a client certificate must match all the validation rules defined by the attributes at the top-level element and match all defined claims for at least one of the defined identities.
Use this policy to check incoming certificate properties against desired properties. Also use this policy to override default validation of client certificates in these cases:
- If you have uploaded custom CA certificates to validate client requests to the managed gateway
- If you configured custom certificate authorities to validate client requests to a self-managed gateway
For more information about custom CA certificates and certificate authorities, see How to add a custom CA certificate in Azure API Management.
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.
<validate-client-certificate validate-revocation="true | false" validate-trust="true | false" validate-not-before="true | false" validate-not-after="true | false" ignore-error="true | false"> <identities> <identity thumbprint="certificate thumbprint" serial-number="certificate serial number" common-name="certificate common name" subject="certificate subject string" dns-name="certificate DNS name" issuer-subject="certificate issuer" issuer-thumbprint="certificate issuer thumbprint" issuer-certificate-id="certificate identifier" /> </identities> </validate-client-certificate>
|validate-revocation||Boolean. Specifies whether certificate is validated against online revocation list. Policy expressions aren't allowed.||No||
|validate-trust||Boolean. Specifies if validation should fail in case chain cannot be successfully built up to trusted CA. Policy expressions aren't allowed.||No||
|validate-not-before||Boolean. Validates value against current time. Policy expressions aren't allowed.||No||
|validate-not-after||Boolean. Validates value against current time. Policy expressions aren't allowed.||No||
|ignore-error||Boolean. Specifies if policy should proceed to the next handler or jump to on-error upon failed validation. Policy expressions aren't allowed.||No||
|identities||Add this element to specify one or more
|serial-number||Certificate serial number.||No||N/A|
|common-name||Certificate common name (part of Subject string).||No||N/A|
|subject||Subject string. Must follow format of Distinguished Name.||No||N/A|
|dns-name||Value of dnsName entry inside Subject Alternative Name claim.||No||N/A|
|issuer-subject||Issuer's subject. Must follow format of Distinguished Name.||No||N/A|
|issuer-certificate-id||Identifier of existing certificate entity representing the issuer's public key. Mutually exclusive with other issuer attributes.||No||N/A|
- Policy sections: inbound
- Policy scopes: global, workspace, product, API, operation
- Gateways: dedicated, consumption, self-hosted
The following example validates a client certificate to match the policy's default validation rules and checks whether the subject and issuer name match specified values.
<validate-client-certificate validate-revocation="true" validate-trust="true" validate-not-before="true" validate-not-after="true" ignore-error="false"> <identities> <identity subject="C=US, ST=Illinois, L=Chicago, O=Contoso Corp., CN=*.contoso.com" issuer-subject="C=BE, O=FabrikamSign nv-sa, OU=Root CA, CN=FabrikamSign Root CA" /> </identities> </validate-client-certificate>
For more information about working with policies, see: