Product Documentation

Configuring Client Authentication

Dec 20, 2017

In a typical SSL transaction, the client that is connecting to a server over a secure connection checks the validity of the server by checking the server's certificate before initiating the SSL transaction. In some cases, however, you might want to configure the server to authenticate the client that is connecting to it.

With client authentication enabled on an SSL virtual server, the NetScaler appliance asks for the client certificate during the SSL handshake. The appliance checks the certificate presented by the client for normal constraints, such as the issuer signature and expiration date.

Note: For the appliance to verify issuer signatures, the certificate of the CA that issued the client certificate must be installed on the appliance and bound to the virtual server that the client is transacting with.

If the certificate is valid, the appliance allows the client to access all secure resources. But if the certificate is invalid, the appliance drops the client request during the SSL handshake.

The appliance verifies the client certificate by first forming a chain of certificates, starting with the client certificate and ending with the root CA certificate for the client (for example, VeriSign). The root CA certificate may contain one or more intermediate CA certificates (if the client certificate is not directly issued by the root CA).

Before you enable client authentication on the NetScaler appliance, make sure that a valid client certificate is installed on the client. Then, enable client authentication for the virtual server that will handle the transactions. Finally, bind the certificate of the CA that issued the client certificate to the virtual server on the appliance .

Note: A NetScaler MPX appliance supports a certificate-key pair size from 512 to 4096 bits. The certificate must be signed by using one of the following hash algorithms:

  • MD5
  • SHA-1
  • SHA-224
  • SHA-256
  • SHA-384
  • SHA-512

On an SDX appliance, if an SSL chip is assigned to a VPX instance, the certificate-key pair size support of an MPX appliance applies. Otherwise, the normal certificate-key pair size support of a VPX instance applies.

A NetScaler virtual appliance (VPX instance) supports certificates of at least 512 bits, up to the following sizes:

  • 4096-bit server certificate on the virtual server
  • 4096-bit client certificate on the service
  • 4096-bit CA certificate
  • 4096-bit certificate on the physical server
  • 4096-bit client certificate (if client authentication is enabled on the virtual server)

Providing the Client Certificate

Before you configure client authentication, a valid client certificate must installed on the client. A client certificate includes details about the specific client system that will create secure sessions with the NetScaler appliance. Each client certificate is unique and should be used by only one client system.

Whether you obtain the client certificate from a CA, use an existing client certificate, or generate a client certificate on the NetScaler appliance, you must convert the certificate to the correct format. On the NetScaler, certificates are stored in either the PEM or DER format and must be converted to PKCS#12 format before they are installed on the client system. After converting the certificate and transferring it to the client, system, make sure that it is installed on that system and configured for the client application that will be part of the SSL transactions (for example, the web browser).

For instructions on how to convert a certificate from PEM or DER format to PKCS#12 format, see Converting SSL Certificates for Import or Export.

For instructions on how to generate a client certificate, see Generating a Test Certificate.

Enabling Client-Certificate Based Authentication

By default, client authentication is disabled on the NetScaler appliance, and all SSL transactions proceed without authenticating the client. You can configure client authentication to be either optional or mandatory as part of the SSL handshake.

If client authentication is optional, the NetScaler requests the client certificate but proceeds with the SSL transaction even if the client presents an invalid certificate. If client authentication is mandatory, the NetScaler terminates the SSL handshake if the SSL client does not provide a valid certificate.

Caution: Citrix recommends that you define proper access control policies before changing client-certificate-based authentication check to optional.
Note: Client authentication is configured for individual SSL virtual servers, not globally.

To enable client-certificate based authentication by using the command line interface

At the command prompt, type the following commands to enable the client-certificate-based authentication and verify the configuration:

  • set ssl vserver <vServerName> [-clientAuth (ENABLED | DISABLED)] [-clientCert (MANDATORY | OPTIONAL)]
  • show ssl vserver <vServerName>

Example

 
> set ssl vserver vssl -clientAuth ENABLED -clientCert Mandatory 
 Done 
> show ssl vserver vssl 
 
        Advanced SSL configuration for VServer vssl: 
        DH: DISABLED 
        Ephemeral RSA: ENABLED          Refresh Count: 0 
        Session Reuse: ENABLED          Timeout: 120 seconds 
        Cipher Redirect: DISABLED 
        SSLv2 Redirect: DISABLED 
        ClearText Port: 0 
        Client Auth: ENABLED    Client Cert Required: Mandatory 
        SSL Redirect: DISABLED 
        Non FIPS Ciphers: DISABLED
        SNI: DISABLED
        OCSP Stapling: DISABLED
        HSTS: DISABLED
        HSTS IncludeSubDomains: NO
        HSTS Max-Age: 0 
        SSLv2: DISABLED SSLv3: ENABLED  TLSv1.0: ENABLED TLSv1.2: ENABLED  TLSv1.2: ENABLED 
 
1)      CertKey Name: sslckey   Server Certificate 
 
1)      Policy Name: client_cert_policy  Priority: 0 
 
1)      Cipher Name: DEFAULT 
        Description: Predefined Cipher Alias 
 Done 

To enable client-certificate based authentication by using the configuration utility

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
  2. In the SSL Parameters section, select Client Authentication, and in the Client Certificate list, select Mandatory.

Note

If client authentication is set to mandatory and if the client certificate contains policy extensions, certificate validation fails. From release 12.0-56.x, you can set a parameter in the front-end SSL profile to skip this check. The parameter is disabled by default. That is, the check is performed by default.

To skip the policy extension check during client authentication by using the NetScaler CLI

At the command prompt, type:

set ssl profile ns_default_ssl_profile_frontend -clientauth ENABLED -skipClientCertPolicyCheck ENABLED

Parameter

skipClientCertPolicyCheck

              Control policy extension check, if present inside the X509 certificate chain. Applicable only if client authentication is enabled and client certificate is set to mandatory. Possible values functions as follows:

- ENABLED: Skip the policy check during client authentication.

- DISABLED: Perform policy check during client authentication.

Possible values: ENABLED, DISABLED

Default: DISABLED

To skip the policy extension check during client authentication by using the NetScaler GUI

  1. Navigate to System > Profiles > SSL Profiles.
  2. Create a new front-end profile or edit an existing front-end profile.
  3. Verify that client authentication is enabled and client certificate is set to mandatory.
  4. Select Skip Client Certificate Policy Check.
localized image

Binding CA Certificates to the Virtual Server

A CA whose certificate is present on the NetScaler appliance must issue the client certificate used for client authentication. You must bind this certificate to the NetScaler virtual server that will carry out client authentication.

You must bind the CA certificate to the SSL virtual server in such a way that the NetScaler can form a complete certificate chain when it verifies the client certificate. Otherwise, certificate chain formation fails and the client is denied access even if its certificate is valid.

You can bind CA certificates to the SSL virtual server in any order. The NetScaler forms the proper order during client certificate verification.

For example, if the client presents a certificate issued by CA_A, where CA_A is an intermediate CA whose certificate is issued by CA_B, whose certificate is in turn issued by a trusted root CA, Root_CA, a chain of certificates that contain all three of these certificates must be bound to the virtual server on the NetScaler.

For instructions on binding one or more certificates to the virtual server, see Binding the Certificate-key Pair to the SSL Based Virtual Server.

For instructions on creating a chain of certificates, see Creating a Chain of Certificates.