Configuring SAML Authentication
The Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization between Identity Providers (IdP) and Service Providers. Citrix 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 Citrix 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, Citrix Gateway rejects user authentication if the signing certificate name is not configured.
Citrix 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, the 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 sends the information back so that when the sending party gets the assertion along with RelayState, the sending party knows what to do next. It is recommended that you encrypt or obfuscate the RelayState.
Note
When Citrix Gateway is used as an IdP to Citrix Cloud, you need not configure the RelayState rule on Citrix Gateway.
In case of IdP chaining, it is sufficient to configure the RelayState rule only on the first SAML policy. In this context, IdP chaining is a scenario where a configured SAML action refers to an authentication virtual server IdP containing another SAML action.
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 ADFS server to be compatible with Citrix 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 Citrix 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 Citrix 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 Citrix 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 Citrix 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. Citrix 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 Citrix Gateway virtual server URL, such as
https:netScaler.virtualServerName.com/cgi/samlauth.This URL is the Assertion Consumer Service URL on the Citrix Gateway appliance. This is a constant parameter and Citrix Gateway expects a SAML response on this URL.
-
Relying party trust identifier. Enter the name Citrix 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 you 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 Citrix 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. Perform 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 must be the following:
pre codeblock => 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"); <!--NeedCopy-->
After you configure AD FS settings, download the AD FS signing certificate and then create a certificate key on Citrix Gateway. You can then configure SAML authentication on Citrix 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.
- It is recommended that you configure actual user names instead of opaque strings.
- SAML cannot be bound as the secondary authentication type.