Merge pull request #124688 from FlorentATo/issue-124686

doc: [124686] Specify SHA-1 thumbprint

Author: v-dirichards

articles/api-management/validate-client-certificate-policy.md

@@ -54,11 +54,11 @@ For more information about custom CA certificates and certificate authorities, s
 
 | Name                            | Description      | Required |  Default    |
 | ------------------------------- | -----------------| -------- | ----------- |
-| validate-revocation  | Boolean. Specifies whether certificate is validated against online revocation list. Policy expressions aren't allowed.  | No  | `true`  |
-| 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 | `true` |
-| validate-not-before | Boolean. Validates value against current time. Policy expressions aren't allowed.| No | `true` |
-| validate-not-after  | Boolean. Validates value against current time. Policy expressions aren't allowed.| No | `true`|
-| 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 | `false` |
+| validate-revocation | Boolean. Specifies whether certificate is validated against online revocation list. Policy expressions aren't allowed. | No  | `true`  |
+| 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 | `true` |
+| validate-not-before | Boolean. Validates value against current time. Policy expressions aren't allowed.| No| `true` |
+| validate-not-after | Boolean. Validates value against current time. Policy expressions aren't allowed.| No| `true`|
+| 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 | `false` |
 
 ## Elements
 
@@ -70,27 +70,24 @@ For more information about custom CA certificates and certificate authorities, s
 
 | Name                            | Description      | Required |  Default    |
 | ------------------------------- | -----------------| -------- | ----------- |
-| thumbprint | Certificate thumbprint. | No | N/A |
+| thumbprint | Certificate SHA-1 thumbprint. | No | N/A |
 | 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, which consists of comma-separated name attributes, for example, *"CN=MyName, OU=MyOrgUnit, C=US..."*.| 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, which consists of comma-separated name attributes, for example, *"CN=MyName, OU=MyOrgUnit, C=US..."*. | No | N/A |
-| issuer-thumbprint | Issuer thumbprint. | 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 |
+| issuer-subject | Issuer's subject. Must follow format of Distinguished Name. | No | N/A |
+| issuer-thumbprint | Issuer SHA-1 thumbprint. | 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 |
+
 
 ## Usage
 
 - [**Policy sections:**](./api-management-howto-policies.md#understanding-policy-configuration) inbound
 - [**Policy scopes:**](./api-management-howto-policies.md#scopes) global, workspace, product, API, operation
 - [**Gateways:**](api-management-gateways-overview.md) classic, v2, consumption, self-hosted, workspace
 
+## Examples
 
-### Usage notes
-
-* You must use double quotes to enclose values of name attributes in the `subject` and `issuer-subject` attributes when they contain certain special characters such as ",". For example, specify `O="Contoso, Inc."` instead of `O=Contoso, Inc.` for the organization name. [Learn more](/windows/win32/api/wincrypt/nf-wincrypt-certnametostra#remarks)
-
-## Example
 
 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.
 
@@ -109,6 +106,25 @@ The following example validates a client certificate to match the policy's defau
 </validate-client-certificate> 
 ```
 
+The following example performs a stricter validation by cheking whether the subject thumbprint and the issuer thumbprint match specified values.
+
+```xml
+<validate-client-certificate 
+    validate-revocation="true" 
+    validate-trust="true" 
+    validate-not-before="true" 
+    validate-not-after="true" 
+    ignore-error="false">
+    <identities>
+        <identity
+            thumbprint="AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00"
+            issuer-thumbprint="BB22CC33DD44EE55FF66AA77BB88CC99DD00EE11" />
+    </identities>
+</validate-client-certificate> 
+```
+
+
+
 ## Related policies
 
 * [Authentication and authorization](api-management-policies.md#authentication-and-authorization)