NetScaler as a SAML IdP

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 NetScaler is configured as an IdP, all requests are received by an authentication virtual server that is associated with the relevant SAML IdP profile.

Note

• NetScaler 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.

• NetScaler, when acting as an OpenID Provider, issues a bearer token for client credential requests and provides user information in JSON format through the introspection endpoint. Currently, the JWT (JSON Web Token) format is not supported in NetScaler.

When used as a SAML IdP, NetScaler:

• 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 NetScaler 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. NetScaler 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 NetScaler 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 SAML_IDP_profile -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\")"
       

   • 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 preceding 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

   • By default, group attributes are sent in the following format in the SAML response when NetScaler acts as a SAML IdP:

      <saml:AttributeValue>grp2</saml:AttributeValue>
      <saml:AttributeValue>grp1</saml:AttributeValue>
       

     You can customize the format of group attributes sent in SAML responses using the following two methods:

     • Enabling comma-separated values

     • Modifying XML tags

     Enabling comma-separated values:

     If you want all group attributes to be sent in a single <saml:AttributeValue> tag, separated by commas (for example, grp2, grp1), enable a specific nsapimgr knob using the following command.

      nsapimgr_wr.sh -ys call=ns_saml_enable_comma_sep_attr_res
       

     The nsapimgr knob is disabled by default.

     Resulting group attribute format: <saml:AttributeValue>grp2,grp1</saml:AttributeValue>

     To disable the nsapimgr knob, run the following command:

      nsapimgr_wr.sh -ys call=ns_saml_disable_comma_sep_attr_res
       

     Modifying XML tags:

     If you want to change the XML tag used for group attributes (for example, from <saml:AttributeValue> to <saml:AttrValue>), use the AAA.USER.GROUPS_AS_XML expression. The AAA.USER.GROUPS_AS_XML expression allows you to specify a custom XML tag (for example, saml:AttrValue) for the group attributes in the SAML response.

     At the command prompt, type:

      set samlidpprofile SAML_IDP_profile -attribute1 groups -attribute1Expr AAA.USER.GROUPS_AS_XML("saml:AttrValue")
       

     Resulting group attribute format:

     <saml:AttrValue>grp2</saml:AttrValue>
     <saml:AttrValue>grp1</saml:AttrValue>
       

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 NetScaler 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.

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

   2. On the Profiles tab, click Add, enter the 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.

     • If the Import Metadata option is disabled, enter the values for the following parameters:

       • Assertion Consumer Service Url: The URL to which the assertion must be sent.

       • Service Provider Logout URL: The SP endpoint to which logout messages must be sent.

       • 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

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

       • SP Certificate Name: Name of the SSL certificate of SAML relying party. This certificate is used to verify signature of the incoming AuthnRequest from a relying party or service provider. Maximum Length = 63.

   • 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 is evaluated to allow Assertion Consumer Service URI coming in the SAML Request. Maximum Length = 8191.

   • IDP Certificate Name: Name of the certificate used to sign the SAML response that is sent to the relying party or service provider after successful authentication. Maximum Length = 63.

   • Issuer Name: The name to be used in requests sent from NetScaler Gateway to IdP to uniquely identify NetScaler Gateway. Maximum Length = 511.

   • Service Provider ID: Unique identifier of the service provider that sends SAML request. NetScaler Gateway ensures that the issuer of the SAML request matches this URI. If there is an SP initiated sign-in scenario, this value must be same as samlIssuerName configured in samlAction. Maximum Length = 511.

   • 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").

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

   • Skew Time (mins): This option specifies the number of minutes on either side of the current time that the assertion is valid. For example, if skewTime is 10, then assertion is valid from (current time - 10) min to (current time + 10) min, that is, 20 min in all. Default = 5.

   • Sign Assertion: Option to sign portions of an assertion when NetScaler Gateway IdP sends one. Based on the user selection, either ASSERTION or RESPONSE or BOTH or NONE can be signed.

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

   • Name ID Expression: Expression that is evaluated to obtain the NameIdentifier to be sent in the assertion.

   • Reject Unsigned Requests: Option to reject unsigned SAML requests. When enabled, NetScaler Gateway denies any authentication requests that arrive without signature.

   • Signature Algorithm: Algorithm used to sign and verify the assertions between the IdP and SP. This algorithm must 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 parameter must be the same on the IdP profile and the SP profile.

   • 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.

   • Attribute1 Expression: Expression that is evaluated to obtain attribute 1’s value.

   • Attribute1 Format: Format of attribute 1 to be sent in the SAML assertion.

   • Attribute1 Friendly Name: Name of attribute 1 that must be sent in the SAML assertion.

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

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

   2. On the Policies tab, click Add, enter the 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.

   • Expression: Expression, which is evaluated to choose a profile for authentication.

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

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

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