Product Documentation
ADC
Current Release 13.0 12.1
View PDF

Client certificate authentication

May 2, 2023
Contributed by: 
S C

Websites that contain sensitive content, such as online banking websites or websites with employee personal information, sometimes require client certificates for authentication. To configure authentication, authorization, and auditing to authenticate users based on client-side certificate attributes, you first enable client authentication on the traffic management virtual server and bind the root certificate to the authentication virtual server. Then, you implement one of two options. You can configure the default authentication type on the authentication virtual server as CERT, or you can create a certificate action that defines what the NetScaler must do to authenticate users based on a client certificate. In either case, your authentication server must support CRLs. You configure the ADC to extract the user name from the SubjectCN field or another specified field in the client certificate.

When the user tries to log on to an authentication virtual server for which an authentication policy is not configured, and a global cascade is not configured, the user name information is extracted from the specified field of the certificate. If the required field is extracted, the authentication succeeds. If the user does not provide a valid certificate during the SSL handshake, or if the user name extraction fails, authentication fails. After it validates the client certificate, the ADC presents a logon page to the user.

The following procedures assume that you have already created a functioning authentication, authorization, and auditing configuration, and therefore they explain only how to enable authentication by using client certificates. These procedures also assume that you have obtained your root certificate and client certificates and have placed them on the ADC in the /nsconfig/ssl directory.

Configure client certificate authentication

To configure the authentication, authorization, and auditing client certificate parameters by using the command line interface

At the command prompt, type the following commands, in the order shown, to configure the certificate and verify the configuration:

add ssl certKey <certkeyName> -cert <certFile> -key <keyFile> -password -inform <inform> -expiryMonitor <expiryMonitor> -notificationPeriod <notificationPeriod>

bind ssl certKey [<certkeyName>] [-ocspResponder <string>] [-priority <positive_integer>]

show ssl certKey [<certkeyName>]

set aaa parameter -defaultAuthType CERT

show aaa parameter

set aaa certParams -userNameField "Subject:CN"

show aaa certParams
<!--NeedCopy-->

To configure the authentication, authorization, and auditing client certificate parameters by using the configuration utility

  1. Navigate to Security > AAA - Application Traffic > Virtual Servers.
  2. In the details pane, select the virtual server that you want to configure to handle client certificate authentication, and then click Edit.
  3. On the Configuration page, under Certificates, click the right arrow (>) to open the CA Cert Key installation dialog.
  4. In the CA Cert Key dialog box, click Insert.
  5. In the CA Cert Key - SSL Certificates dialog box, click Install.
  6. In the Install Certificate dialog box, set the following parameters, whose names correspond to the CLI parameter names as shown:
    • Certificate-Key Pair Name*—certkeyName
    • Certificate File Name—certFile
    • Key File Name—keyFile
    • Certificate Format—inform
    • Password—password
    • Certificate Bundle—bundle
    • Notify When Expires—expiryMonitor
    • Notification Period—notificationPeriod
  7. Click Install, and then click Close.
  8. In the CA Cert Key dialog box, in the Certificate list, select the root certificate.
  9. Click Save.
  10. Click Back to return to the main configuration screen.
  11. Navigate to Security > AAA - Application Traffic > Policies > Authentication > CERT.
  12. In the details pane, select the policy you want to configure to handle client certificate authentication, and then click Edit.
  13. In the Configure Authentication CERT Policy dialog, Server drop-down list, select the virtual server you configured to handle client certificate authentication.
  14. Click OK. A message appears in the status bar, stating that the configuration completed successfully.

Client certificate authentication using advanced policies

Following are the steps to configure client certificate authentication on NetScaler using advanced policies.

  1. Navigate to Security > AAA - Application Traffic > Virtual Servers.

  2. In the details pane, select the virtual server that you want to configure to handle client certificate authentication, and click Edit.

    Note:

    If you have imported a valid CA certificate and server certificate for the virtual server you can skip step 3 to step 10.

  3. On the Configuration page, under Certificates, click > to open the CA Cert Key installation dialog box.
  4. In the CA Cert Key dialog box, click Insert.
  5. In the CA Cert Key - SSL Certificates dialog box, click Install.

  6. In the Install Certificate dialog box, set the following parameters, whose names correspond to the CLI parameter names as shown:

    • Certificate-Key Pair Name—certkeyName
    • Certificate File Name—certFile
    • Key File Name—keyFile
    • Certificate Format—inform
    • Password—password
    • Certificate Bundle—bundle
    • Notify When Expires—expiryMonitor
    • Notification Period—notificationPeriod
  7. Click Install, and then click Close.
  8. In the CA Cert Key dialog box, from the Certificate list, select the root certificate.
  9. Click Save.
  10. Click Back to return to the main configuration screen.
  11. Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies, and then select Policy.

  12. In the details pane do one of the following:

    • To create a new policy, click Add.
    • To modify an existing policy, select the policy, and then click Edit.

  13. In the Create Authentication Policy or Configure Authentication Policy dialog box, type or select values for the parameters.

    • Name - The policy name. Cannot be changed for a previously configured policy.
    • Action Type - Select Cert
    • Action - The authentication action (profile) to associate with the policy. You can choose an existing authentication action, or click the plus and create a new action of the proper type.
    • Log Action - The audit action to associate with the policy. You can choose an existing audit action, or click the plus and create a new action.
    • Expression - The rule that selects connections to which you want to apply the action that you specified. The rule can be simple (“true” selects all traffic) or complex. You enter expressions by first choosing the type of expression in the leftmost drop-down list beneath the Expression window, and then by typing your expression directly into the expression text area, or by clicking Add to open Add Expression dialog box and using the drop-down lists in it to construct your expression.)
    • Comment - You can type a comment that describes the type of traffic that this authentication policy applies to. Optional.
  14. Click Create or OK, and then click Close. If you created a policy, that policy appears in the Authentication Policies and Servers page.

Client certificate pass-through

The NetScaler can now be configured to pass client certificates through to protected applications that require client certificates for user authentication. The ADC first authenticates the user, then inserts the client certificate into the request and sends it to the application. This feature is configured by adding appropriate SSL policies.

The exact behavior of this feature when a user presents a client certificate depends upon the configuration of the VPN virtual server.

  • If the VPN virtual server is configured to accept client certificates but not require them, the ADC inserts the certificate into the request and then forwards the request to the protected application.
  • If the VPN virtual server has client certificate authentication disabled, the ADC renegotiatiates the authentication protocol and reauthenticates the user before it inserts the client certificate in the header and forwards the request to the protected application.
  • If the VPN virtual server is configured to require client certificate authentication, the ADC uses the client certificate to authenticate the user, then inserts the certificate in the header and forwards the request to the protected application.

In all of these cases, you configure the client certificate pass-through as follows.

Create and configure client certificate pass-through by using the command line interface

At the command prompt, type the following commands:

add vpn vserver <name> SSL <IP> 443
<!--NeedCopy-->

For name, substitute a name for the virtual server. The name must contain from one to 127 ASCII characters, beginning with a letter or underscore (_), and containing only letters, numbers, and the underscore, hash (#), period (.), space, colon (:), at (@), equals (=), and hyphen (-) characters. For <IP>, substitute the IP address assigned to the virtual server.

set ssl vserver <name> -clientAuth ENABLED -clientCert <clientcert>
<!--NeedCopy-->

For <name>, substitute the name of the virtual server that you created. For <clientCert>, substitute one of the following values:

  • disabled—disables client certificate authentication on the VPN virtual server.
  • mandatory—configures the VPN virtual server to require client certificates to authenticate.
  • optional—configures the VPN virtual server to allow client certificate authentication, but not to require it.
bind vpn vserver <name> -policy local
<!--NeedCopy-->

For <name>, replace the name of the VPN virtual server that you created.

bind vpn vserver <name> -policy cert
<!--NeedCopy-->

For <name>, substitute the name of the VPN virtual server that you created.

bind ssl vserver <name> -certkeyName <certkeyname>
<!--NeedCopy-->

For <name>, substitute the name of the virtual server that you created. For <certkeyName>, substitute the client certificate key.

bind ssl vserver <name> -certkeyName <cacertkeyname> -CA -ocspCheck Optional
<!--NeedCopy-->

For <name>, substitute the name of the virtual server that you created. For <cacertkeyName>, substitute the CA certificate key.

add ssl action <actname> -clientCert ENABLED -certHeader CLIENT-CERT
<!--NeedCopy-->

For <actname>, substitute a name for the SSL action.

add ssl policy <polname> -rule true -action <actname>
<!--NeedCopy-->

For <polname>, substitute a name for your new SSL policy. For <actname>, substitute the name of the SSL action that you created.

bind ssl vserver <name> -policyName <polname> -priority 10
<!--NeedCopy-->

For <name>, replace the name of the VPN virtual server.

Example 

add vpn vserver vs-certpassthru SSL 10.121.250.75 443
set ssl vserver vs-certpassthru -clientAuth ENABLED -clientCert optional
bind vpn vserver vs-certpassthru -policy local
bind vpn vserver vs-certpassthru -policy cert
bind ssl vserver vs-certpassthru -certkeyName mycertKey
bind ssl vserver vs-certpassthru -certkeyName mycertKey -CA -ocspCheck Optional
add ssl action act-certpassthru -clientCert ENABLED -certHeader CLIENT-CERT
add ssl policy pol-certpassthru -rule true -action act-certpassthru
bind ssl vserver vs-certpassthru -policyName pol-certpassthru -priority 10
<!--NeedCopy-->
Client certificate authentication
May 2, 2023
Contributed by: 
S C
May 2, 2023
Contributed by: 
S C

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.