Product Documentation

Configuring SSL-Based Header Insertion

Sep 01, 2016

Because the NetScaler appliance offloads all SSL-related processing from the servers, the servers receive only HTTP traffic. In some circumstances, the server needs certain SSL information. For example, security audits of recent SSL transactions require the client subject name (contained in an X509 certificate) to be logged on the server.

Such data can be sent to the server by inserting it into the HTTP header as a name-value pair. You can insert the entire client certificate, if required, or only the specific fields from the certificate, such as the subject, serial number, issuer, certificate hash, SSL session ID, cipher suite, or the not-before or not-after date used to determine certificate validity.

You can enable SSL-based insertion for HTTP-based SSL virtual servers and services only. You cannot apply it to TCP-based SSL virtual servers and services. Also, client authentication must be enabled on the SSL virtual server, because the inserted values are taken from the client certificate that is presented to the virtual server for authentication.

To configure SSL-based header insertion, first create an SSL action for each specific set of information to be inserted, and then create policies that identify the connections for which you want to insert the information. As you create each policy, specify the action that you want associated with the policy. Then, bind the policies to the SSL virtual servers that will receive the SSL traffic.

The following example uses default syntax policies. In the following example, a control policy (ctrlpol) is created to perform client authentication if a request is received for the URL /testsite/file5.html. A data policy (datapol) is created to perform an action (act1) if client authentication is successful, and an SSL action (act1) is added to insert the certificate details and issuer's name in the request before forwarding the request. For other URLs, client authentication is disabled. The policies are then bound to an SSL virtual server (ssl_vserver) that receives the SSL traffic.

Command-line example of configuring SSL-based header insertion


> add ssl action act1 -clientCert ENABLED -certHeader mycert -clientcertissuer ENABLED -certIssuerHeader myissuer 
> add ssl policy datapol -rule HTTP.REQ.URL.EQ(\"/testsite/file5.html\") -action act1 
> add ssl policy ctrlpol -rule HTTP.REQ.URL.EQ(\"/testsite/file5.html\") -action CLIENTAUTH 
> bind ssl vserver ssl_vserver -policyName ctrlpol -priority 1 
> bind ssl vserver ssl_vserver -policyName datapol -priority 1 

To configure SSL-based header insertion by using the configuration utility

  1. Navigate to Traffic Management > SSL > Policies.
  2. In the details pane, on the Actions tab, click Add.
  3. In the Create SSL Action dialog box, set the following parameters:
    • Name*
    • Client Certificate
    • Certificate Tag
    • Client Certificate Issuer
    • Issuer Tag

    * A required parameter

  4. Click Create, and then click Close.
  5. On the tab, click Add to create a control policy.
  6. In the Create SSL Policy dialog box, set the following parameters:
    • Name*
    • Expression
    • Request Action

    * A required parameter

  7. Click Create, and then click Close.
  8. Create a data policy by repeating steps 5 through 7.
  9. In the navigation pane, expand SSL Offload, and then click Virtual Servers.
  10. In the details pane, from the list of virtual servers, select the virtual server to which you want to bind the SSL policies, and then click Open.
  11. In the Configure Virtual Server (SSL Offload) dialog box, click SSL Settings, and then click SSL Policies.
  12. In the Bind/Unbind SSL Policies dialog box, click Insert Policy. Under Policy Name, select the policy that you created in steps 5 through 7.
  13. Click OK, and then click Close. A message appears in the status bar, stating that the policy has been bound successfully.
  14. Repeat steps 12 and 13 and select the policy that you created in step 8.