Product Documentation
Download:PDFPRINT

Configuring SAML Authentication

Mar 05, 2014

The Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization between Identity Providers (IdP) and Service Providers. NetScaler Gateway supports SAML authentication.

When you configure SAML authentication, you create the following settings:

  • IdP Certificate Name. This is the public key that corresponds to the private key at the IdP.
  • Redirect URL. This is the URL of the authentication IdP. Users who are not authenticated are redirected to this URL.
  • User Field. You can use this field to extract the user name if the IdP sends the user name in a different format than the NameIdentifier tag of the Subject tag. This is an optional setting.
  • Signing Certificate Name. This is the private key of the NetScaler Gateway server that is used to sign the authentication request to the IdP. If you do not configure a certificate name, the assertion is sent unsigned or the authentication request is rejected.
  • SAML Issuer name. This value is used when the authentication request is sent. There must be a unique name in the issuer field to signify the authority from which the assertion is sent. This is an optional field.
  • Default authentication group. This is the group on the authentication server from which users are authenticated.
  • Two Factor. This setting enables or disables two-factor authentication.
  • Reject unsigned assertion. If enabled, NetScaler Gateway rejects user authentication if the signing certificate name is not configured.

NetScaler Gateway supports HTTP POST-binding. In this binding, the sending party replies to the user with a 200 OK that contains a form-auto post with required information. Specifically, that default form must contain two hidden fields called SAMLRequest and SAMLResponse, depending on whether the form is a request or response. The form also includes RelayState, which is a state or information used by the sending party to send arbitrary information that is not processed by relying party. The relying party simply sends the information back so that when the sending party gets the assertion along with RelayState, the sending party knows what to do next. Citrix recommends that you encrypt or obfuscate RelayState.

Configuring Active Directory Federation Services 2.0

You can configure Active Directory Federation Services (AD FS) 2.0 on any Windows Server 2008 or Windows Server 2012 computer that you use in a federated server role. When you configure the AD FS server to work with NetScaler Gateway, you need configure the following parameters by using the Relying Party Trust Wizard in Windows Server 2008 or Windows Server 2012.

Windows Server 2008 Parameters

  • Relying Party Trust. You provide the NetScaler Gateway metadata file location, such as https://vserver.fqdn.com/ns.metadata.xml, where vserver.fqdn.com is the fully qualified domain name (FQDN) of the NetScaler Gateway virtual server. You can find the FQDN on the server certificate bound to the virtual server.
  • Authorization Rules. You can allow or deny users access to the relying party.

Windows Server 2012 Parameters

  • Relying Party Trust. You provide the NetScaler Gateway metadata file location, such as https://vserver.fqdn.com/ns.metadata.xml, where vserver.fqdn.com is the fully qualified domain name (FQDN) of the NetScaler Gateway virtual server. You can find the FQDN on the server certificate bound to the virtual server.
  • AD FS Profile. Select the AD FS profile.
  • Certificate. NetScaler Gateway does not support encryption. You do not need to select a certificate.
  • Enable support for the SAML 2.0 WebSSO protocol. This enables support for SAML 2.0 SSO. You provide the NetScaler Gateway virtual server URL, such as https:<netScaler.virtualServerName.com>/cgi/samlauath.

    This URL is the Assertion Consumer Service URL on the NetScaler Gateway appliance. This is a constant parameter and NetScaler Gateway expects a SAML response on this URL.

  • Relying party trust identifier. Enter the name NetScaler Gateway. This is a URL that identifies relying parties, such as https://<netscalerGateway.virtualServerName.com/adfs/services/trust.
  • Authorization Rules. You can allow or deny users access to the relying party.
  • Configure claim rules. You can configure the values for LDAP attributes by using Issuance Transform Rules and use the template Send LDAP Attributes as Claims. You then configure LDAP settings that include:
    • Email addresses
    • sAMAccountName
    • User Principal Name (UPN)
    • MemberOf
  • Certificate Signature. You can specify the signature verification certificates by selecting the Properties of a Relaying Party and then adding the certificate.

    If the signing certificate is less than 2048 bits, a warning message appears. You can ignore the warning to proceed. If your are configuring a test deployment, disable the Certificate Revocation List (CRL) on the Relaying Party. If you do not disable the check, AD FS tries the CRL to validate the certificate.

    You can disable the CRL by running the following command: Set-ADFWRelayingPartyTrust - SigningCertficateRevocatonCheck None-TargetName NetScaler

After you configure the settings, verify the relying party data before you complete the Relaying Party Trust Wizard. You check the NetScaler Gateway virtual server certificate with the endpoint URL, such as https://vserver.fqdn.com/cgi/samlauth.

After you finish configuring settings in the Relaying Party Trust Wizard, select the configured trust and then edit the properties. You need to do the following:

  • Set the secure hash algorithm to SHA-1.
    Note: Citrix supports SHA-1 only.
  • Delete the encryption certificate. Encrypted assertions are not supported.
  • Edit the claim rules, including the following:
    • Select Transform Rule
    • Add Claim Rule
    • Select Claim Rule Template: Send LDAP attributes as claims
    • Give a Name
    • Select Attribute Store: Active Directory
    • Select LDAP attribute: <Active Directory parameters>
    • Select Out Going Claim Rule as "Name ID"
    Note: Attribute Name XML tags are not supported.
  • Configure the Logout URL for Single Sign-off. The claim rule is Send logout URL. The custom rule should be the following: 
    => issue(Type = "logoutURL", Value = "https://<adfs.fqdn.com>/adfs/ls/", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/attributename"] = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified");

After you configure AD FS settings, download the AD FS signing certificate and then create a certificate key on NetScaler Gateway. You can then configure SAML authentication on NetScaler Gateway by using the certificate and key.

Configuring SAML Two-Factor Authentication

You can configure SAML two-factor authentication. When you configure SAML authentication with LDAP authentication, use the following guidelines:

  • If SAML is the primary authentication type, disable authentication in the LDAP policy and configure group extraction. Then, bind the LDAP policy as the secondary authentication type.
  • SAML authentication does not use a password and only uses the user name. Also, SAML authentication only informs users when authentication succeeds. If SAML authentication fails, users are not notified. Since a failure response is not sent, SAML has to be either the last policy in the cascade or the only policy.
  • Citrix recommends that you configure actual user names instead of opaque strings.
  • SAML cannot be bound as the secondary authentication type.