Product Documentation

Auth Improvements for SAML Authentication

This feature is for those with SAML knowledge, and fundamental authentication proficiency is required to use this information. The reader must understand FIPS to use this information.

The following NetScaler features can be used with third party applications/servers that are compatible with the SAML 2.0 specification:

  • SAML Service Provider (SP)
  • SAML Identity Provider (IdP)

SP and IdP allow a SingleSignOn (SSO) between cloud services. The SAML SP feature provides a way of addressing user claims from an IdP. The IdP could be a third party service or another NetScaler appliance. The SAML IdP feature is used to assert user logons and provide claims consumed by SPs.

As part of the SAML support, both IdP and SP modules digitally sign the data that is sent to peers. The digital signature includes an authentication request from SP, Assertion from IdP, and logout messages between these two entities. The digital signature validates the message authenticity.

The current implementation of SAML SP and IdP do the signature computation in a packet engine. These modules use SSL certificates to sign the data. In a FIPS compliant NetScaler, the private key of the SSL certificate is not available in the packet engine or user space, so the SAML module today is not ready for FIPS hardware.

This document describes the mechanism to offload signature calculations to the FIPS card. Signature verification is done in the software, as the public key is available.

Solution

The SAML feature set is enhanced to use an SSL API for signature offload. See docs.citrix.com for details about these affected SAML sub-features:

  1. SAML SP Post Binding – Signing of AuthnRequest

  2. SAML IdP Post Binding – Signing of Assertion/Response/Both

  3. SAML SP Single Logout scenarios – Signing of LogoutRequest in SP initiated model and Signing of LogoutResponse in IdP initiated model

  4. SAML SP Artifact binding – Signing of ArtifactResolve request

  5. SAML SP Redirect Binding – Signing of AuthnRequest

  6. SAML IdP Redirect Binding – Signing of Response/Assertion/Both

  7. SAML SP Encryption support – Decryption of Assertion

Platform

The API can be offloaded only to a FIPS platform.

Configuration

Offload configuration is performed automatically on the FIPS platform.

However, since SSL private keys are not available to user space in FIPS hardware, there is a slight configuration change in creating the SSL certificate on FIPS hardware.

Here’s the configuration information:

  • add ssl fipsKey fips-key

    You would then need to create a CSR and use it at the CA server to generate a certificate. You can then copy that certificate in /nsconfig/ssl. Let’s assume that file is fips3cert.cer.

  • add ssl certKey fips-cert -cert fips3cert.cer -fipsKey fips-key

    You would then need to specify this certificate in the SAML action for SAML SP module.

  • set samlAction <name> -samlSigningCertName fips-cert

    Likewise, you need to use this in samlIdpProfile for SAML IdP module

  • set samlidpprofile fipstest –samlIdpCertName fips-cert

The first time, you will not have the fips-key described above. If there’s no FIPS key, create one as described at: https://support.citrix.com/servlet/KbServlet/download/9539-102-665378/NS9000\_FIPS\_6\[1\]\[1\].1.pdf

  • create ssl fipskey <fipsKeyName> -modulus <positive_integer> [-exponent ( 3 F4 )]
  • create certreq <reqFileName> -fipskeyName <string>

Auth Improvements for SAML Authentication

In this article