SAML authentication
Security Assertion Markup Language (SAML) is an XML-based authentication mechanism that provides single sign-on capability and is defined by the OASIS Security Services Technical Committee.
Note
Starting from NetScaler 12.0 Build 51.x, Citrix ADC appliance used as a SAML Service Provider (SP) with Multi-Factor (nFactor) authentication now prepopulates the user-name field on the login page. The appliance sends a NameID attribute as part of a SAML authorization request, retrieves the NameID attribute value from the Citrix ADC SAML Identity Provider (IdP), and prepopulates the user-name field.
Why use SAML authentication
Consider a scenario in which a service provider (LargeProvider) hosts a number of applications for a customer (BigCompany). BigCompany has users that must seamlessly access these applications. In a traditional setup, LargeProvider would need to maintain a database of users of BigCompany. This raises some concerns for each of the following stakeholders:
- LargeProvider must ensure security of user data.
- BigCompany must validate the users and keep the user data up-to-date, not just in its own database, but also in the user database maintained by LargeProvider. For example, a user removed from the BigCompany database must also be removed from the LargeProvider database.
- A user has to log on individually to each of the hosted applications.
The SAML authentication mechanism provides an alternative approach. The following deployment diagram shows how SAML works.
The concerns raised by traditional authentication mechanisms are resolved as follows:
- LargeProvider does not have to maintain a database for BigCompany users. Freed from identity management, LargeProvider can concentrate on providing better services.
- BigCompany does not bear the burden of making sure the LargeProvider user database is kept in sync with its own user database.
- A user can log on once, to one application hosted on LargeProvider, and be automatically logged on to the other applications that are hosted there.
The Citrix ADC appliance can be deployed as a SAML Service Provider (SP) and a SAML Identity Provider (IdP). Read through the relevant topics to understand the configurations that must be performed on the Citrix ADC appliance.
A Citrix ADC appliance configured as a SAML service provider can now enforce an audience restriction check. The audience restriction condition evaluates to “Valid” only if the SAML replying party is a member of at least one of the specified audiences.
You can configure a Citrix ADC appliance to parse attributes in SAML assertions as group attributes. Parsing them as group attributes enables the appliance to bind policies to the groups.
Note
A Citrix ADC MPX FIPS appliance used as a SAML service provider now supports encrypted assertions. Also, a Citrix ADC MPX FIPS appliance functioning as a SAML service provider or a SAML identity provider can now be configured to use the SHA2 algorithms on FIPS hardware.
Configuring FIPS offload support using the command line interface:
-
Add SSL FIPS
add ssl fipsKey fips-key
-
Create a CSR and use it at CA server to generate a certificate. You can then copy the certificate in /nsconfig/ssl. Let’s assume that the file is fips3cert.cer.
add ssl certKey fips-cert -cert fips3cert.cer -fipsKey fips-key<!--NeedCopy--> -
Specify this certificate in the SAML action for SAML SP module
set samlAction <name> -samlSigningCertName fips-cert<!--NeedCopy--> -
Use the certificate in samlIdpProfile for SAML IDP module
set samlidpprofile fipstest –samlIdpCertName fips-cert<!--NeedCopy-->
The following table lists some articles that are specific to deployments where the Citrix ADC appliance is used as a SAML SP or a SAML IdP.
| SAML SP | SAML IdP | Information Link |
|---|---|---|
| Citrix ADC | Citrix AppController Z3 | Citrix Support |
| Citrix ADC | CloudGateway | Citrix Support |
| Citrix ADC | Microsoft AD FS 3.0 | Citrix Support |
| Citrix ADC | Shibboleth | Citrix Support |
| Citrix ADC | Shibboleth (With SAML single logout configuration) | Citrix Support |
| Siteminder | Citrix ADC | Citrix Support |
| ShareFile | Citrix ADC | Citrix Support |
Some information on other specific deployments:
- NetScaler as SAML SP on FIPS Device
- Configuring Office365 for Single Sign-on with NetScaler as SAML IdP
WebView credential type support for authentication mechanisms
The authentication of a Citrix ADC appliance can now support AUTHv3 protocol. The WebView credential type in AUTHv3 protocol support all type of authentication mechanisms (including SAML and OAuth). The WebView credential type is a part of AUTHv3, which is implemented by Citrix Receiver and browser in web applications.
The following example explains the flow of WebView events through Citrix Gateway and Citrix Receiver:
- The Citrix Receiver negotiates to Citrix Gateway for AUTHv3 protocol support.
- Citrix ADC appliance responds positively and suggests a specific start URL.
- Citrix Receiver then connects to the specific endpoint (URL).
- The Citrix Gateway sends a response to the client to start the WebView.
- Citrix Receiver starts WebView and sends initial request to Citrix ADC appliance.
- Citrix ADC appliance redirects URI to browser login endpoint.
- Once authentication is complete, Citrix ADC appliance sends completion response to WebView.
- The WebView now exits and gives control back to Citrix Receiver to continue AUTHv3 protocol for session establishment.
Metadata reading and generation support for SAML SP and IdP configuration
Citrix ADC appliance now supports metadata files as means of configuration entities for both SAML Service Provider (SP) and Identity Provider (IdP). The metadata file is a structured XML file that describes the configuration of an entity. The metadata files for SP and IdP are separate. Based on deployment, and at times, one SP or IdP entity can have multiple metadata files. As an administrator, you can export and import (SAML SP and IdP) metadata files on Citrix ADC. The functionality of metadata export and import for SAML SP and IdP are explained in the following sections.
Metadata export for SAML SP
Consider an example where Citrix ADC is configured as SAML SP and an SAML IdP would like to import metadata that contains Citrix ADC SP configuration. Assume that Citrix ADC appliance is already configured with a “samlAction” attribute that specifies SAML SP configuration. To export metadata from users or administrator, query Citrix Gateway or authentication virtual server as shown below:
https://vserver.company.com/metadata/samlsp/<action-name>
Metadata import for SAML SP
Currently, SAML Action configuration on Citrix ADC appliance takes various parameters. Administrator manually specifies these. However, administrators are often unaware of nomenclature if it comes to interop with different SAML systems. If metadata of IdP is available, then bulk of the configuration in the ‘samlAction’ entity can be avoided. In fact, the entire IdP specific configuration might be omitted if IdP metadata file is given. The ‘samlAction’ entity now takes an additional parameter to read configuration from metadata file.
When you import a metadata in a Citrix ADC appliance, the metadata does not contain any signature algorithms to be used, it contains the endpoint details. A metadata can be signed with certain algorithms which can be used to verify the metadata itself. The algorithms are not stored in the ‘samlAction’ entity.
Therefore, what you specify in the ‘samlAction’ entity are the ones used when sending the data out. An incoming data can contain a different algorithm for a Citrix ADC appliance to process.
To fetch the metadata files by using command line interface.
set samlAction <name> [-metadataUrl <url> [-metadataRefreshInterval <int>] https://idp.citrix.com/samlidp/metadata.xml
Note
The metadataRefreshInterval parameter is the interval in minutes for fetching metadata information from the specified metadata URL. Default value 36000.
Metadata import for SAML IdP
The “samlIdPProfile” parameter takes a new argument to read the entire configuration that is specific to SP. SAML IdP configuration can be simplified by replacing SP specific properties with an SP metadata file. This file is queried through HTTP.
To read from metadata file using command line interface:
set samlIdPProfile <name> [-metadataUrl <url>] [-metadataRefreshInterval <int>]
Name-value attribute support for SAML authentication
You can now configure SAML authentication attributes with a unique name along with values. The names are configured in the SAML action parameter and the values are obtained by querying for the names. By specifying the name attribute value, admins can easily search for the attribute value associated with the attribute name. Also, admins no longer have to remember the attribute by its value alone.
Important
- In samlAction command, you can configure a maximum of 64 attributes separated by comma with total size less than 2048 bytes.
- Citrix recommends that you use the attributes list. Use of “attribute 1 to attribute 16” will cause session failure if the extracted attribute size is large.
To configure the name-value attributes by using the CLI
At the command prompt, type:
add authentication samlAction <name> [-Attributes <string>]
Example:
add authentication samlAction samlAct1 -attributes “mail,sn,userprincipalName”