Product Documentation
ADC
14.1-Current Release 13.1
View PDF

Configure SSL-based header insertion

September 27, 2025
Contributed by: 
C S S

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 do one of the following:

  • Insert the entire client certificate, if necessary, a hash (also known as a fingerprint or thumbprint) of the entire client certificate.
  • Insert only the specific fields from the certificate, such as the subject, serial number, issuer, signature, SSL session ID, cipher suite.
  • Insert 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 receive the SSL traffic.

The following example uses Advanced policy 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. 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

Example:

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

Done
<!--NeedCopy-->

Configure SSL-based header insertion by using the GUI

  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.

Configure an SSL policy action for inserting client certificate thumbprint in the HTTP header

NetScaler appliances now support inserting the thumbprint (also called a fingerprint) of a certificate into the header of a request sent to a back-end server. If client authentication is enabled, the appliance computes the thumbprint of the certificate, and uses an SSL policy action to insert the thumbprint into the request. The server searches for the thumbprint, and grants secure access if there is a match.

Configure an SSL action to enable client certificate fingerprint, specify a header name to insert the client certificate fingerprint, and a digest (hash value) to compute the fingerprint value. The NetScaler appliance supports SHA1 and SHA2 (SHA224, SHA256, SHA384, SHA512) digests. The appliance derives the fingerprint value by computing the specified digest of the DER-encoding of the client certificate. Then, create an SSL policy specifying this action, and bind the policy to an SSL virtual server.

Configure an SSL action for inserting client certificate thumbprint by using the CLI

At the command prompt type:

add ssl action <name> -clientCertFingerprint ( ENABLED | DISABLED ) -certFingerprintHeader <string> -certFingerprintDigest <certFingerprintDigest>
<!--NeedCopy-->

Arguments:

clientCertFingerprint:

Insert the certificate’s fingerprint into the HTTP header of the request being sent to the web server. The fingerprint is derived by computing the specified hash value (SHA256, for example) of the DER-encoding of the client certificate.

certFingerprintHeader:

Name of the header into which to insert the client certificate fingerprint.

certFingerprintDigest:

Digest algorithm used to compute the fingerprint of the client certificate.

Possible values: SHA1, SHA224, SHA256, SHA384, SHA512

Example:

add ssl action act1 -clientcertfingerprint ENABLED -certfingerprintdigest SHA1 -certfingerprintheader example
Done
<!--NeedCopy-->

sh ssl action act1
    1)      Name: act1
            Type: Data Insertion
            Cert Fingerprint Header: ENABLED
            Cert-Fingerprint Tag: example
            Cert-Fingerprint Digest Algorithm: SHA1
            Hits: 0
            Undef Hits: 0
            Action Reference Count: 0
Done
<!--NeedCopy-->

add ssl policy pol1 -rule true -action act1
Done
<!--NeedCopy-->

bind ssl vserver v1 -policyName pol1 -priority 10
Done
<!--NeedCopy-->

sh ssl vserver v1

            Advanced SSL configuration for VServer v1:
            DH: DISABLED
            DH Private-Key Exponent Size Limit: 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
            SSLv2: DISABLED SSLv3: DISABLED TLSv1.0: DISABLED  TLSv1.1: ENABLED  TLSv1.2: DISABLED
            Push Encryption Trigger: Always
            Send Close-Notify: YES

            ECC Curve: P_256, P_384, P_224, P_521

    1)      CertKey Name: intca6    CA Certificate          CRLCheck: Mandatory             CA_Name Sent
    2)      CertKey Name: intca5    CA Certificate          CRLCheck: Mandatory             CA_Name Sent
    3)      CertKey Name: intca4    CA Certificate          CRLCheck: Mandatory             CA_Name Sent
    4)      CertKey Name: intca3    CA Certificate          CRLCheck: Mandatory             CA_Name Sent
    5)      CertKey Name: intca2    CA Certificate          CRLCheck: Mandatory             CA_Name Sent
    6)      CertKey Name: intca1    CA Certificate          CRLCheck: Mandatory             CA_Name Sent

            Data policy
    1)      Policy Name: pol1       Priority: 10

    1)      Cipher Name: DEFAULT
            Description: Default cipher list with encryption strength >= 128bit
    Done
<!--NeedCopy-->

Configure an SSL action for inserting client certificate thumbprint by using the GUI

  1. Navigate to Traffic Management> SSL> Policies.
  2. In the details pane, select the SSL Actions tab, and click Add.
  3. In the Create SSL Action dialog box, set the following parameters:
    • Name*
    • Client Certificate Finger Print
    • FingerPrint Tag
    • FingerPrint Digest *A required parameter
  4. Click Create.
  5. Select the SSL Policies tab, and click Add.
  6. In the Create SSL Policy dialog box, set the following parameters:
    • Name*
    • Action
    • Expression *A required parameter
  7. Click Create.
  8. Navigate to Traffic Management> Load Balancing > Virtual Servers.
  9. In the details pane, from the list of SSL virtual servers, select the virtual server to which you want to bind the SSL policy, and then click Edit.
  10. In Advanced Settings, click SSL Policies.
  11. Click below SSL Policy, and in Policy Binding dialog box, select the policy created earlier and assign a priority.
  12. Click Bind.
Configure SSL-based header insertion
September 27, 2025
Contributed by: 
C S S
September 27, 2025
Contributed by: 
C S S

In this article

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