Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

NetScaler as a SAML IdP

December 12, 2024
Contributed by: 
C C B

The SAML IdP (Identity Provider) is a SAML entity that is deployed on the customer network. The IdP receives requests from the SAML SP and redirects users to a logon page, where they must enter their credentials. The IdP authenticates these credentials with the active directory (external authentication server, such as LDAP) and then generates a SAML assertion that is sent to the SP.

The SP validates the token, and the user is then granted access to the requested protected application.

When the NetScaler appliance is configured as an IdP, all requests are received by an authentication virtual server that is associated with the relevant SAML IdP profile.

Note

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

When used as a SAML IdP, a NetScaler appliance:

  • Supports all authentication methods that it supports for traditional logons.

  • Digitally signs assertions.

  • Supports single-factor and two-factor authentication. SAML must not be configured as the secondary authentication mechanism.

  • Can encrypt assertions by using the public key of the SAML SP. This is recommended when the assertion includes sensitive information.

  • Can be configured to accept only digitally signed requests from the SAML SP.

  • Can log on to the SAML IdP by using the following 401-based authentication mechanisms: Negotiate, NTLM, and Certificate.

  • Can be configured to send 16 attributes in addition to the NameId attribute. The attributes must be extracted from the appropriate authentication server. For each of them, you can specify the name, the expression, the format, and a friendly name in the SAML IdP profile.

  • If the NetScaler appliance is configured as a SAML IdP for multiple SAML SP, a user can gain access to applications on the different SPs without explicitly authenticating every time. The NetScaler appliance creates a session cookie for the first authentication, and every subsequent request uses this cookie for authentication.

  • Can send multi-valued attributes in a SAML assertion.

  • Supports post and redirect bindings. Support for artifact binding is introduced in NetScaler release 13.0 Build 36.27.

  • 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 must be accepted. The skew time can be configured on the SAML SP and the SAML IdP.

  • Can be configured to serve assertions only to SAML SPs that are pre-configured on or trusted by the IdP. For this configuration, the SAML IdP must have the service provider ID (or issuer name) of the relevant SAML SPs.

    Note

    • Before you proceed, make sure that you have an authentication policy that is bound to an LDAP authentication virtual server.

    • For details on how to configure an LDAP action to retrieve the required attributes, see Name-value attribute support for LDAP authentication.

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

  1. Create a SAML IdP profile.

    Example

    Adding NetScaler appliance as an IdP with SiteMinder as the SP.

    add authentication samlIdPProfile samlIDPProf1 -samlSPCertName siteminder-cert -encryptAssertion ON -metadataUrl https://samlidp.example.com/metadata -samlIdPCertName ns-cert -assertionConsumerServiceURL https://example.com/cgi/samlauth -rejectUnsignedRequests ON -signatureAlg RSA-SHA256 -digestMethod SHA256 –acsUrlRule AAA.LOGIN.SAML_REQ_ACS_URL.REGEX_MATCH(re#^https://example\.com/cgi/samlauth$#)

  2. Configure the SAML IdP profile. In the following example, the IdP session contains the “userPrincipalName” attribute.

    set samlidPProfile SAML-IDP-Profile -Attribute1 "userPrincipalName" -Attribute1Expr "AAA.USER.ATTRIBUTE(\"userPrincipalName\")"

    Points to note

    • In the SAML IdP profile, configure acsURLRule that takes an expression of the list of applicable service provider URLs for this IdP. This expression depends on the SP being used. If NetScaler is configured as SP, the ACS URL is https://<SP-domain_name>/cgi/samlauth. It is recommended that you have a full URL in the expression for matching.

    • If you want the SAML IdP to allow only one ACS URL, use the following command:

      The following CLI example uses https://testlb.aaa.local as the ACS URL:

       set samlidpprofile SAML_IDP_profile -acsurlrule  "AAA.LOGIN.SAML_REQ_ACS_URL.eq(\"https://testlb.aaa.local\")"
 <!--NeedCopy-->

    • If you want the SAML IdP to match the ACS URL with a regular expression, use the following expression:

      –acsUrlRule AAA.LOGIN.SAML_REQ_ACS_URL.REGEX_MATCH(re#^https://example.com/cgi/samlauth$#)

      The above expression ensures that the ACS URL matches with https://example.com/cgi/samlauth. The “^” sign at the beginning of the regular expression ensures that NetScaler does not allow anything before “https”. The “$” sign at the end of the regular expression ensures that NetScaler does not allow anything after “samlauth”.

      If the expression is -acsUrlRule AAA.LOGIN.SAML_REQ_ACS_URL.REGEX_MATCH(re#https://example.com/cgi/#), the SAML IdP allows any ACS URL as shown in the following examples:

      • https://example.com/cgi/samlauth

      • abcdhttps://example.com/cgi/xyz

      • https://example.com/cgi/abcde

    • Some third-party SPs do not specify or send the ACS URL in SAML authentication requests. In such cases, use the following expression in the SAML IdP profile:

      AAA.LOGIN.SAML_REQ_ACS_URL.LENGTH.EQ(0) || AAA.LOGIN.SAML_REQ_ACS_URL.EQ("https://fqdn/endpoint")

    • SAML supports only RSA certificate. Other certificates like HSM, FIPS are not supported.

      For more details on the 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.

    • If the IdP logout URL is different from the redirect URL and the user is on the NetScaler login page for more than 2 minutes, a server error HTTP/1.1 Internal Server Error 43549 appears when the user attempts to authenticate. The NetScaler logs display a message indicating that the incoming post logout redirect URL is not in the allowlisted logout redirect URLs for the user.

      To resolve this issue, bind the pattern set as shown in the following example:

      bind patset ns_aaa_oauthidp_logout_redirect_uris "https://FQDN and path to the logout url"

    • If the authentication virtual server is configured as a SAML SP, the metadata URL that must be used in the SAML IdP profile is https://<netscaler-saml-sp-fqdn>/metadata/samlsp/saml_sp_act. For example,

      add authentication samlIdPProfile SAML_IDP_profile -samlIdPCertName aaa_local -assertionConsumerServiceURL "https://ksav.ksaaa.local/cgi/samlauth" -samlIssuerName "https://ksidp1.aaa.local/saml/login" -rejectUnsignedRequests OFF -serviceProviderID kslb.ksaaa.local -signAssertion NONE -SPLogoutUrl "https://ksav.ksaaa.local/cgi/tmlogout" -logoutBinding REDIRECT -metadataUrl "https://ksav.ksaaa.local/metadata/samlsp/saml_sp_act" -metadataRefreshInterval 1

  3. Configure the SAML authentication policy and associate the SAML IdP profile as the action of the policy.

    add authentication samlIdPPolicy samlIDPPol1 -rule true -action samlIDPProf1

    Note:

    If the policy name includes one or more spaces, enclose the name in double or single quotation marks (for example, “my policy” or ‘my policy’).

  4. Bind the policy to the authentication virtual server.

    bind authentication vserver saml-auth-vserver -policy samlIDPPol1 -priority 100

    For more details on the command, see https://developer-docs.netscaler.com/en-us/adc-command-reference-int/current-release/authentication/authentication-samlidpprofile.

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

  1. Configure a SAML IdP profile. This profile is used to verify the incoming authentication requests from the SP, and create and sign the assertion before sending it to the SP.

    Navigate to Security > AAA - Application Traffic > Policies > Authentication Advanced Policies > SAML IDP Policies.

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

    Parameter descriptions:

    • Name - The name of the new SAML single sign-on profile.

    • Export SAML IdP Metadata - Click this link if you want to export the metadata of the SAML IdP profile to a NetScaler Gateway VPN virtual server.

    • Import Metadata - This option imports the SAML IdP metadata. This option is enabled by default.

    • Assertion Consumer Service Url - The URL to which the assertion is to be sent.

    • Service Provider Logout URL - The SP endpoint to which logout messages are to be sent.

    • Logout Binding – Specifies the transport mechanism of the SAML logout messages. Available options are POST and REDIRECT.

    • SAML SP Metadata URL – The URL that is used to obtain the SAML IdP metadata.

      Note:

      When the SAML SP metadata URL is configured, the following parameters are taken from the SAML IdP profile and are auto-filled in the SAML SP configuration:

      • Assertion Consumer Service URL
      • Service Provider Logout URL
      • SP Certificate Name
      • Logout Binding
      • SAML Binding
      • Sign Assertion

    • Metadata Refresh Interval (mins) - The time interval (in minutes) for fetching the metadata from the specified metadata URL. The default time interval is 3600 minutes.

    • Assertion Consumer Service URL Rule - Expression that defines the allowed ACS URLs that come from a SAML SP. In other words, it allowlists ACS URLs to prevent attacks that insert rogue ACS URLs in SAML requests.

    • Assertion Consumer Service URL - The URL that the authenticated user is redirected to.

    • IdP Certificate Name - Certificate-Key pair used for the authentication page.

    • SP Certificate Name - Certificate of the Service Provider in this scenario, the key is not required for this.

    • Sign Assertion - The option to sign the assertion and the response when redirecting the client back to the Service Provider.

    • Issuer Name - A string value included in the SAML assertion issued by IdP.

    • Service Provider ID - Unique ID that is specified on SP to help identify the service provider. The ID can be anything and is not necessarily a URL. But the ID must be the same on both SP and IdP profiles.

    • Default Authentication Group - The default group that is chosen when an authentication succeeds, in addition to the extracted groups. This group is useful for admins using the nFactor flow to decide the appropriate configurations for the relaying party. For example, when you configure an authentication policy, you can specify the default group name as part of the following expression:

      AAA.USER.IS_MEMBER_OF("Default Authentication Group name").

    • Reject Unsigned Requests - Option that you can specify to ensure only assertions signed with the SP Certificate are accepted.

    • Audience - The Audience to whom the assertion is sent by the IdP. This is usually an entity name or a URL that represents the SP.

    • Skew Time (mins) - 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.

    • NAME ID format - Format of name identifier sent in the assertion.

    • Name ID expression - Expression that is evaluated to obtain the name identifier to be sent in the assertion.

    • Sign Assertion - Option to sign portions of the assertion sent by the IdP. The available options are None, Assertion, Response, or Both.

    • Signature Algorithm - Algorithm used to sign and verify the assertions between the IdP and SP, this needs to be the same on the IdP profile and the SP profile.

    • Digest Method - Algorithm used to verify the integrity of the Assertions between IdP and SP, this needs to be the same on the IdP profile and the SP profile.

    • 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. Associate the SAML IdP policy with an authentication virtual server. For Artifact binding, the transport mechanism on the SP and IdP must be the same.

      Note:

      For NetScaler SAML artifact binding, the Artifact Resolution Service URL value must be in the following format:

      https://<your-idp-hostname>/saml/idp/artifactresolve

    • Attribute 1 - Name of the attribute in SAML assertion whose value must be extracted and stored as attribute1. A similar pattern is applicable to the remaining attributes as well.

    • Attribute1Expr - Expression that is evaluated to obtain attribute 1’s value.

    • Attribute1FriendlyName - Name of attribute 1 that must be sent in the SAML assertion.

    • Attribute1Format - Format of attribute 1 to be sent in the SAML assertion.

  2. Configure the SAML authentication policy and associate the SAML IdP profile as the action of the policy.

    Navigate to Security > AAA - Application Traffic > Policies > Authentication Advanced Policies > SAML IDP Policies.

    Select Policies, click Add, enter values for the following parameters, and click Create.

    Parameter descriptions:

    • Name - Name of the SAML IdP authentication policy.

    • Action - Name of the SAML IdP profile to apply to requests or connections that match this policy.

    • Log Action - Name of message log action to use when a request matches this policy. Select a log action from the drop-down list or create a log action by clicking Add.

    • Undefined-Result Action - Action to perform if the result of a policy evaluation is undefined. An undefined event indicates an internal error condition. Only the built-in actions can be used.

    • Comments - Any comments to preserve information about this policy.

  3. Associate the SAML IdP policy with an authentication virtual server.

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

NetScaler as a SAML IdP
December 12, 2024
Contributed by: 
C C B
December 12, 2024
Contributed by: 
C C B

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.