NetScaler as a SAML SP

The SAML service provider (SP) is a SAML entity deployed by the service provider. When a user tries to access a protected application, the SP evaluates the client request. If the client is unauthenticated (does not have a valid NSC_TMAA or NSC_TMAS cookie), the SP redirects the request to the SAML identity provider (IdP).

The SP also validates SAML assertions that are received from the IdP.

When the NetScaler appliance is configured as an SP, a traffic management virtual server (load balancing or content switching) receives all user requests associated with the relevant SAML action.

The NetScaler appliance also supports POST and Redirect bindings during logout.

Note

A NetScaler appliance can be used as a SAML SP in a deployment where the SAML IdP is configured either on the appliance or on any external SAML IdP.

When used as a SAML SP, a NetScaler appliance:

• Can extract the user information (attributes) from the SAML token. This information can then be used in the policies that are configured on the NetScaler appliance. For example, if you want to extract the GroupMember and emailaddress attributes, in the SAMLAction, specify the Attribute2 parameter as GroupMember and the Attribute3 parameter as emailaddress.

  Note

  Default attributes such as user name, password, and logout URL must not be extracted in attributes 1–16, because they as are implicitly parsed and stored in the session.

• Can extract attribute names of up to 127 bytes from an incoming SAML assertion. The previous limit was 63 bytes.

• Supports post, redirect, and artifact bindings.

  Note

  Do not use redirect binding for large amounts of data when the assertion after inflate or decoding is greater than 10K.

• Can decrypt assertions.

• Can extract multi-valued attributes from a SAML assertion. These attributes are sent is nested XML tags such as:

  <AttributeValue> <AttributeValue>Value1</AttributeValue> <AttributeValue>Value2</AttributeValue> </AttributeValue>

  Note

  From NetScaler 13.0 Build 63.x and above, the individual maximum length for SAML attributes has been increased to allow a maximum of 40k bytes. The size of all the attributes must not exceed 40k bytes.

  When presented with previous XML, the NetScaler appliance can extract both Value1 and Value2 as values of a given attribute, as opposed to the old firmware that extracts only Value1.

• Can specify the validity of a SAML assertion.

  If the system time on NetScaler SAML IdP and the peer SAML SP is not in sync, the messages might get invalidated by either party. To avoid such cases, you can now configure the time duration for which the assertions are valid.

  This duration, called the “skew time,” specifies the number of minutes for which the message can be accepted. The skew time can be configured on the SAML SP and the SAML IdP.

• Can send an extra attribute called ‘ForceAuth’ in the authentication request to an external IdP (identity provider). By default, the ForceAuthn is set to ‘False’. It can be set to ‘True’ to suggest IdP to force authentication despite the existing authentication context. Also, NetScaler SP does authentication request in query parameter when configured with artifact binding.

Configure the NetScaler appliance as a SAML SP by using the CLI

1. Configure a SAML SP action.

   Example

   The following command adds a SAML action that redirects unauthenticated user requests.

   add authentication samlAction SamlSPAct1 -metadataUrl "https://ksidp1.ksaaa.local/metadata/samlidp/SAML_IDP_profile" -samlIdPCertName nssp -preferredbindtype SSOREDIRECT -samlSigningCertName nssp –samlRedirectUrl https://auth1.example.com -relaystateRule "AAA.LOGIN.RELAYSTATE.EQ(\"https://lb.example1.com/\")"

   Points to note

   • Certificate provided for -samlIdPCertName in the samlAction command must match the corresponding certificate from IdP for the signature verification to succeed.
   • SAML supports only the RSA certificate. Other certificates like HSM and FIPS are not supported.
   • It is recommended to have a full domain name with a trailing ‘/’ in the expression.
   • If the authentication virtual server is configured as a SAML IdP, the metadata URL that must be used in the SAML SP action is https://<netscaler-saml-idp-fqdn>/metadata/samlidp/SAML_IDP_profile.
   • If multiple SAML policies are part of an IdP chain, it is sufficient to configure a relay state rule only on the first SAML policy.

   For details on this command, see https://developer-docs.netscaler.com/en-us/adc-command-reference-int/current-release/authentication/authentication-samlaction and https://support.citrix.com/article/CTX316577.

2. Configure the SAML policy.

   Example:

   The following command defines a SAML policy that applies the previously defined SAML action to all traffic.

   add authentication policy SamlSPPol1 -rule true -action SamlSPAct1

3. Bind the SAML policy to the authentication virtual server.

   Example

   The following command binds the SAML policy to an authentication virtual server named “av_saml”.

   bind authentication vserver av_saml -policy SamlSPPol1

4. Bind the authentication virtual server to the appropriate traffic management virtual server.

   Example

   The following command adds a load balancing virtual server named “lb1_ssl” and associates the authentication virtual server named “av_saml” to the load balancing virtual server. add lb vserver lb1_ssl SSL 10.217.28.224 443 -persistenceType NONE -cltTimeout 180 -AuthenticationHost auth1.example.com -Authentication ON -authnVsName av_saml

   For details on this command, see https://developer-docs.citrix.com/projects/citrix-adc-command-reference/en/latest/authentication/authentication-samlAction.

Configure a NetScaler appliance as a SAML SP by using the GUI

1. Configure a SAML SP action.

   1. Navigate to Security > AAA-Policies > Authentication > Basic Policies > SAML.

   2. Select Servers tab, click Add, enter values for the following parameters, and click Create.

      Parameter descriptions:

      • Name - Name of the server.

      • Redirect URL - URL that users authenticate against. Some IdPs have special URLs that are not reachable unless they are on a SAML setup.

      • Single Logout URL - URL specified so that the NetScaler can recognize when to send the client back to the IdP to complete the signout process.

      • SAML Binding - A mechanism that is used to transport SAML requestor and responder messages between the SP and IdP. When NetScaler acts as an SP, it supports Post, Redirect, and Artifact bindings. The default binding method is POST.

        Note:

        For Artifact binding, the transport mechanism on the SP and IdP must be the same.

      • Logout Binding - Specifies the transport mechanism of SAML logout messages. The default binding mechanism is Post.

      • IdP Certificate Name - IdPCert Certificate (Base64) present under SAML Signing Certificate.

      • SAML IDP Metadata URL - Used to obtain the SAML metadata. You do not have to specify the IdP certificate name and the redirect URL fields when the metadata URL is present.

        When you configure the metadata URL, the SAML IdP sends the binding type options for SSO and Logout to NetScaler. By default, NetScaler selects Redirect as the binding type for Logout and Post as the binding type for SSO.

        The following is an example of the SAML IdP response that includes the options for binding type:

        <?xml version=\"1.0\"?> <md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" ID=\"_b4743282f0a1e14164b8ccd429e8cee2\" entityID=\"192.0.2.255\"> <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP -Redirect\" Location=\"https://192.0.2.255 /cgi/tmlogout_redirect1\"></md:SingleLogoutService> <md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://192.0.2.255 /cgi/tmlogout_post1\"></md:SingleLogoutService> <md:SingleSignOnServ ice Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://192.0.2.255 /saml/login_post1\"> </md:SingleSignOnService> <md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https://192.0.2.255 /saml/login_redirect1\"> </md:SingleSignOnService> </md:EntityDescriptor>

        You can modify the default binding types for SSO and Logout by configuring the Preferred bind type parameter.

        Note:

        Starting from release 14.1 build 29.x onwards, NetScaler configured as a SAML SP can retrieve and store multiple certificates from the same IdP using the SAML IdP metadata URL. This functionality allows the SP to select the correct certificate and validate SAML assertions from the IdP by using that certificate. The SP can store up to 4 certificates. This enhances the flexibility and robustness of the system.

      • Preferred bind type - Specifies the preferred binding type for SSO and logout. This option is available from release 14.1 build 25.x onwards.

        In the previous SAML IdP response, for SSO, NetScaler selects Post as the SAML binding and chooses https://192.0.2.255/saml/login_post1, by default. You can modify this behavior by selecting the SSOREDIRECT checkbox as the preferred binding type.

        In the previous SAML IdP response, for Logout, NetScaler selects Redirect as the Logout binding type and chooses https://192.0.2.255/cgi/tmlogout_redirect1, by default. You can modify this behavior by selecting the LOGOUTPOST checkbox as the preferred binding type.

        You can configure either one or both the binding types based on your preference.

      • Metadata Refresh Interval (mins) - Interval in minutes for fetching metadata from the specified metadata URL.

      • User Field - Section of the IdP’s SAML authentication form that contains the user name for SP to extract if necessary.

      • Signing Certificate Name - Select the SAML SP certificate (with private key) that NetScaler uses to sign authentication requests to the IdP. The same certificate (without private key) must be imported to the IdP, so that the IdP can verify the authentication request signature. Most IdPs do not require the signing certificate name.

      • IssuerName - Identifier. Unique ID that is specified on both the SP and IdP to help identify the service provider to each other.

      • Reject unsigned assertion - Option that you can specify if you require the assertions from the IdP to be signed. The default option is ON.
        • ON: Rejects assertions without a signature
        • STRICT: Ensures that both response and assertion are signed
        • OFF: Allows unsigned assertions

      • Audience - Audience for which an assertion sent by IdP is applicable. This is typically an entity name or a URL that represents the service provider.

      • Signature Algorithm - Algorithm to be used to sign/verify SAML transactions. The default value is RSA-SHA256.

      • Digest Method - Algorithm to be used to compute/verify digest for SAML transactions. The default value is SHA256.

      • Relay State Rule - Refer to Points to note about the relaystateRule parameter for details about this parameter.

      • State Check Rule - Configure the expressions that are evaluated to validate HTTP requests on SAML endpoints.

      • Default Authentication Group - The default group that is chosen when the authentication succeeds in addition to the extracted groups.

      • Group Name Field - Name of the tag in an assertion that contains user groups.

      • Skew Time (mins) - This option specifies the clock skew in minutes that the NetScaler service provider allows on an incoming assertion. For example, if you set the skew time to 10 minutes at 16:00, the SAML assertion is valid from 15:50 to 16:10 - 20 minutes in total. The default skew time is 5 minutes.

      • Two Factor - Enables the second factor authentication after SAML.

      • Assertion Consumer Service Index - Index/ID of the metadata entry corresponding to this configuration.

      • Attribute Consuming Service Index - Index/ID of the attribute specification at the IdP. The IdP locates the attributes requested by SP using this index and send those attributes in the SAML assertion.

      • Requested Authentication Context - Specifies the context requirements of the authentication statements returned in the response.

      • Authentication Class Types - Specifies the authentication class types that are requested from the IdP.

      • Custom Authentication Class Types - Specifies the custom authentication class reference to be sent as part of the authentication request sent by the SP to SAML IdP.

      • Send Thumbprint - Sends the thumbprint instead of the certificate in the SAML request.

      • Enforce Username - Choose if the username extracted from the SAML assertion can be edited on the login page while doing a second factor authentication.

      • Force Authentication - Enforces authentication at the IdP that receives the request from NetScaler.

      • Store SAML Response - Stores the entire SAML response as long as the user session is active.

2. Create a corresponding SAML policy.

   Navigate to Security > AAA-Application Traffic > Policies > Authentication > Advanced Policies > Policy and click Add.

   On the Create Authentication SAML Policy page, provide the following details:

   • Name - Specify a name for the SAML policy.
   • Action Type - Select SAML as the authentication action type.
   • Action - Select the SAML server profile to bind the SAML policy with.
   • Expression - Displays the name of the rule or expression that the SAML policy uses to determine if the user must authenticate with the SAML server. On the text box, set the value “rule = true” for the SAML policy to take effect and the corresponding SAML action to be run.

3. Bind the SAML policy to the authentication virtual server.

   Navigate to Security > AAA - Application Traffic > Virtual Servers, and associate the SAML policy with the authentication virtual server.

4. Associate the authentication server with the appropriate traffic management virtual server.

   Navigate to Traffic Management > Load Balancing (or Content Switching) > Virtual Servers, select the virtual server, and associate the authentication virtual server with it.

Points to note about the relaystateRule parameter

Configure an expression for the relaysStateRule parameter in the samlAction command for a smooth authentication redirection after the SAML assertion. The expression must include a single published domain or a list of published domains that users want to connect to, before an authentication redirection. For example, the expression must contain the domains of the front-end virtual server (VPN, load balancing, or content switching) that uses the SAML action for authentication.

We recommend using full domain names with a trailing (/). For example https://example.com/.

The following examples describe the RelayStateRule parameter configuration examples for single domain and multiple domain scenarios:

For a single domain:

set samlAction <samlActionName> -relaystateRule "AAA.LOGIN.RELAYSTATE.EQ(\"https://example1.com/\")"

For multiple domains:

Use pattern sets to add multiple domains:

add patset test1

bind patset test1 "https://example1.com/"

bind patset test1 "https://test1.com/"

bind patset test1 "https://10.11.11.112/"

set samlAction <samlActionName> -relaystateRule AAA.LOGIN.RELAYSTATE.CONTAINS_ANY("test1")
<!--NeedCopy-->

To configure RegEx pattern matching for the FQDN:

set samlaction <samlActionName> -relaystateRule "AAA.LOGIN.RELAYSTATE.REGEX_MATCH(re#^https://[a-zA-Z0-9]*\.example1\.com/#)"
<!--NeedCopy-->

Specify the “^” sign (^https) at the starting of the domain and specify the forward slash “/” at the end of the expression (example: example1\.com/).

Following are some of definitions of the RelayStateRule expressions:

EQ: Exact match.
CONTAINS: Domain inclusion.
CONTAINS_ANY: Match any domain from a PATSET.
REGEX_MATCH: Regex-based matching.
<!--NeedCopy-->