Additional features supported for SAML
Metadata reading and generation support for SAML SP and IdP configuration
Citrix ADC appliance 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 the Citrix ADC is configured as SAML SP and an SAML IdP would like to import metadata that contains the Citrix ADC SP configuration. Assume that a Citrix ADC appliance is already configured with a “samlAction” attribute that specifies the SAML SP configuration. To export metadata from users or administrator, query the Citrix Gateway or authentication virtual server as following:
Metadata import for SAML SP
Currently, the SAML Action configuration on a Citrix ADC appliance takes various parameters. Administrator manually specifies these parameters. However, administrators are often unaware of nomenclature if it comes to interop with different SAML systems. If metadata of IdP is available, then the bulk of the configuration in the ‘samlAction’ entity can be avoided. In fact, the entire IdP specific configuration might be omitted if the IdP metadata file is given. The ‘samlAction’ entity now takes an extra parameter to read the configuration from the 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
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 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.
- In the 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” causes 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>]
add authentication samlAction samlAct1 -attributes “mail,sn,userprincipalName”
Assertion Consumer Service URL support for SAML IdP
A Citrix ADC appliance configured as a SAML Identity Provider (IdP) supports Assertion Consumer Service (ACS) indexing to process the SAML Service Provider (SP) request. The SAML IdP imports ACS indexing configuration from SP metadata or allows for entering ACS indexes information manually.
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||Microsoft Azure AD||Citrix Support|
|Okta||Citrix ADC||Citrix Support|
|AWS||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 the AUTHv3 protocol. The WebView credential type in the AUTHv3 protocol supports 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, the Citrix ADC appliance sends a completion response to WebView.
- The WebView now exits and gives control back to Citrix Receiver to continue the AUTHv3 protocol for session establishment.
Increase of SessionIndex size in SAML SP
The SessionIndex size of the SAML Service Provider (SP) is increased to 96 bytes. Previously, the default maximum size of SessionIndex was 63 bytes.
Support introduced in NetScaler 13.0 Build 36.x
Custom authentication class reference support for SAML SP
You can configure a custom authentication class reference attribute in the SAML action command. Using the custom authentication class reference attribute, you can customize the class names in the appropriate SAML tags. The custom authentication class reference attribute along with a namespace is sent to the SAML IdP as part of the SAML SP authentication request.
Previously, using the SAML action command, you can configure only a set of predefined classes defined in the authnCtxClassRef attribute.
While configuring the customAuthnCtxClassRef attribute, ensure the following:
- The names of the classes must include alphanumeric characters or a valid URL with proper XML tags.
- If you have to configure multiple custom classes, each class must be separated by commas.
To configure the customAuthnCtxClassRef attributes by using the CLI
At the command prompt, type:
- add authentication samlAction
- set authentication samlAction
add authentication samlAction samlact1 –customAuthnCtxClassRef http://www.class1.com/LoA1,http://www.class2.com/LoA2
set authentication samlAction samlact2 –customAuthnCtxClassRef http://www.class3.com/LoA1,http://www.class4.com/LoA2
To configure the customAuthnCtxClassRef attributes by using the GUI
- Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies > Actions > SAML.
- On the SAML page, select Servers tab and Click Add.
- On the Create Authentication SAML Server page, enter the name for a SAML action.
Scroll down to configure the class types in Custom Authentication Class Types section.
Support for artifact binding in SAML IdP
Citrix ADC appliance configured as SAML Identity Provider (IdP) supports artifact binding. The artifact binding enhances the security of SAML IdP and restricts the malicious users from inspecting the assertion.
FIPS offload support
A Citrix ADC MPX FIPS appliance used as a SAML service provider 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.
In FIPS mode, only the RSA-V1_5 algorithm is supported as the key transport algorithm.
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
Specify this certificate in the SAML action for SAML SP module
set samlAction <name> -samlSigningCertName fips-cert
Use the certificate in samlIdpProfile for a SAML IdP module
set samlidpprofile fipstest –samlIdpCertName fips-cert
Common SAML terminologies
The following are some common SAML terminologies:
Assertion: A SAML assertion is an XML document returned by the Identity Provider to the Service Provider after authentication of the user. The assertion has a specific structure, as defined by the SAML standard.
Types of Assertions: The following are the types of assertion.
- Authentication - the user is authenticated by a particular means at a particular time
- Authorization - the user was granted or denied access to a specified resource
- Attributes - the user is associated with the supplied attributes
Assertion Consumer Service (ACS): The service provider’s endpoint (URL) that is responsible for receiving and parsing a SAML assertion.
Audience Restriction: A value within the SAML assertion that specifies who (and only who) the assertion is intended for. The “audience” will be the service provider and is typically a URL but can technically be formatted as any string of data.
Identity Provider (IdP): In terms of SAML, the Identity Provider is the entity that verifies the identity of the user, in response to a request by the Service Provider. The Identity Provider is responsible for maintaining and authenticating the user’s identity.
Service Provider (SP): In terms of SAML, the Service Provider (SP) offers a service to the user and allows the user to sign in by using SAML. When the user attempts to sign in, the SP sends a SAML authentication request to the Identity Provider (IdP).
SAML Binding: SAML requestors and responders communicate by exchanging messages. The mechanism to transport these messages is called a SAML binding.
HTTP Artifact: One of the binding options supported by the SAML protocol. HTTP Artifact is useful in scenarios where the SAML requester and responder are using an HTTP User-Agent and do not want to transmit the entire message, either for technical or security reasons. Instead, a SAML Artifact is sent, which is a unique ID for the full information. The IdP can then use the Artifact to retrieve the full information. The artifact issuer must maintain state while the artifact is pending. An Artifact Resolution Service (ARS) must be set up. HTTP Artifact sends the artifact as a query parameter.
HTTP POST: One of the binding options supported by the SAML protocol. HTTP POST sends the message content as a POST parameter, in the payload.
HTTP Redirect: One of the binding options supported by the SAML protocol. When HTTP Redirect is used, the Service Provider redirects the user to the Identity Provider where the login happens, and the Identity Provider redirects the user back to the Service Provider. HTTP Redirect requires intervention by the User-Agent (the browser). HTTP Redirect sends the message content in the URL. Because of this, it cannot be used for the SAML response, because the size of the response exceeds the URL length allowed by most browsers.
The Citrix ADC appliance supports POST and Redirect bindings during logout.
Metadata: Metadata is the configuration data in SP and IdP to know how to communicate to each other which is in XML standards.
Other useful Citrix articles related to SAML authentication
You might find the following articles related to SAML authentication useful.
Additional features supported for SAML
In this article
- Metadata reading and generation support for SAML SP and IdP configuration
- Name-value attribute support for SAML authentication
- Assertion Consumer Service URL support for SAML IdP
- WebView credential type support for authentication mechanisms
- Increase of SessionIndex size in SAML SP
- Custom authentication class reference support for SAML SP
- Support for artifact binding in SAML IdP
- FIPS offload support
- Common SAML terminologies
- Other useful Citrix articles related to SAML authentication