Configure Citrix Netscaler for Mutual TLS authentication with PhenixID Authentication Services
Warning
Please note, this document is using the legacy authenticators - in order to use the new protocol agnostic authenticators, you need to apply relevant modifications to the configuration examples outlined in this article.
Summary
This document will guide you through the steps to configure Citrix NetScaler for certificate authentication with mutual TLS.
This will enable usage of SmartCard authentication in PAS.
System Requirements
- PhenixID Authentication Server 3.0 or higher
- Citrix Netscaler admin rights
Instruction
Overview
This document will guide you through the steps to configure Netscaler for Mutual TLS.
The configuration for PAS to receive the http-header with the certificate is documented at the PAS documentation. Look for HeaderBasedCertificate or HeaderBasedCertificateSAML authenticators.
Configure TrustStore
The first step is to configure which certificates the Netscaler should trust. This is done by entering the CA certificates under Traffic Management> Load Balancing> Virtual Servers
For everything to work, you must also bring the root certificate (so that you get the whole chain). By checking the box “Skip CA” when entering the root certificate, it will not be sent to the client browser.
Then enter the intermediate certificates you want to present to the browser. This way you can get the client browser to send certificates for example HSA ID but not social security number (which has another intermediate).
Specify URI for mutual TLS demand
Warning
Please note, as of TLS 1.3, this will not work as intended since it relies on a feature in the TLS/SSL protocol that has been explicitly removed in TLS 1.3.
HTTPS (HTTP over TLS/SSL) works like this:
- TLS is negotiated
- Thanks to ex SNI, it's possible to negotiate with different certificates on both the client and the server for different hosts (ex. FQDN)
- However, HTTP has not started yet, so the intended path is not part of the negotiation
- HTTP starts, and the server learns of the path the client wants to access
- At this point, it's too late to negotiate ex. the requirement of a client certificate, TLS has already been negotiated
- However, there has been a feature in TLS/SSL prior to version 1.3 (eg. 1.2 and lower) where the TLS session can be renegotiated
- This has been removed, starting with TLS 1.3, since it has been known to cause security issues
- This was used to let the server intercept the HTTP requests, and when a "protected path" was seen, trigger a TLS renegotiation where a client certificate was required
- However, since TLS renegotiation has been removed, the feature of enabling mutual TLS for a specific path is not possible with TLS 1.3
- There is, however, a new feature in TLS 1.3 that's called "post-handshake (client) authentication" which can solve this problem. The support for this feature is not widedely available (it's an optional extension), so it's not really feasible to use.
- For HTTP/2.0, the use of this new feature in TLS 1.3 is explicitly forbidden, so it's not really an option at all (since HTTP is now multiplexed, with multiple requests sharing the same TLS session/connection)
So, in short, starting with TLS 1.3 and/or HTTP 2.0: it is not possible to request mutual TLS (mTLS)/client authentication for a specific path. Make sure to have a dedicated "FQDN", IP and/or port combination (or similar) for mTLS.
The second step is to specify in which subdirectories the Netscaler must require client certificates. Create an SSL Policy that turns on a specific subdirectory and then an SSL Action that requires us to have a client certificate to access that directory.
Send certificate to PAS in HTTP-header
The last step, after Netscaler has approved the client certificate, is to forward it to the backend servers in an HTTP header. Then you need another SSL Action that turns on the same directory and an SSL Policy that writes the entire certificate in a header. The header must be configured with the same name as PAS is configured to receive the header.
Verify configuration
This image is an example with two different URI:s configured for mutual TLS.
Configure PAS
Now it’s time to configure PAS for client certificate authentication, see the article Mutual TLS (Client Certificate Authentication)