<authentication> of <clientCertificate> Element

Article
09/15/2021

Specifies authentication behaviors for client certificates used by a service.

<configuration>
  <system.serviceModel>
    <behaviors>
      <serviceBehaviors>
        <behavior>
          <serviceCredentials>
            <clientCertificate>
              <authentication>

Syntax

<authentication customCertificateValidatorType="namespace.typeName, [,AssemblyName] [,Version=version number] [,Culture=culture] [,PublicKeyToken=token]"
                certificateValidationMode="ChainTrust/None/PeerTrust/PeerOrChainTrust/Custom"
                includeWindowsGroups="Boolean"
                mapClientCertificateToWindowsAccount="Boolean"
                revocationMode="NoCheck/Online/Offline"
                trustedStoreLocation="CurrentUser/LocalMachine" />

Attributes and Elements

The following sections describe attributes, child elements, and parent elements

Attributes

Attribute	Description
customCertificateValidatorType	Optional string. A type and assembly used to validate a custom type. This attribute must be set when `certificateValidationMode` is set to `Custom`.
certificateValidationMode	Optional enumeration. Specifies one of the modes used to validate credentials. This attribute is of the X509CertificateValidationMode type. If set to X509CertificateValidationMode.Custom, then a `customCertificateValidator` must also be supplied. The default is X509CertificateValidationMode.ChainTrust.
includeWindowsGroups	Optional Boolean. Specifies if Windows groups are included in the security context. Setting this attribute to `true` has a performance impact, as it results in a full group expansion. Set this attribute to `false` if you do not need to establish the list of groups a user belongs to.
mapClientCertificateToWindowsAccount	Boolean. Specifies whether the client can be mapped to a Windows identity using the certificate. Active Directory must be enabled to do this.
revocationMode	Optional enumeration. One of the modes used to check for a revoked certificate lists (RCL). The default is `Online`. This value is ignored when using HTTP transport security.
trustedStoreLocation	Optional enumeration. One of the two system store locations: `LocalMachine` or `CurrentUser`. This value is used when a service certificate is negotiated to the client. Validation is performed against the Trusted People store in the specified store location. The default is `CurrentUser`.

customCertificateValidatorType Attribute

Value	Description
String	Specifies the type name and assembly and other data used to find the type.

certificateValidationMode Attribute

Value	Description
Enumeration	One of the following values: None, PeerTrust, ChainTrust, PeerOrChainTrust, Custom. For more information, see Working with Certificates.

revocationMode Attribute

Value	Description
Enumeration	One of the following values: NoCheck, Online, Offline. For more information, see Working with Certificates.

trustedStoreLocation Attribute

Value	Description
Enumeration	One of the following values: `LocalMachine` or `CurrentUser`. The default is `CurrentUser`. If the client application is running under a system account then the certificate is typically under `LocalMachine`. If the client application is running under a user account then the certificate is typically in `CurrentUser`.

Child Elements

None.

Parent Elements

Element	Description
<clientCertificate>	Defines an X.509 certificate used to authenticate a client to a service.

Remarks

The <authentication> element corresponds to the X509ClientCertificateAuthentication class. It enables you to customize how clients are authenticated. You can set the certificateValidationMode attribute to None, ChainTrust, PeerOrChainTrust, PeerTrust, or Custom. By default, the level is set to ChainTrust, which specifies that each certificate must be found in a hierarchy of certificates ending in a root authority at the top of the chain. This is the most secure mode. You can also set the value to PeerOrChainTrust, which specifies that self-issued certificates (peer trust) are accepted as well as certificates that are in a trusted chain. This value is used when developing and debugging clients and services because self-issued certificates need not be purchased from a trusted authority. When deploying a client, use the ChainTrust value instead.

You can also set the value to Custom. When set to the Custom value, you must also set the customCertificateValidatorType attribute to an assembly and type used to validate the certificate. To create your own custom validator, you must inherit from the abstract X509CertificateValidator class. For more information, see How to: Create a Service that Employs a Custom Certificate Validator.

Example

The following code specifies an X.509 certificate and a custom validation type in the <authentication> element.

<serviceBehaviors>
  <behavior name="myServiceBehavior">
    <clientCertificate>
      <certificate findValue="www.cohowinery.com"
                   storeLocation="CurrentUser"
                   storeName="TrustedPeople"
                   x509FindType="FindByIssuerName" />
      <authentication customCertificateValidatorType="MyTypes.Coho"
                      certificateValidationMode="Custom"
                      revocationMode="Offline"
                      includeWindowsGroups="false"
                      mapClientCertificateToWindowsAccount="true" />
    </clientCertificate>
  </behavior>
</serviceBehaviors>

Share via