Category: Citrix ADC 12.1

Self-Service Password Reset (SSPR) – Citrix ADC

Last Modified: Dec 28, 2020 @ 5:49 am

33 Comments

Navigation

SSPR Flow

The SSPR feature in Citrix ADC is completely unrelated to the SSPR in Citrix StoreFront. They are separate registrations.

  • ADC SSPR registration is stored in an Active Directory user attribute.

SSPR is available in Citrix ADC 12.1 build 51.16 and higher.

SSPR requires nFactor, which is only available in Citrix ADC Advanced Edition and Premium Edition. You can use nFactor with Citrix Gateway.

The first factor is a Login Schema that has an optional Forgot Password link. The Login Schema file named SingleAuthPasswordResetRem.xml has this link. There are other built-in Login Schemas for Username Only and Dual Auth that also have the link.

If the user logs in normally, then ADC checks if the user has been enrolled in SSPR or not. If not enrolled, then the user is prompted to select questions and provide answers. This is a custom Login Schema that you can create from the ADC GUI as described later.

If the user clicks the Forgot Password link, then the user is prompted to answer two of the previously enrolled questions.

  • Optionally, the user might be prompted to retrieve a One-time password (OTP) sent to an Alternate Email address. The user might not have access to corporate email, so the OTP should be sent to the user’s personal email address. The user enters the alternate email address during SSPR registration.

  • Finally, the user is prompted to enter a new password.

Here’s what a sample SSPR nFactor configuration looks like:

# ** nFactor Visualizer 
# ** ------------------ 
# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"
# **    Adv Authn Policy = LDAP_Password_Reset
# **       Priority = 10
# **       Rule = "aaa.LOGIN.VALUE(\"passwdreset\").EQ(\"1\")"
# **       Action = ldapAction named LDAP-Corp_NoAuth
# **       Goto if failed = NEXT
# **       Next Factor if Success = kba_validation
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = kba_validation
# **             Priority = 10
# **             Rule = true
# **             Action = ldapAction named LDAP-Corp_NoAuth
# **             Goto if failed = NEXT
# **             Next Factor if Success = email_validation
# **                Login Schema Profile = LSCHEMA_INT
# **                Adv Authn Policy = email_validation
# **                   Priority = 10
# **                   Rule = true
# **                   Action = emailAction named EmailOTP
# **                   Goto if failed = NEXT
# **                   Next Factor if Success = password_reset
# **                      Login Schema Profile = LSCHEMA_INT
# **                      Adv Authn Policy = LDAP-Corp-Adv_NoAuth
# **                         Priority = 100
# **                         Rule = true
# **                         Action = ldapAction named LDAP-Corp_NoAuth
# **                         Goto if failed = NEXT
# **    Adv Authn Policy = LDAP-Corp-Adv
# **       Priority = 20
# **       Rule = true
# **       Action = ldapAction named LDAP-Corp
# **       Goto if failed = NEXT
# **       Next Factor if Success = check_for_sspr_registration
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = switch_to_kba_register
# **             Priority = 1
# **             Rule = "AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"0\")"
# **             Action = NO_AUTHN
# **             Goto if failed = NEXT
# **             Next Factor if Success = kba_registration
# **                Login Schema Profile = lschema_KBARegistration
# **                Adv Authn Policy = first_time_login_forced_kba_registration
# **                   Priority = 1
# **                   Rule = true
# **                   Action = ldapAction named LDAP-Corp
# **                   Goto if failed = NEXT
# **          Adv Authn Policy = NoAuth
# **             Priority = 100
# **             Rule = true
# **             Action = NO_AUTHN
# **             Goto if failed = END

Active Directory User Attribute

Citrix ADC SSPR stores its configuration in an Active Directory User attribute.

The attribute must be dedicated to SSPR. You can’t use the same attribute that you might already be using for Citrix ADC One-time passwords (OTP).

  • In Active Directory Users and Computers, enable Advanced Features mode (from the View menu), double-click a user, switch to the Attribute Editor tab, and find a String attribute that is not being used. When you double-click an attribute, look for String in the window title.
  • Open the Active Directory Schema console. Under Attributes, find your candidate attribute and double-click it. Make sure the Maximum length is high (e.g. 32767). The extensionAttributes default to 1024 or 2048, which is not long enough.
  • You might want to uncheck the bottom boxes (e.g. Attribute is copied when duplicating a user) since each user has their own SSPR configuration.
  • ADC needs permissions to set this Attribute and reset user passwords. You can use the Delegate Control wizard to grant these permissions.

    1. Consider creating a group for SSPR Admins and delegating permissions to that group. You can add your LDAP Bind Account and your Service Desk accounts to this group.
    2. In the Tasks to Delegate page, change it to Create a custom task to delegate and click Next.
    3. In the Active Directory Object Type page, change the selection to Only the following objects in this folder and select User objects. Click Next.
    4. In the Permissions page, on the top of the page, check the box for Property-specific.
    5. In the Permissions list, check the box next to Reset password. Scroll down.
    6. Find the attribute you are using for SSPR and check the Read and Write boxes. Click Next.

Help Desk will need to be trained to reset a user’s SSPR registration by double-clicking the attribute and clicking the Clear button. The next time the user logs in, the user will be prompted to enroll for SSPR again.

ADC uses a certificate to encrypt the contents of the Attribute. It currently is not possible to configure the certificate from the GUI, so you’ll need to SSH to the ADC and run the following command. The certificate should already be installed on the ADC.

bind vpn global -userDataEncryptionKey MyCertificate

The ADC SSPR configuration needs two LDAP Policy/Servers: one with authentication enabled, and one without authentication. In both LDAP Servers, in the Other Settings section, enter the Attribute name into the Alternate Email field and in the KB Attribute field. The same attribute can be used for both. However, you cannot use the same attribute for the OTP Secret field.

SSPR KBA Registration Login Schema

When creating the KBA Registration Login Schema you will be prompted to choose from a list of questions. This list is configured in the file KBQuestions.json located in /nsconfig/loginschema/LoginSchema.

  1. In ADC GUI, on the left, expand Security, expand AAA – Application Traffic, and click Login Schema.
  2. On the right, switch to the Profiles tab.
  3. On the right, click the button labelled Add KBA Registration Login Schema.
  4. Give the new Schema a name. ADC will create a file with the same name.
  5. Configure at least two questions. Move questions from the left to the right. Note: the XML file that it creates has size limits so don’t choose too many questions.
  6. On the right, you can optionally change the labels for Question Field and Answer Field. If you don’t enter anything, then the labels are Question, and Answer, as shown earlier in this article. Scroll down.
  7. Near the bottom are two More links you can click.
  8. The first More link lets you allow users to enter their own questions.
  9. The second More link lets you enable Register Alternate Email.
  10. Click Create when done.
  11. ADC creates a file in /nsconfig/loginschema/LoginSchema that matches the Schema name you entered earlier.
  12. ADC also adds a Login Schema Profile with the same name you entered earlier.

LDAP Servers

You’ll need two LDAP Servers: one with Authentication enabled, and the other with Authentication unchecked. Other than the Authentication checkbox, they are identical. Configure them like normal LDAP Servers.

The NoAuth server has Authentication unchecked.

Configure both LDAP Servers with the SSPR attribute as detailed earlier.

Email Action and Policy

You can optionally configure an Email action to send the user a OTP before allowing the password reset.

  1. In the ADC GUI, the easy way to find Email Actions is to enter “email” in the top left search box.
  2. On the right, click Add.
  3. Give the Email Action a name.
  4. In the Username box, enter the From email address. The emails will look like they come from this address.
  5. Enter the SMTP password for this From address.
  6. In the Server URL box, enter a smtps URL with port number similar to smtps://mail01.corp.com:587. Gmail’s URL smtps://smtp-relay.gmail.com:587 also works.
  7. In the Content box, enter a string containing $code. ADC replaces $code with the OTP.
  8. In the Type box, enter SMTP.
  9. In the Email Address box, enter aaa.user.attribute("alternate_mail"). This expression pulls the destination email address from Alternate Email attribute you defined in your LDAP Server.
  10. Click Create.
  11. It does not appear to be possible to use the ADC GUI to create an Email Authentication Policy. SSH to your ADC and run something similar to the following command: 
    add authentication Policy email_validation -rule true -action EmailOTP

SSPR nFactor Configuration

AAA vServer and Login Schema

The first factor will be a Login Schema that has the Reset Password link. This section creates the following portion of the nFactor configuration:

# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"

Do the following:

  1. Create a AAA vServer.
  2. It can be Non Addressable.
  3. Optionally bind a certificate to the AAA vServer so its status will be Green instead of Red.
  4. On the right, in the Advanced Settings column, click Login Schemas to move it to the left.
  5. On the left, in the Login Schemas section, click where it says No Login Schema.
  6. Next to the Select Policy field, click Add to create a new Login Schema Policy.
  7. Give the Login Schema Policy a name to indicate that this Login Schema includes a link for Self-Service Password Reset.
  8. Next to Profile, click Add to create a new Login Schema Profile.
  9. Give the Login Schema Profile a name.
  10. In the Authentication Schema field, click the edit icon.
  11. In the Login Schema Files section, click the LoginSchema folder.
  12. Highlight one of the PasswordReset files (e.g. SingleAuthPasswordResetRem.xml) and then click the blue Select button on the top right. You can also optionally modify the built-in files.
  13. The Create Authentication Login Schema window collapses and the Authentication Schema field shows the selected file. Click Create when done.
  14. Click Create to finish creating the Authentication Login Schema Policy.
  15. Click Bind to bind the Login Schema Policy to the AAA vServer.

SSPR Registration

Let’s start with the SSPR Registration flow. This section creates the following snippet of the full nFactor configuration:

# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"
# **    Adv Authn Policy = LDAP-Corp-Adv
# **       Priority = 20
# **       Rule = true
# **       Action = ldapAction named LDAP-Corp
# **       Goto if failed = NEXT
# **       Next Factor if Success = check_for_sspr_registration
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = switch_to_kba_register
# **             Priority = 1
# **             Rule = "AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"0\")"
# **             Action = NO_AUTHN
# **             Goto if failed = NEXT
# **             Next Factor if Success = kba_registration
# **                Login Schema Profile = lschema_KBARegistration
# **                Adv Authn Policy = first_time_login_forced_kba_registration
# **                   Priority = 1
# **                   Rule = true
# **                   Action = ldapAction named LDAP-Corp
# **                   Goto if failed = NEXT
# **          Adv Authn Policy = NoAuth
# **             Priority = 100
# **             Rule = true
# **             Action = NO_AUTHN
# **             Goto if failed = END

Do the following:

  1. In the AAA vServer, scroll down to the Advanced Authentication Policies section and click where it says No Authentication Policy.
  2. In the Select Policy field, select your normal LDAP policy. The Login Schema collects username and password and verifies it with the LDAP Policy that you select here.
  3. Change the Priority to 20 or similar. This binding must be a higher number than the Password Reset flow that we configure later.
  4. Next to the Select Next Factor field, click Add to create a Policy Label which will check if the user is registered or not.
  5. Name the Policy Label to indicate that this Policy Label checks if the user is registered or not.
  6. Leave the Login Schema set to LSCHEMA_INT (i.e. no schema), and click Continue.
  7. Next to the Select Policy field, click Add to create an Authentication Policy.
  8. Name this Authentication Policy to indicate that it does nothing more than check if the user is registered or not.
  9. In the Expression field, enter the following expression: 
    AAA.USER.ATTRIBUTE("kba_registered").EQ("0")
  10. Click Create.
  11. Back in the Policy Label Policy Binding window, next to the Select Next Factor field, click Add to create another Policy Label.
  12. Name the Policy Label to indicate that this factor performs the SSPR Registration (i.e. Knowledge-Based Authentication registration).
  13. In the Login Schema field, select the KBA Registration Login Schema that you created earlier.
  14. Click Continue.
  15. Next to the Select Policy field, click Add to create an Authentication Policy.
  16. Name the Authentication Policy to indicate that ADC uses this LDAP Server to store the KBA registration information in the Active Directory User attribute.
  17. Change Action Type to LDAP.
  18. Change Action to your normal authenticating LDAP Server that has the KB Attribute defined.
  19. For Expression, enter true.
  20. Click Create.
  21. Back in the Policy Label Policy Binding page, click Bind.
  22. Click Done to finish creating the Policy Label for KBA Registration.
  23. Back in the “Check for SSPR Registration” Policy Label Policy Binding page, click Bind.
  24. To handle users that are already registered, click Add Binding.
  25. Next to the Select Policy field, click Add to create an Authentication Policy.
  26. Name the Policy to indicate that no authentication is occurring. This policy always returns true and is necessary to avoid errors for users that are already registered.
  27. Change Action Type to NO_AUTHN.
  28. In the Expression box, enter true.
  29. Click Create.
  30. Back in the Policy Label Policy Binding screen, click Bind.
  31. Click Done to close the “Check for SSPR Registration” Policy Label.
  32. Click Bind to bind the LDAP Policy and “Check for SSPR Registration” factor to the AAA vServer.

Password Reset

This section creates the following snippet of the full nFactor configuration:

# ** AAA vserver: AAA-SSPR
# **    Login Schema Policy = lschema_password_reset
# **       Priority = 20
# **       Rule = true
# **       Login Schema XML = "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"
# **    Adv Authn Policy = LDAP_Password_Reset
# **       Priority = 10
# **       Rule = "aaa.LOGIN.VALUE(\"passwdreset\").EQ(\"1\")"
# **       Action = ldapAction named LDAP-Corp_NoAuth
# **       Goto if failed = NEXT
# **       Next Factor if Success = kba_validation
# **          Login Schema Profile = LSCHEMA_INT
# **          Adv Authn Policy = kba_validation
# **             Priority = 10
# **             Rule = true
# **             Action = ldapAction named LDAP-Corp_NoAuth
# **             Goto if failed = NEXT
# **             Next Factor if Success = email_validation
# **                Login Schema Profile = LSCHEMA_INT
# **                Adv Authn Policy = email_validation
# **                   Priority = 10
# **                   Rule = true
# **                   Action = emailAction named EmailOTP
# **                   Goto if failed = NEXT
# **                   Next Factor if Success = password_reset
# **                      Login Schema Profile = LSCHEMA_INT
# **                      Adv Authn Policy = LDAP-Corp-Adv_NoAuth
# **                         Priority = 100
# **                         Rule = true
# **                         Action = ldapAction named LDAP-Corp_NoAuth
# **                         Goto if failed = NEXT

Do the following to create the Password Reset flow:

  1. In the AAA vServer, in the Advanced Authentication Policies section, click where it says 1 Authentication Policy
  2. Note the Priority number of the existing binding. Our new binding will need a lower priority number so it is evaluated first. Click Add Binding.
  3. Next to the Select Policy field, click Add to create an Authentication Policy.
  4. Name the Authentication Policy to indicate that this policy only applies if the user clicked the Forgot Password link in the Login Schema.
  5. Change Action Type to LDAP.
  6. Change Action to the your LDAP Server that has Authentication unchecked (i.e. not enabled).
  7. In the Expression box, enter the following expression that returns true if the user clicked the link: 
    aaa.LOGIN.VALUE("passwdreset").EQ("1")
  8. Click Create.
  9. Back in the Policy Binding page, change the Priority to a number that is lower than the existing Policy Binding.
  10. Next to the Select Next Factor field, click Add to create a Policy Label (i.e. factor)
  11. Name the Policy Label to indicate that this factor will verify the user’s questions and answers.
  12. Leave the Login Schema set to the default LSCHEMA_INT (i.e. no schema) and click Continue.
  13. Next to the Select Policy field, click Add to create an Authentication Policy.
  14. Name the Authentication Policy to indicate that this policy verifies the user’s KBA questions and answers.
  15. Change Action Type to LDAP.
  16. Change Action to your LDAP Server that does not require authentication.
  17. In the Expression box, enter true.
  18. Click Create.
  19. Back in the Policy Label Policy Binding page, if you wish to add email validation, then next to Select Next Factor, click Add to create another Policy Label (factor).
  20. Name the Policy Label to indicate that this factor will perform Email OTP verification.
  21. Leave the Login Schema set to the default LSCHEMA_INT (i.e. no schema) and click Add.
  22. In the Policy Label Policy Binding section, click where it says Click to select.
  23. Click the small circle next to the email policy that you created earlier from the ADC’s command line. It’s not possible to use the GUI to create the email policy.
  24. At the top of the screen, click the blue Select button.
  25. Back in the Policy Label Policy Binding screen, next to the Select Next Factor field, click Add to create another Policy Label (i.e. factor).
  26. Name this Policy Label to indicate that this factor performs the password reset.
  27. Leave the Login Schema set to the default LSCHEMA_INT (i.e. no schema) and click Continue.
  28. In the Policy Label Policy Binding section, next to the Select Policy field, click Add to create an Authentication Policy.
  29. Name the Authentication Policy to indicate that this is your LDAP Policy that has Authentication unchecked (not enabled).
  30. Change Action Type to LDAP.
  31. Change Action to your LDAP Server that has Authentication unchecked.
  32. In the Expression field, enter true.
  33. Click Create.
  34. That’s it for the AAA configuration. Now click Bind and Done several times to return to the AAA vServer.






  35. Click Close to finish the AAA vServer’s Authentication Policy bindings.

Bind to Citrix Gateway

If you are using nFactor configuration with Citrix Gateway, then configure the Authentication Profile like normal.

  1. Go to Citrix Gateway > Virtual Servers and edit a Gateway.
  2. On the right, in the Advanced Settings column, click Authentication Profile to move it to the left.
  3. On the left, in the Authentication Profile section, click Add.
  4. Name the Authentication Profile to indicate that this nFactor Flow does Self-Service Password Reset.
  5. In the Authentication Virtual Server field, click where it says Click to select.
  6. Click the small circle next to the AAA vServer that is configured with your SSPR flow.
  7. At the top of the page, click the blue Select button.
  8. Click Create.
  9. Click OK to select the Authentication Profile.

CLI Commands

Here’s a full sample ADC CLI configuration:

# Certs
# -----
add ssl certKey WildcardCorpCom.cer_CERT_KE_ic1 -cert WildcardCorpCom.cer_ic1 -passcrypt b217e266 -encrypted -encryptmethod ENCMTHD_3

add ssl certKey WildcardCorpCom.cer_CERT_KEY -cert WildcardCorpCom.pfx -key WildcardCorpCom.pfx -inform PFX -passcrypt 52e54af -encrypted -encryptmethod ENCMTHD_3 -expiryMonitor DISABLED

add ssl certKey CorpIntermediate -cert CorpIntermediate.cer -inform DER -passcrypt cc9675 -encrypted -encryptmethod ENCMTHD_3 -expiryMonitor DISABLED

# Cert Links
# ----------
link ssl certKey WildcardCorpCom.cer_CERT_KEY CorpIntermediate

link ssl certKey CorpIntermediate WildcardCorpCom.cer_CERT_KE_ic1


# AAA Global Settings
# -------------------
enable ns feature AAA


# LDAP Actions
# ------------
add authentication ldapAction LDAP-Corp -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword 868d22c -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED -nestedGroupExtraction ON -groupNameIdentifier sAMAccountName -groupSearchAttribute memberOf -groupSearchSubAttribute CN -KBAttribute extensionAttribute1 -alternateEmailAttr extensionAttribute1

add authentication ldapAction LDAP-Corp_NoAuth -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword a4ffb4 -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED -passwdChange ENABLED -nestedGroupExtraction ON -groupNameIdentifier sAMAccountName -groupSearchAttribute memberOf -groupSearchSubAttribute CN -KBAttribute extensionAttribute1 -alternateEmailAttr extensionAttribute1


# Email (SSPR) Actions
# --------------------
add authentication emailAction EmailOTP -userName admin@corp.local -password 7868e -encrypted -encryptmethod ENCMTHD_3 -serverURL "smtps://mail01.corp.local:587" -content "Your OTP is $code" -emailAddress "aaa.user.attribute(\"alternate_mail\")"


# Advanced Authentication Policies
# --------------------------------
add authentication Policy LDAP-Corp-Adv -rule true -action LDAP-Corp

add authentication Policy kba_validation -rule true -action LDAP-Corp_NoAuth

add authentication Policy LDAP_Password_Reset -rule "aaa.LOGIN.VALUE(\"passwdreset\").EQ(\"1\")" -action LDAP-Corp_NoAuth

add authentication Policy NoAuth -rule true -action NO_AUTHN

add authentication Policy switch_to_kba_register -rule "AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"0\")" -action NO_AUTHN

add authentication Policy email_validation -rule true -action EmailOTP

add authentication Policy first_time_login_forced_kba_registration -rule true -action LDAP-Corp

add authentication Policy EmailOTP -rule true -action EmailOTP

add authentication Policy LDAP-Corp-Adv_NoAuth -rule true -action LDAP-Corp_NoAuth


# Login Schemas
# -------------
add authentication loginSchema lschema_KBARegistration -authenticationSchema "/nsconfig/loginschema/LoginSchema/lschema_KBARegistration.xml"

add authentication loginSchema lschema_password_reset -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"


# Login Schema Policies
# ---------------------
add authentication loginSchemaPolicy lschema_password_reset -rule true -action lschema_password_reset


# Authentication Policy Labels
# ----------------------------
add authentication policylabel kba_registration -loginSchema lschema_KBARegistration

bind authentication policylabel kba_registration -policyName first_time_login_forced_kba_registration -priority 1 -gotoPriorityExpression NEXT

add authentication policylabel check_for_sspr_registration -loginSchema LSCHEMA_INT

bind authentication policylabel check_for_sspr_registration -policyName switch_to_kba_register -priority 1 -gotoPriorityExpression NEXT -nextFactor kba_registration

bind authentication policylabel check_for_sspr_registration -policyName NoAuth -priority 100 -gotoPriorityExpression END

add authentication policylabel password_reset -loginSchema lschema_noschema

bind authentication policylabel password_reset -policyName LDAP-Corp-Adv_NoAuth -priority 100 -gotoPriorityExpression NEXT

add authentication policylabel email_validation -loginSchema lschema_noschema

bind authentication policylabel email_validation -policyName email_validation -priority 10 -gotoPriorityExpression NEXT -nextFactor password_reset

add authentication policylabel kba_validation -loginSchema lschema_noschema

bind authentication policylabel kba_validation -policyName kba_validation -priority 10 -gotoPriorityExpression NEXT -nextFactor email_validation


# Authentication Virtual Servers
# ------------------------------
add authentication vserver AAA-SSPR SSL 0.0.0.0

bind authentication vserver AAA-SSPR -portaltheme RfWebUI

bind authentication vserver AAA-SSPR -policy lschema_password_reset -priority 20 -gotoPriorityExpression END

bind authentication vserver AAA-SSPR -policy LDAP_Password_Reset -priority 10 -nextFactor kba_validation -gotoPriorityExpression NEXT

bind authentication vserver AAA-SSPR -policy LDAP-Corp-Adv -priority 20 -nextFactor check_for_sspr_registration -gotoPriorityExpression NEXT


# Authentication Profiles
# -----------------------
add authentication authnProfile SSPR -authnVsName AAA-SSPR


# NetScaler Gateway Global Bindings
# ---------------------------------
bind vpn global -userDataEncryptionKey WildcardCorpCom.cer_CERT_KEY


# NetScaler Gateway Virtual Servers
# ---------------------------------
add vpn vserver gateway2 SSL 10.2.4.220 443 -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -httpProfileName http2 -deploymentType ICA_STOREFRONT -authnProfile SSPR -vserverFqdn gateway3.corp.com

bind vpn vserver gateway2 -portaltheme RfWebUI

bind vpn vserver gateway2 -policy PL_OS_10.2.4.120 -priority 100

bind vpn vserver gateway2 -policy PL_WB_10.2.4.120 -priority 100


# SSL Virtual Servers
# -------------------
bind ssl vserver gateway2 -certkeyName WildcardCorpCom.cer_CERT_KEY

bind ssl vserver AAA-SSPR -certkeyName WildcardCorpCom.cer_CERT_KEY

VMware Horizon Load Balancing – NetScaler / Citrix ADC

Last Modified: Jul 25, 2024 @ 12:06 pm

135 Comments

Navigation

Use this procedure to load balance VMware Unified Access Gateway.

Change Log

Overview

To simplify this post, this post is focused on Unified Access Gateway, which is the replacement for Horizon Security Servers.

For load balancing of other Horizon components:

  • Internal Horizon Connection Servers – This is standard load balancing on SSL_BRIDGE protocol, port 443, and Source IP persistence. See the CLI commands for a sample configuration.
    • If you enabled the Secure Gateways (PCoIP, Blast) on the Connection Servers, then load balance the Connection Servers using the same procedure as load balancing UAGs.

UAG appliances vs Horizon Security Servers

There are two VMware-provided remote access solutions for Horizon View:

Unified Access Gateway appliances are preferred over Horizon Security Servers for the following reasons:

  • No need to pair with internal Connection Servers, which simplifies the configuration.
  • Linux appliance instead of Windows server.
  • Authentication can be offloaded to the Unified Access Gateway. This includes: Smart Cards, RSA, and RADIUS.
  • Blast Extreme Adaptive Transport (BEAT) in Horizon 7.1 and newer only works with Unified Access Gateway 2.9 and newer. Security Server and older Access Points don’t work.
    • VMware Blog Post Deep Dive into VMware Horizon Blast Extreme Adaptive Transport – Blast Extreme Adaptive Transport is enabled by default in VMware Horizon View 7.1 and Horizon Client 4.4. If the clients are connecting from outside the demilitarized zone (DMZ), you would also need to have VMware Unified Access Gateway (not Security Server) to take full advantage of the new transport. The adaptive transport will automatically sense the network for UDP availability and will fallback to legacy Blast TCP if UDP is not available.

Here is a typical Unified Access Gateway architecture:

  • Two Internal Connection Servers – these need to be load balanced on an internal VIP on TCP 443. Internal users connect to the internal VIP.
    • Instructions for load balancing the internal Connection Servers are not detailed in this post. Instead, see the CLI Commands.
  • Two DMZ Unified Access Gateway (Access Point) appliances – these need to be load balanced on a DMZ VIP on several ports. External users connect to the DMZ VIP.
    • Unified Access Gateway appliances connect to the internal Load Balancing VIP for the internal Connection Servers using HTTPS protocol
    • Unified Access Gateway appliances connect directly to Horizon Agents using Blast or PCoIP protocol.

During UAG configuration, you specify the address of the internal Connection Servers. The address you enter should be a DNS name that resolves to an internal load balancing VIP for the Connection Servers.

If you have split DNS, you can use the same DNS name for both external UAG access, and for internal Connection Server load balancing. Externally, configure the DNS name to resolve to the UAG Load Balancing VIP. Internally, configure the DNS name to resolve to the internal VIP that load balances the Connection Servers.

For Cloud Pod Architecture, configure separate VIPs in each datacenter. Then configure NetScaler Citrix ADC GSLB to resolve a single DNS name to multiple VIPs.

Protocols/Ports

To support Blast Extreme, PCoIP, and HTML Blast connectivity, the following ports must be load balanced to the UAGs:

  • TCP 443
  • UDP 443
  • TCP 4172
  • UDP 4172
  • TCP 8443
  • UDP 8443

The initial connection to UAG is always TCP 443 (HTTPS). If a user is load balanced on port 443 to a particular UAG, then the connection on UDP 4172 must go the same UAG. Normally load balancing persistence only applies to a single port number, so whatever UAG was selected for port 443, won’t be considered for the 4172 connection. But in NetScaler Citrix ADC, you can configure a Persistency Group to use a single persistency across multiple load balancing Virtual Servers with different port numbers. In F5, you configure Match Across Services, as detailed by Aresh Sarkari at Persistence Profile – F5 LTM Load Balancing for VMware Unified Access Gateway Appliance.

This topic primarily focuses on NetScaler Citrix ADC GUI configuration. Alternatively, you can skip directly to the CLI commands.

Load Balancing Monitors

Users connect to Unified Access Gateway appliances on multiple ports: TCP 443, UDP 443, TCP 8443, UDP 8443, TCP 4172, and UDP 4172. Create Load Balancing Monitors for each port number. Since UDP can’t be easily monitored, use TCP monitors as substitutes for UDP. That means you only need four monitors:

  • TCP 443 – HTTPS
    • HEAD /favicon.ico or GET /favicon.ico. This string can detect if UAG is in Quiesce mode, or if Connection Server is disabled in Horizon Console. See VMware 56636 for supported monitoring strings.
  • TCP 4172
  • TCP 8443

The procedure for configuring monitors changed in NetScaler 12.0 build 56 and newer.

SSL (443) Monitor for Connection Server Health

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Horizon-SSL or similar.
  4. In the Type field, click where it says Click to select.
  5. In the Monitor Types list, click the circle next to HTTP.
  6. Scroll up and click the blue Select button.
  7. To reduce UAG CPU, VMware recommends setting the Interval to 30 seconds.
  8. In the HTTP Request field, enter GET /favicon.ico. See VMware 56636 for supported health monitoring requests.
  9. Check the box next to Secure.
  10. Scroll down and click Advanced Parameters to expand it.
  11. In the Advanced Parameters section, in the Destination Port field, enter 443.
  12. Scroll down to the TROFS Code field and enter 503. When UAG is in Quiesce mode, TROFS will cause the service to transition to out of service allowing existing connections instead of directly going down and killing existing sessions. (h/t Henry Heres)
  13. Scroll down, and click Create.

PCoIP (4172) Monitor

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Horizon-PCoIP or similar.
  4. For the Type field, click where it says Click to select and select TCP from the Monitor Types list.
  5. Scroll down to Advanced Parameters, click Advanced Parameters to expand it, and then enter 4172 in the Destination Port field. This forces the monitor to connect to port 4172 even if the monitor is bound to a service group that is configured for a different port number.
  6. Scroll down, and click Create.

Blast (8443) Monitor

  1. On the left, expand Traffic Management, expand Load Balancing, and click Monitors.
  2. On the right, click Add.
  3. Name it Horizon-Blast or similar.
  4. For the Type field, click where it says Click to select and select TCP from the Monitor Types list.
  5. Scroll down to Advanced Parameters, click Advanced Parameters to expand it, and then enter 8443 in the Destination Port field. This forces the monitor to connect to port 8443 even if the monitor is bound to a service group that is configured for a different port number.
  6. Scroll down, and click Create.

UAG DDoS

NetScaler Citrix ADC Monitors might trigger UAG’s DDoS protection. To stop this: (source = UAG breaks after a few days. They break 100% of the time. at VMware Discussions)

  1. Point your browser to the UAG appliance’s admin interface using https, port 9443 and path /admin.
  2. Login to the admin interface.
  3. On the right, under Configure Manually, click Select.
  4. In the Advanced Settings section, click the gear icon for System Configuration.
  5. Scroll down.
  6. Change Request Timeout to 0.
  7. Change Body Receive Timeout to 0.
  8. Click Save.

Load Balancing Servers

Create Load Balancing Server Objects for the DMZ Unified Access Gateway appliances.

  1. On the left, expand Traffic Management, expand Load Balancing, and click Servers.
  2. On the right, click Add.
  3. Enter a descriptive server name, usually it matches the actual appliance name.
  4. Enter the IP address of a Unified Access Gateway appliance.
  5. Enter comments to describe the server. Click Create.
  6. Continue adding Unified Access Gateway appliances.

Load Balancing Service Groups

Overview

Since there are six protocol/ports to UAG, there will be six service groups – one for each protocol/port:

  • TCP 443 – SSL_BRIDGE
  • UDP 443
  • UDP 4172
  • TCP 4172
  • TCP 8443 – SSL_BRIDGE
  • UDP 8443

Users will initially connect to TCP port 443, and then must be redirected to one of the other ports on the same UAG appliance that was initially used for the TCP 443 connection. If TCP 443 is up, but UDP 4172 is down on the same appliance, then you probably TCP 443 to go down too. To facilitate this, bind all three port number monitors to the TCP 443 service. If any of the bound monitors goes down, then TCP 443 is also taken down.

  • Only the TCP 443 service group needs to monitor all port numbers.
  • Other port number service groups only need to monitor that specific port number. For example, the TCP 8443 Service Group should monitor port TCP 8443.
  • Since UDP is difficult to monitor, the UDP Service Groups will monitor the equivalent TCP port. For example, the UDP 4172 Service Group will monitor TCP 4172. This isn’t the best option, but it’s better than ping.

TCP 443 Load Balancing Service Group

  1. On the left, expand Traffic Management, expand Load Balancing, and click Service Groups.
  2. On the right, click Add.
  3. Give the Service Group a descriptive name (e.g. svcgrp-Horizon-SSL).
  4. Change the Protocol to SSL_BRIDGE.
  5. Click OK to close the Basic Settings section.
  6. On the left, in the Service Group Members section, click where it says No Service Group Member.

    1. Change the selection to Server Based.
    2. In the Select Server field, click where it says Click to select.
    3. Select the Unified Access Gateway appliances you created earlier, and then at the top of the page click the blue Select button.
    4. In the Port field, enter 443, and click Create.
  7. Click OK to close the Service Group Members section.
  8. On the right, in the Advanced Settings column, click Monitors to move it to the left.
  9. On the left, at the bottom of the page, in the Monitors section, click where it says No Service Group to Monitor Binding.

    1. In the Select Monitor field, click where it says Click to select.
    2. Click the circle next to the Horizon-SSL monitor, and then at the top of the page click the blue Select button.
    3. Click Bind.
  10. For load balancing UAGs, this Service Group should monitor all port numbers so that if any of the port numbers are down then the entire server should no longer receive connections. If load balancing internal Connection Servers, then you don’t need to bind any more monitors since the PCoIP Gateway and Blast Gateway are usually disabled. To bind more monitors, on the left, click where it says 1 Service Group to Monitor Binding.

    1. Click Add Binding.
    2. In the Select Monitor field, click where it says Click to select.
    3. Click the circle next to the Horizon-PCoIP monitor, and then at the top of the page click the blue Select button.
    4. Then click Bind.
    5. Repeat these steps to bind the Horizon-Blast monitor. Unfortunately you can only bind one monitor at a time.
      • If any of these monitors goes down, then the UAG is taken offline.
    6. Click Close.
  11. To verify the monitors, on the left, higher up the page in the Service Group Members section, click the line that says # Service Group Members.

    1. Right-click one of the members, and click Monitor Details.
    2. The Last Response should indicate Success. If you bound multiple monitors to the Service, then the member will only be UP if all monitors succeed.

      • UAG has a Quiesce mode, which tells the load balancer to stop sending it connections. You can enable Quiesce mode in the UAG’s System Configuration menu.
      • Connection Servers can be disabled.
      • If Quiesce mode is enabled on the UAG, or if the Connection Server is disabled, then the member of the service group will show Going Out of Service. You can see this by right-clicking on the Server Group and clicking Manage Members.

    3. Click Close when done.
  12. Then click Done to finish creating the Service Group.

Other Ports Load Balancing Service Groups

Here are general instructions for the other Horizon UAG load balancing service groups.

  1. On the left, go to Traffic Management > Load Balancing > Service Groups.
  2. On the right, click Add.
  3. Name it svcgrp-Horizon-UDP443 or similar.
  4. Change the Protocol to UDP. Click OK to close the Basic Settings section.
  5. On the left, click where it says No Service Group Member.

    1. Change the selection to Server Based, and then click Click to select.
    2. Select your multiple Unified Access Gateway appliances, and then at the top of the page click the blue Select button.
    3. Enter 443 as the Port. Click Create.
  6. Click OK to close the Service Group Members section.
  7. On the right, in the Advanced Settings column, click Monitors to move it to the left.

    1. On the left, in the Monitors section, click where it says No Service Group to Monitor Binding.
    2. For the Select Monitor field, click where it says Click to select.
    3. Select the Horizon-SSL monitor, click Select, and then click Bind. Since we don’t have a UDP monitor, we’re binding the TCP monitor instead.
  8. Click Done to finish creating the Service Group for UDP 443.
  9. Add another Service Group for PCoIP on TCP 4172.
    1. Name = svcgrp-Horizon-PCoIPTCP or similar.
    2. Protocol = TCP
    3. Members = multiple Unified Access Gateway appliances.
    4. Port = 4172.
    5. Monitors = Horizon-PCoIP. You can add the other monitors if desired.
  10. Add another Service Group for PCoIP on UDP 4172.
    1. Name = svcgrp-Horizon-PCoIPUDP or similar.
    2. Protocol = UDP
    3. Members = multiple Unified Access Gateway appliances
    4. Port = 4172.
    5. Monitors = Horizon-PCoIP. You can add the other monitors if desired.
  11. Add another Service Group for SSL_BRIDGE 8443.
    1. Name = svcgrp-Horizon-TCP8443 or similar.
    2. Protocol = SSL_BRIDGE
    3. Members = multiple Unified Access Gateway appliances
    4. Port = 8443.
    5. Monitors = Horizon-Blast. You can add the other monitors if desired.
  12. Add another Service Group for UDP 8443 (Blast Extreme in Horizon 7).
    1. Name = svcgrp-Horizon-UDP8443 or similar.
    2. Protocol = UDP
    3. Members = multiple Unified Access Gateway appliances
    4. Port = 8443.
    5. Monitors = Horizon-Blast. You can add the other monitors if desired.
  13. The six service groups should look something like this:

Load Balancing Virtual Servers

Unified Access Gateway appliances listen on multiple ports so you will need separate load balancers for each port number. Here is a summary of their Virtual Servers, all listening on the same Virtual IP address:

  • Virtual Server on SSL_BRIDGE 443 – bind the SSL_BRIDGE 443 service group.
  • Virtual Server on UDP 443 (Horizon 7) – bind the UDP 443 service group.
  • Virtual Server on UDP 4172 – bind the PCoIP UDP service group.
  • Virtual Server on TCP 4172 – bind the PCoIP TCP service group.
  • Virtual Server on SSL_BRIDGE 8443 – bind the SSL_BRIDGE 8443 service group.
  • Virtual Server on UDP 8443 (Horizon 7) – bind the UDP 8443 service group.

Do the following to create the Virtual Servers:

  1. On the left, under Traffic Management > Load Balancing, click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section:
    1. Name it lbvip-Horizon-SSL or similar.
    2. Change the Protocol to SSL_BRIDGE.
    3. Specify a new VIP. This one VIP will be used for all of the Virtual Servers.
    4. Enter 443 as the Port.
  4. Click OK to close the Basic Settings section.
  5. On the left, in the Services and Service Groups section, click where it says No Load Balancing Virtual Server ServiceGroup Binding.

    1. Click where it says Click to select.
    2. Click the circle next to the Horizon-SSL Service Group, and then at the top of the page click the blue Select button.
    3. Click Bind.
  6. Click Continue to close the Services and Service Groups section.
  7. Then click Done to finish creating the Load Balancing Virtual Server. Persistence will be configured later.
  8. Create another Load Balancing Virtual Server for UDP 443. You can right-click the existing Load Balancing Virtual Server and click Add to copy some settings.

    1. Name = lbvip-Horizon-UDP443
    2. Same VIP as the TCP 443 Load Balancer.
    3. Protocol = UDP, Port = 443
    4. Service Group Binding = the UDP 443 Service Group

  9. Create another Load Balancing Virtual Server for PCoIP UDP 4172:
    1. Name = lbvip-Horizon-PCoIPUDP
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = UDP, Port = 4172
    4. Service Group Binding = the PCoIP UDP Service Group.

  10. Create another Load Balancing Virtual Server for PCoIP TCP 4172:
    1. Name = lbvip-Horizon-PCoIPTCP
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = TCP, Port = 4172
    4. Service Group Binding = the PCoIP TCP Service Group

  11. Create another Load Balancing Virtual Server for SSL_BRIDGE 8443:
    1. Name = lbvip-Horizon-8443SSL
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = SSL_BRIDGE, Port = 8443
    4. Service Group Binding = the TCP 8443 SSL_BRIDGE Service Group

  12. Create another Load Balancing Virtual Server for UDP 8443:
    1. Name = lbvip-Horizon-8443UDP
    2. Same VIP as the 443 Load Balancer.
    3. Protocol = UDP, Port = 8443
    4. Service Group Binding = the UDP 8443 Service Group

  13. This gives you six Load Balancing Virtual Servers on the same VIP, but different protocols and port numbers.

Persistency Group

Users will first connect to SSL_BRIDGE 443 and be load balanced. Subsequent connections to the other port numbers must go to the same load balanced appliance. Create a Persistency Group to facilitate this.

  1. On the left, under Traffic Management, expand Load Balancing, and click Persistency Groups.
  2. On the right, click Add.
  3. Give the Persistency Group a name (e.g. Horizon).
  4. Change the Persistence drop-down to SOURCEIP.
  5. Enter a Time-out that is equal to, or greater than the timeout in Horizon View Administrator, which defaults to 10 hours (600 minutes).
  6. In the Virtual Server Name section, click Add.
  7. Move all six Horizon Load Balancing Virtual Servers to the right. Click Create.

Horizon Connection Server Locked.properties File

Horizon Connection Server’s default security settings might prevent you from connecting to load balanced Connection Servers and/or Unified Access Gateways. On the Connection Servers, go to C:\Program Files\VMware\VMware View\Server\sslgateway\conf, edit or create locked.properties file, and enter the following:

allowUnexpectedHost=true
checkOrigin=false
enableCORS=false

More details at VMware 2144768 Accessing the Horizon View Administrator page displays a blank error window in Horizon and 85801 Cross-Origin Resource Sharing (CORS) with Horizon 8 and loadbalanced HTML5 access. allowUnexpectedHost defaults to false in Horizon 2306 and Horizon 2212.1 and newer. Another option is to add portalHost entries as detailed at Allow HTML Access Through a Gateway at VMware Docs.

Load Balancing CLI Commands

Internal Connection Server Load Balancing

add server VCS01 10.2.2.19
add server VCS02 10.2.2.20
add serviceGroup svcgrp-VCS-SSL SSL_BRIDGE
add lb vserver lbvip-Horizon-SSL SSL_BRIDGE 10.2.5.203 443 -persistenceType SOURCEIP -timeout 600
bind lb vserver lbvip-Horizon-SSL svcgrp-VCS-SSL
add lb monitor Horizon-SSL HTTP -respCode 200 -httpRequest "GET /favicon.ico" -destPort 443 -secure YES
bind serviceGroup svcgrp-VCS-SSL VCS01 443
bind serviceGroup svcgrp-VCS-SSL VCS02 443
bind serviceGroup svcgrp-VCS-SSL -monitorName Horizon-SSL

Unified Access Gateway load balancing with Blast and PCoIP

add server UAG01 10.2.2.187
add server UAG02 10.2.2.188
add serviceGroup svcgrp-Horizon-SSL SSL_BRIDGE
add serviceGroup svcgrp-Horizon-UDP443 UDP
add serviceGroup svcgrp-Horizon-PCoIPTCP TCP
add serviceGroup svcgrp-Horizon-PCoIPUDP UDP
add serviceGroup svcgrp-Horizon-TCP8443 SSL_BRIDGE
add serviceGroup svcgrp-Horizon-UDP8443 UDP
add lb vserver lbvip-Horizon-SSL SSL_BRIDGE 10.2.5.204 443
add lb vserver lbvip-Horizon-UDP443 UDP 10.2.5.204 443
add lb vserver lbvip-Horizon-PCoIPUDP UDP 10.2.5.204 4172
add lb vserver lbvip-Horizon-PCoIPTCP TCP 10.2.5.204 4172
add lb vserver lbvip-Horizon-8443SSL SSL_BRIDGE 10.2.5.204 8443
add lb vserver lbvip-Horizon-8443UDP UDP 10.2.5.204 8443
bind lb vserver lbvip-Horizon-SSL svcgrp-Horizon-SSL
bind lb vserver lbvip-Horizon-UDP443 svcgrp-Horizon-UDP443
bind lb vserver lbvip-Horizon-PCoIPTCP svcgrp-Horizon-PCoIPTCP
bind lb vserver lbvip-Horizon-PCoIPUDP svcgrp-Horizon-PCoIPUDP
bind lb vserver lbvip-Horizon-8443SSL svcgrp-Horizon-TCP8443
bind lb vserver lbvip-Horizon-8443UDP svcgrp-Horizon-UDP8443
add lb group Horizon -persistenceType SOURCEIP -timeout 600
bind lb group Horizon lbvip-Horizon-SSL
bind lb group Horizon lbvip-Horizon-UDP443
bind lb group Horizon lbvip-Horizon-PCoIPUDP
bind lb group Horizon lbvip-Horizon-PCoIPTCP
bind lb group Horizon lbvip-Horizon-8443SSL
bind lb group Horizon lbvip-Horizon-8443UDP
set lb group Horizon -persistenceType SOURCEIP -timeout 600
add lb monitor Horizon-SSL HTTP -respCode 200 -httpRequest "GET /favicon.ico" -destPort 443 -secure YES -trofscode 503
add lb monitor Horizon-PCoIP TCP -LRTM DISABLED -destPort 4172 -secure YES
add lb monitor Horizon-Blast TCP -LRTM DISABLED -destPort 8443 -secure YES
bind serviceGroup svcgrp-Horizon-SSL UAG01 443
bind serviceGroup svcgrp-Horizon-SSL UAG02 443
bind serviceGroup svcgrp-Horizon-SSL -monitorName Horizon-SSL
bind serviceGroup svcgrp-Horizon-SSL -monitorName Horizon-PCoIP
bind serviceGroup svcgrp-Horizon-SSL -monitorName Horizon-Blast
bind serviceGroup svcgrp-Horizon-UDP443 UAG01 443
bind serviceGroup svcgrp-Horizon-UDP443 UAG02 443
bind serviceGroup svcgrp-Horizon-UDP443 -monitorName Horizon-SSL
bind serviceGroup svcgrp-Horizon-PCoIPTCP UAG01 4172
bind serviceGroup svcgrp-Horizon-PCoIPTCP UAG02 4172
bind serviceGroup svcgrp-Horizon-PCoIPTCP -monitorName Horizon-PCoIP
bind serviceGroup svcgrp-Horizon-PCoIPUDP UAG01 4172
bind serviceGroup svcgrp-Horizon-PCoIPUDP UAG02 4172
bind serviceGroup svcgrp-Horizon-PCoIPUDP -monitorName Horizon-PCoIP
bind serviceGroup svcgrp-Horizon-TCP8443 UAG01 8443
bind serviceGroup svcgrp-Horizon-TCP8443 UAG02 8443
bind serviceGroup svcgrp-Horizon-TCP8443 -monitorName Horizon-Blast
bind serviceGroup svcgrp-Horizon-UDP8443 UAG01 8443
bind serviceGroup svcgrp-Horizon-UDP8443 UAG02 8443
bind serviceGroup svcgrp-Horizon-UDP8443 -monitorName Horizon-Blast

Global Server Load Balancing (GSLB) – Citrix ADC

Last Modified: Mar 30, 2023 @ 10:18 am

242 Comments

Navigation

💡 = Recently Updated

Change Log

GSLB Planning

GSLB is nothing more than DNS. GSLB receives a DNS query, and then GSLB sends back an IP address, which is exactly how a DNS server works. The user then connects to the returned IP, which doesn’t even need to be on a NetScaler ADC.

GSLB can do some things that DNS servers can’t do:

  • Don’t give out an IP address unless it is UP (monitoring)
    • If the active IP address is down, then give out the passive IP address (active/passive) instead
  • Give out the IP address that is closest to the user (proximity load balancing)
  • Give out different IPs for internal users vs external users (DNS View)

GSLB is only useful if you have a single DNS name that could resolve to two or more IP addresses. If there’s only one IP address, then use normal DNS instead.

Citrix Blog Post Global Server Load Balancing: Part 1 explains how DNS queries work and how GSLB fits in.

Citrix has a good DNS and GSLB Primer.

When configuring GSLB, don’t forget to ask “where is the data?”. See Citrix Blog Post XenDesktop, GSLB & DR – Everything you think you know is probably wrong!

GSLB Configuration Overview

GSLB Configuration can be split between one-time steps for GSLB infrastructure, and repeatable steps for each GSLB-enabled DNS name.

One-time GSLB Infrastructure configuration

  1. Create ADNS listener on each ADC pair – DNS clients send DNS queries to the ADNS listeners. GSLB resolves a DNS query into an IP address, and returns the IP address in the DNS response.
  2. Create GSLB Sites (aka MEP Listener) – GSLB Sites usually correspond to different datacenters. GSLB Sites are also the IP address endpoints for Citrix ADC’s proprietary Metric Exchange Protocol (MEP), which is used by GSLB to transmit proximity, persistence, and monitoring information.
  3. Import Static Proximity Database – Citrix ADC includes a database that can be used to determine the geographical location of an IP address. Or you can subscribe to a geolocation service, and import its database.
  4. Delegate DNS sub-zone to ADC ADNS – in the original DNS zone, create a new sub-zone (e.g. gslb.company.com), and delegate the sub-zone to all ADNS listeners.

Repeatable GSLB Configuration for each DNS name:

  1. Create one or more GSLB Services per DNS name, and per IP address response – each GSLB Service corresponds to a single IP address that can be returned in response to a DNS Query.
    • Optionally, bind a Monitor to each GSLB Service. Monitors determine if the GSLB Service is up or not.
  2. Create a GSLB Virtual Server per DNS name
    • Bind a DNS name to the GSLB Virtual Server.
    • For active/active – bind multiple GSLB Services to the GSLB Virtual Server, configure a load balancing method (e.g. proximity), and configure site persistence.
    • For active/passive – bind the active GSLB Service. Create another GSLB Virtual Server with passive GSLB Service and configure as Backup Virtual Server.
      • Alternatively, NetScaler ADC 13.1 and newer let you bind GSLB Services in priority order. See Citrix Docs for details.
  3. Create CNAME records for each delegated DNS name – in the main DNS zone, create a CNAME that maps the original DNS name to the delegated sub-zone. For example, CNAME citrix.company.com to citrix.gslb.company.com.

You will create separate GSLB Services, separate GSLB Virtual Servers, and separate CNAMEs for each DNS name. If you have a bunch of DNS names that you want to GSLB-enable, then you’ll repeat these steps for each GSLB-enabled DNS name.

Each datacenter has a separate ADNS listener IP address. DNS is delegated to all GSLB ADNS Listener IPs, and any one of them can respond to the DNS query. Thus, all ADC pairs participating in GSLB should have the same Per-DNS name configuration.

One ADC appliance for both public DNS/GSLB and internal DNS/GSLB?

GSLB can be enabled both publically and internally. For public GSLB, configure it on DMZ ADC appliances, and expose the DNS listener to the Internet. For internal GSLB, configure it on separate internal ADC appliances/instances, and create an internal DNS listener.

Each ADC appliance only has one DNS table, so if you try to use the same ADC for both public DNS and internal DNS, then be aware that external users can query for internal GSLB-enabled DNS names.

  • As described by Phil Bossman in the comments, you can use a Responder policy to prevent external users from reading internal DNS names. 
    add policy patset GSLB_INTERNAL
bind policy patset GSLB_INTERNAL internalHostname.gslb.domain.com -index 1
add responder action DNS_Empty_Response respondwith DNS.NEW_RESPONSE
add responder policy GSLB_DNS_Empty_Response "(!(CLIENT.IP.SRC.IN_SUBNET(10.0.0.0/8)||CLIENT.IP.SRC.IN_SUBNET(192.0.0.0/16)||CLIENT.IP.SRC.IN_SUBNET(172.0.0.0/12)) && DNS.REQ.QUESTION.DOMAIN.CONTAINS_ANY(\"GSLB_INTERNAL\"))" DNS_Empty_Response
bind responder global GSLB_DNS_Empty_Response 100 END -type DNS_REQ_DEFAULT

One appliance resolving a single DNS name differently for internal and public

Let’s say you have a single DNS name citrix.company.com. When somebody external resolves the name, it should resolve to a public IP. When somebody internal resolves the name, it should resolve to an internal IP.

For internal GSLB and external GSLB of the same DNS name on the same ADC appliance, you can use DNS Policies and DNS Views to return different IP addresses depending on where users are connecting from. See Citrix CTX130163 How to Configure a GSLB Setup for Internal and External Users Using the Same Host Name.

If the Internet circuit in the remote datacenter goes down, then this should affect public DNS, since you don’t want to give out a public IP that isn’t reachable. But do you also want an Internet outage to affect internal DNS? Probably not. In that case, you would need different GSLB monitoring configurations for internal DNS and external DNS. However, if you have only a single GSLB Virtual Server with DNS Views, then you can’t configure different monitoring configurations for each DNS View.

To work around this limitation, create two separate GSLB Virtual Servers with different monitoring configurations. Internal DNS uses a CNAME record to reach the GSLB Virtual Server configured for internal monitoring:

  • External citrix.company.com:
    • Configure ADC GSLB for citrix.company.com.
    • On public DNS, delegate citrix.company.com to the ADC DMZ ADNS services.
  • Internal citrix.company.com:
    • Configure ADC GSLB for citrixinternal.company.com or something like that.
    • On internal DNS, create CNAME for citrix.company.com to citrixinternal.company.com
    • On internal DNS, delegate citrixinternal.company.com to ADC internal ADNS services.

Remote Internet Monitoring

For public DNS/GSLB, you don’t want to give out a remote public IP address if that remote public IP address is not reachable. That means the local ADC will need to somehow determine if the remote datacenter has Internet connectivity or not. Here are some methods of verifying the remote Internet connection:

  • Route GSLB Metric Exchange Protocol (MEP) across the Internet. If MEP goes down, then all IP addresses associated with the remote GSLB Site are assumed to be down, and thus the local ADC will stop giving out those remote IP addresses.
  • Bind explicit monitors to each GSLB Service, and ensure the monitoring is routed across the Internet.

GSLB IP Addresses

GSLB is separate from data traffic. The GSLB IP addresses are separate from the IP addresses needed for data.

Some GSLB-specific IP Addresses are needed on each ADC pair:

  • ADNS Listener IP: An ADC IP that listens for DNS queries.
    • The ADNS listener IP is typically an existing SNIP on the appliance.
    • For external DNS, create a public IP for the ADNS Listener IP, and open UDP 53 and TCP 53, so Internet-based DNS servers can access it.
    • A single ADC appliance can have multiple ADNS listeners – typically one ADNS listener for public, and another ADNS listener for internal.
  • GSLB Site IP / MEP listener IP: An ADC IP that will be used for ADC-to-ADC GSLB communication. This communication is called MEP or Metric Exchange Protocol. MEP transmits the following between GSLB-enabled ADC pairs: load balancing metrics, proximity, persistence, and monitoring.
    • GSLB Sites – On ADC, you create GSLB Sites. GSLB Sites are the endpoints for the MEP communication. Each ADC pair is configured with the MEP endpoints for the local appliance pair, and all remote appliance pairs.
    • TCP Ports – MEP uses port TCP 3009 or TCP 3011 between the ADC pairs. TCP 3009 is encrypted.
    • The ADNS IP address can be used as the MEP endpoint IP.
    • MEP endpoint can be any IP – The MEP endpoint IP address can be any IP address and does not need to be a SNIP or ADNS.
    • One MEP IP per appliance – there can only be one MEP endpoint IP address on each ADC pair.
    • Route MEP across Internet? – If you route MEP across the Internet, and if the MEP connection is interrupted, then Internet at one of the locations is probably not working. This is an easy way to determine if remote Internet is up or not. If you don’t route MEP across the Internet, then you’ll need to configure every remote-site GSLB Service with a monitor to ensure that the remote Internet is up.
      • Public IPs for MEP Enpoints – if you route MEP across the Internet, then you’ll need public IPs for each publically-accessible MEP endpoint IP address.
      • Public Port for MEP: Open port TCP 3009 between the MEP Public IPs. Make sure only the MEP IPs can access this port on the other ADC . Do not allow any other device on the Internet to access this port. Port 3009 is encrypted.
    • GSLB Sync Ports: To use GSLB Configuration Sync, open ports TCP 22 and TCP 3008 (secure) from the NSIP (management IP) to the remote public MEP IP. The GSLB Sync command runs a script in BSD shell and thus NSIP is always the Source IP.
  • Public IP Summary: In summary, for public GSLB, if MEP and ADNS are listening on the same IP, then you need one new public IP that is NAT’d to the DMZ IP that is used for ADNS and MEP (GSLB Site IP).
    • Each datacenter has a separate public IP.
    • DNS is delegated to all public ADNS IP listeners.

GSLB Wizard

NetScaler 12 and Citrix ADC 12.1 and newer have a GSLB Wizard at Traffic Management > GSLB.

However, the wizard doesn’t really save any time or steps, so it won’t be documented here.

ADNS Listener

  1. At System > Network > IPs, identify a Citrix ADC-owned IP that you will use as the ADNS listener. This is typically a SNIP.
  2. Create a public IP for the ADNS Service IP and configure firewall rules. UDP 53 and TCP 53 need to be opened from the Internet to the public IP that NATs to the ADNS Listener IP address.
  3. On the left, expand Traffic Management > Load Balancing, and click Services.
  4. On the right, click Add.

    1. In the Basic Settings section, do the following:
      1. Name the service ADNS or similar.
      2. In the IP Address field, enter an appliance SNIP.
      3. In the Protocol drop-down, select ADNS.
    2. Click OK.
    3. No other configuration is needed so scroll down and click Done to close the Load Balancing Service properties.
  5. Highlight the ADNS service you just added and then click Add to create another Service while copying some of the settings from the previously created Service.

    1. Change the Service Name to ADNS_TCP or similar.
    2. Change the Protocol drop-down to ADNS_TCP.
    3. Click OK to close the Basic Settings section.
    4. No other configuration is needed so scroll down and click Done to close the Load Balancing Service properties.
  6. You should have two ADNS services on the same IP address: one for ADNS, and one for ADNS_TCP.
  7. On the left of the console in the menu, expand System, expand Network, and then click IPs.
  8. On the right, you’ll see the SNIP is now marked as the ADNS svc IP.
  9. Repeat the ADNS configuration on the other appliance pair in the other datacenter. Except the other appliance will use its own SNIP as the ADNS Service listener IP address.
  10. Your ADC appliances are now DNS servers.

DNS Security

  1. Citrix ADC includes DNS Security Options, at Security > DNS Security, which can protect your ADNS service.
  2. To protect ADNS, set the Profile to All DNS Endpoints.

Metric Exchange Protocol

This section details MEP configuration between two GSLB Sites. See Citrix Docs for larger Parent-Child Topology Deployment Using the MEP Protocol.

GSLB Sites

  1. The local GSLB Site IP can be any IP, including the same SNIP that you used for ADNS.
  2. Open the firewall rules for Metric Exchange Protocol. The GSLB Site IP on this appliance pair uses TCP 3009 to communicate with the GSLB Site IP on the other appliance pair.
  3. On the left, expand Traffic Management, right-click GSLB, and enable the feature.
  4. Expand GSLB, and click Sites.
  5. On the right, click Add.
  6. In the Create GSLB Site page, do the following:
    1. We’re adding the local site first. Enter a descriptive name for the local site.
    2. In the Site Type drop-down, select LOCAL.
    3. In the Site IP Address field, enter an IP that this appliance will listen for MEP traffic. This is typically a SNIP and can the same as your ADNS IP.
    4. For Internet-routed GSLB MEP, in the Public IP Address field, enter the public IP that is NAT’d to the GSLB Site IP.
    5. For internal GSLB MEP, there is no need to enter anything in the Public IP field.
  7. Scroll down, and click Create, to close the Create GSLB Site page.

  8. Go back to System > Network > IPs, and notice that the IP is now marked as a GSLB site IP.
  9. If you want to use the GSLB Sync Config feature, then you’ll need to edit the GSLB site IP, and enable Management Access.

    1. Scroll down, and enable Management Access. SSH is all you need.
  10. Go to the other appliance pair, and also create the Local GSLB site using its GSLB site IP, and its public IP that is NAT’d to the GSLB site IP.

    1. In System > Network > IPs on the remote appliance, there should now be a GSLB site IP. If GSLB Sync is desired, enable management access on that IP and ensure SSH is enabled.
  11. Now on each appliance, add another GSLB Site, which will be the Remote GSLB site.
  12. In the Create GSLB Site page, do the following:
    1. Enter a descriptive name for the remote site.
    2. Select REMOTE as the Type.
    3. Enter the other appliance’s actual GSLB Site IP as configured on the appliance. This IP does not need to be reachable.
    4. In the Public IP Address field, enter the public IP that is NAT’d to the GSLB Site IP on the other appliance. For MEP, TCP 3009 must be open from the local GSLB Site IP, to the remote public Site IP. For GSLB sync, TCP 22, and TCP 3008, must be open from the local NSIP, to the remote public Site IP.
  13. Click Create.
  14. Repeat on the other appliance.

RPC

MEP defaults to unencrypted on TCP 3011. To fix that:

  1. On the left, expand System, expand Network, and click RPC.
  2. On the right, right-click the new RPC address (the other site’s GSLB Site IP), and click Edit.
  3. On the bottom, check the box next to Secure. In ADC 13.0 64.x and 12.1 build 61.x onwards, Secure is enabled by default. (source = Citrix CTX292743 Configuration Sync, Propagation and MEP Propagation Might Fail After Upgrade to 13.0 64.x\12.1 61.x)

    • If your local GSLB Site IP is not a SNIP, then you’ll need to change the RPC Node to use the local GSLB Site IP as the source IP. In the Source IP Address field, enter the local GSLB Site IP.
  4. Click OK when done.
  5. Do the same thing on the other appliance.
  6. If you go back to GSLB > Sites, you should see it as active.

See Citrix Tech Zone Troubleshooting Citrix GSLB MEP Cheat Sheet

If your MEP connection between GSLB Sites flaps, it might be useful to introduce a delay before remote GSLB Services are marked as Down.

  1. You can do this at Traffic Management > GSLB > Dashboard.
  2. On the right, click Change GSLB settings.
  3. In the GSLB Service State Delay Time (secs) field, enter a delay before the GSLB Services are marked as down when MEP goes down.

    set gslb parameter -GSLBSvcStateDelayTime 15

Static Proximity Geo Location Database

If you want to use DNS Policies, or Static Proximity GSLB Load Balancing, or Responders based on user’s location, import a geo location database.

Citrix ADC has a built-in database at /var/netscaler/inbuilt_db/ that you can use. Or you can download a database. Common free databases are:

For IP2Location, see the blog post Add IP2Location Database as NetScaler’s Location File for instructions on how to import.

CTX235799 NetScaler data formats for Location Database Import

Citrix Github has a Citrix-ADC-GSLB-GeoIP-Conversion-Tool that can convert Maxmind GeoIP City database to Citrix ADC (NetScaler) format.

Import the Built-in Geo database:

  1. In the Citrix ADC GUI, on the left, expand Traffic Management, expand GSLB, expand Database and Entries, and click Static Databases.
  2. On the right, click Add.
  3. Change the Import From selection to File.
  4. Click Choose File.
  5. Browse to /var/netscaler/inbuilt_db/. To browse to the directory, select var, and then click Open.
  6. Repeat for each directory until you reach /var/netscaler/inbuilt_db.
  7. In ADC 12.1, you can select the file named Citrix_Netscaler_InBuild_GeoIP_DB_IPv4. In NetScaler 12.0, select the only file shown. Then click Open.
  8. In the Location Format field, if using the built-in database, select netscaler, and click Create.
  9. After you later create a GSLB Service, when you open the GSLB Service, the public IP will be translated to a location based on the contents of the static proximity database.

Private IP Blocks

Geo Location databases only contain entries for Public IPs. For Private IPs, do the following:

  1. On the left, expand Traffic Management, expand GSLB, expand Database and Entries, and click Custom Entries.
  2. On the right, click Add.
  3. Enter a range of IP addresses for a particular location.
  4. Enter a Location Name in Geo Location format, which is typically six location words separated by periods. You can look in the static proximity database for examples.
  5. Make sure you enter coordinates. Google can find you coordinates for cities.
  6. Click Create.
  7. Continue creating Custom Entries for other private IP blocks.

Use Geo Locations

You can use the Geo locations in a DNS Policy, static proximity GSLB Load Balancing, Responders, and Rewrites:

Prior to Citrix ADC 12.1 build 50, the only option in policy expressions is to match a known location.

Citrix ADC 12.1 build 50 and newer lets you extract the user’s location and use it in policy expressions.

GSLB Services

GSLB Services represent the IP addresses that are returned in DNS Responses. The IP addresses represented by GSLB Services do not need to be hosted on a Citrix ADC, but Citrix ADC-owned IP addresses (e.g. load balancing VIPs) have additional GSLB Site Persistence options (e.g. cookie-based persistence).

  • Each potential IP address in a DNS response is a separate GSLB Service.
  • GSLB Services are associated with GSLB Sites.
  • GSLB Service configuration is identical for active/active and active/passive. GSLB Virtual Server configuration defines active/active or active/passive, not GSLB Services.

GSLB should be configured identically on all Citrix ADC pairs that are responding to DNS queries. Since you have no control over which Citrix ADC will receive the DNS query, you must ensure that both Citrix ADC pairs are giving out the same DNS responses.

To create a GSLB Service:

  1. On the left, expand Traffic Management > GSLB, and click Services.
  2. On the right, click Add.
  3. The service name should be similar to the DNS name that you are trying to GSLB. Include the site name in the service name.
  4. Select one of the GSLB Sites. The IP address you’re configuring in this GSLB Service should be geographically located in the selected GSLB Site.
  5. On the bottom part, if the IP address is owned by this Citrix ADC, then select Virtual Servers, and select a Virtual Server that is already defined on this appliance. It should automatically fill in the other fields. This option is only available when creating a GSLB Service in the Local GSLB Site.

    1. If the IP address is not owned by this Citrix ADC, then change the selection to New Server, and enter the remote IP address in the Server IP field.
    2. The Server IP field is the IP address that Citrix ADC will monitor for reachability.
    3. If the remote IP is owned by a different Citrix ADC that is reachable by MEP, then enter the actual VIP configured on that remote Citrix ADC. The Server IP does not need to match what is returned to the DNS Query.
  6. In the Public IP field, enter the IP address that will be returned to the DNS Query. If you leave Public IP blank, then Citrix ADC will copy the Server IP to the Public IP field. For Public GSLB, the Public IP field is usually a Public IP address. For internal GSLB, the Public IP field is usually an internal IP, and probably matches the Server IP.
  7. Scroll up, and make sure the Service Type is SSL. It’s annoying that Citrix ADC doesn’t set this drop-down correctly.
  8. Scroll down, and click OK, to close the Basic Settings section.
  9. GSLB Service Monitoring – on the right, in the Advanced Settings column, you can click Monitors to bind a monitor to this GSLB Service. Review the following notes before you bind a monitor.

    • Local Citrix ADC VIP – If the GSLB Service IP is a VIP on the local appliance, then GSLB will simply use the state of the local traffic Virtual Server (Load Balancing, Content Switching, or Gateway). There’s no need to bind a monitor to the GSLB Service.
    • Remote Citrix ADC VIP – If the GSLB Service IP is a VIP on a remote appliance, then GSLB will use MEP to ask the other appliance for the state of the remote traffic Virtual Server. In both cases. There’s no need to bind a monitor to the GSLB Service.
    • GSLB Monitor overrides other Monitoring methods – If you bind a monitor to the GSLB Service, then MEP and local Virtual Server state are ignored (overridden).
    • Here are some reasons for binding a monitor to the GSLB Service:
      • IP is not on a Citrix ADC– If the GSLB Service IP is not hosted on a Citrix ADC, then only a monitor can determine if the Service IP is up or not.
      • Monitor remote Internet – For Public DNS, if MEP is not routed through the Internet, then you need some method of determining if the remote Internet circuit is up or not. In that case, you’ll need to bind monitors directly to the GSLB Service. The route of the Monitor should go across the Internet. Or you can ping the Internet router in the remote datacenter to make sure it’s reachable.
      • Traffic Domains – If the GSLB Service IP is in a non-default Traffic Domain, then you will need to attach a monitor, since GSLB cannot determine the state of Virtual Servers in non-default Traffic Domains.
      • TCP monitor – for TCP services (not UDP), a simple TCP monitor is probably all you need. The TCP monitor tries to connect to the GSLB Service Public IP address using the SNIP of the local appliance. Make sure firewall on both sides allows this connection.
  10. Active/Active Site Persistence – If you intend to do GSLB active/active, and if you need site persistence, then on the right you can add Site Persistence and enable Connection Proxy or HTTP Redirect. See Citrix Blog Post Troubleshooting GSLB Persistence with Fiddler for more details. This only works with GSLB Service IPs that match Virtual Server VIPs on Citrix ADC appliances reachable through MEP.

  11. Scroll down, and click Done, to finish creating the GSLB Service.
  12. Create additional GSLB Services for each IP address that will be returned to a DNS query. There should be at least two for each DNS name.
  13. When creating a GSLB Service, select the correct Site, and make sure Service Type = SSL.
  14. The State will probably be down until the other ADC is configured.

Manually Synchronize GSLB Configuration

Copy the GSLB Service Configuration to the remote Citrix ADC pair. You can either repeat the GUI steps listed above. Or you can do the following:

  1. On the left, expand Traffic Management, expand GSLB, and click Dashboard.
  2. On the right, click View GSLB Configuration.
  3. This shows you all of the CLI commands for GSLB. Look for add gslb service commands. You can copy them, and run them (SSH) on other Citrix ADC pairs that are participating in GSLB.

GSLB Virtual Server

GSLB Virtual Server is the entity that links a DNS name with GSLB Services.

For Active/Passive GSLB in NetScaler ADC 13.1 or newer, GSLB Services can be bound in priority order. GSLB will give out the IP address of the lowest order GSLB Service. If that GSLB Service is down, then GSLB will give out the IP address of the next order GSLB Service.

  1. Create a GSLB Virtual Server.
  2. Bind the active GSLB Service but set the Order to 1.
  3. Bind the passive GSLB Service but set the Order to 2.
  4. Bind a DNS name to the GSLB Virtual Server.
  5. Repeat the GSLB Virtual Server configuration on other Citrix ADC pairs participating in GSLB.
  6. Delegate the DNS name to Citrix ADC ADNS.

For Active/Passive GSLB, the Active GSLB Virtual Server will give out a single IP address if that IP address up. If the GSLB Service is down, then it will fail over to a Backup GSLB Virtual Server that gives out a different IP address.

  1. Create a GSLB Virtual Server for the Passive IP address.
    1. Bind the Passive GSLB Service to the Passive GSLB Virtual Server.
  2. Create another GSLB Virtual Server for the Active IP address.
    1. Bind the Active GSLB Service to the Active GSLB Virtual Server.
    2. Configure Backup Virtual Server pointing to the Passive GSLB Virtual Server.
    3. Bind a DNS name to the Active GSLB Virtual Server.
  3. Repeat the GSLB Virtual Server configuration on other Citrix ADC pairs participating in GSLB.
  4. Delegate the DNS name to Citrix ADC ADNS.

For Active/Active GSLB, a single GSLB Virtual Server gives out multiple IP addresses based on load balancing method and site persistence.

  1. Create one GSLB Virtual Server.
    1. Bind two or more GSLB Services to the Virtual Server.
    2. Configure the GSLB Virtual Server Load Balancing Method – e.g., Proximity
    3. Configure Site Persistence:
      1. Source IP persistence is configured on the GSLB Virtual Server.
      2. Cookie Persistence is configured on the GSLB Services.
    4. Bind a DNS name to the GSLB Virtual Server.
  2. Repeat the GSLB Virtual Server configuration on other Citrix ADC pairs participating in GSLB.
  3. Delegate the DNS name to Citrix ADC ADNS.

Configure Active/Passive GSLB in NetScaler ADC 13.1 and newer

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Sevices you intend to bind.

      add gslb vserver <gslb_vserver_name> SSL
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the box next to the active GSLB Service and click Select.
    3. In the Order box, enter 1. Click Bind.
  6. To add another GSLB Service Binding, on the left, click where it says 1 GSLB Virtual Server to GSLB Service Binding.

    1. Click Add Binding.
    2. Click where it says Click to select.
    3. Check the box next to a passive GSLB Service and then click Select at the top of the page.
    4. In the Order box, enter 2 so that this GSLB Service is only used if all Order 1 GSLB Services are down. Click Bind.
  7. Click OK to close the GSLB Services and GSLB Service Group Binding section.
  8. On the left, click where it says No GSLB Virtual Server Domain Binding.

    1. Enter the FQDN that this GSLB Virtual Server will resolve.
    2. Click Bind.
    3. If you are doing CNAME (e.g., citrix.corp.com CNAME to citrix.gslb.corp.com, then add domain bindings for both the main FQDN and the CNAME FQDN. Click Close when done.
  9. Click OK to close the GSLB Virtual Server Domain Binding section.
  10. Click OK to close the ADNS Service section.
  11. With GSLB Services assigned to different Order numbers, it is not necessary to configure Backup Virtual Server.
  12. If you bound multiple GSLB Services to a single Order number, then you might want to adjust Method and Persistence.
  13. Click Done to finish creating the GSLB Virtual Server.
  14. On the left, if you expand Traffic Management > DNS, expand Records, and click Address Records…
  15. You’ll see a new DNS record for the GSLB domain you just configured. Notice it is marked as GSLB DOMAIN, and has a default TTL of 5 seconds. You can also see which GSLB Virtual Server it is bound to.
  16. Configure an identical GSLB Virtual Server on the other NetScaler ADC appliance pair. Both NetScaler ADC pairs must be configured identically. You can use Traffic Management > GSLB > Dashboard > View GSLB Configuration to copy the add/set/bind gslb vserver commands from this appliance to other NetScaler ADC appliances.


Configure Active/Passive GSLB in NetScaler ADC 13.0 and older

Passive Virtual Server

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the Passive GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Services that you will bind to this Virtual Server.
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the box next to an existing Passive GSLB Service, and then click the blue Select button at the top of the screen.
    3. Click Bind.
  6. Click OK to close the GSLB Virtual Server GSLB Service Binding section.
  7. Click OK to close the GSLB Virtual Server Domain Binding section. The DNS name is bound to the Active Virtual Server, not the Passive Virtual Sever.
  8. Click OK to close the ADNS Service section.
  9. Click Done to finish creating the Passive GSLB Virtual Server.

Active Virtual Server

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the Active GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Services that you will bind to this Virtual Server.
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the box next to an existing Active GSLB Service, and click Select.
    3. Click Bind.
  6. Click OK to close the GSLB Virtual Server GSLB Service Binding section.
  7. On the left, click where it says No GSLB Virtual Server Domain Binding.
  8. In the Domain Binding page, do the following:
    1. Enter the FQDN that GSLB will resolve.
    2. Click Bind.
  9. Click OK to close the GSLB Virtual Server Domain Binding section.
  10. Click OK to close the ADNS Service section.
  11. On the right, in the Advanced Settings section, click Backup Virtual Server to add it to the left.
  12. On the left, in the Backup Virtual Server section, select the Passive GSLB Virtual Server, and click OK.
  13. Click Done when done creating the Active GSLB Virtual Server.
  14. On the left, if you expand Traffic Management > DNS, expand Records, and click Address Records…
  15. On the right, you’ll see a new DNS record for the GSLB domain you just configured. Notice the Type is GSLB DOMAIN, and has a default TTL of 5 seconds. You can also see which GSLB Virtual Server it is bound to.
  16. Configure identical GSLB Virtual Servers on the other Citrix ADC appliance pair. Both Citrix ADC pairs must be configured identically. You can use Traffic Management > GSLB > Dashboard > View GSLB Configuration to copy the add/set/bind gslb vserver commands from this appliance to other Citrix ADC appliances.

Configure Active/Active GSLB

  1. On the left, expand Traffic Management, expand GSLB, and click Virtual Servers.
  2. On the right, click Add.
  3. In the Basic Settings section, do the following:
    1. Give the GSLB Virtual Server a descriptive name.
    2. Set the Service Type to SSL to match the GSLB Sevices you intend to bind.
    3. You can optionally check the box for Send all “active” service IPs in response (MIR). By default, GSLB only gives out one IP address per DNS query. This checkbox always returns all IPs, but the IPs are ordered based on the GSLB Load Balancing Method and/or GSLB Persistence.
    4. A new DNS feature called ECS will contain the actual DNS client IP. This dramatically improves the accuracy of determining a user’s location. Without this setting, GSLB can only see the IP address of the user’s configured DNS server instead of the real client IP. Check the box next to Respond with ECS option to enable ECS for site persistence.

      set gslb vserver <gslb_vserver> -ECS ENABLED
  4. Click OK to close the Basic Settings section.
  5. On the left, click where it says No GSLB Virtual Server to GSLB Service Binding.

    1. Click where it says Click to select.
    2. Check the boxes next to multiple existing GSLB Services, and click Select.
    3. Click Bind.
  6. Click OK to close the GSLB Virtual Server GSLB Service Binding section.
  7. On the left, click where it says No GSLB Virtual Server Domain Binding.

    1. Enter the FQDN that this GSLB Virtual Server will resolve.
    2. Click Bind.
  8. Click OK to close the GSLB Virtual Server Domain Binding section.
  9. Click OK to close the ADNS Service section.
  10. On the left, in the Method section, click the pencil icon.

    1. For poximity load balancing, change the Choose Method drop-down to RTT with STATICPROXIMITY as backup.
      1. RTT = Round Trip Time. Each ADC appliance sends a ping to the user’s DNS server. Whichever ADC appliance gets the fastest response determines the site of the GSLB Service. RTT requires that ADC be able to ping anything on the Internet so adjust firewall rules accordingly.
      2. STATICPROXIMITY requires that the Geo Location database has already been installed on the appliance.
    2. Click OK to close the Method section.
  11. On the right, in the Advanced Settings column, click Persistence to add it to the left.

    1. On the left, at the bottom of the page in the Persistence section, change the Persistence drop-down to Source IP.
    2. Enter a Persistence Id.
      1. The Persistence ID signifies the persistence table that each ADC pair shares across the MEP connection.
      2. Each active/active GSLB Virtual Server should have a different Persistence ID (different persistence table).
      3. When you configure the same GSLB Virtual Server on each Citrix ADC pair, specify the same Persistence ID so every Citrix ADC has the same persistence information for this particular GSLB Virtual Server.
    3. In the Time-out field, enter the Persistence Time-out. This is typically the same or longer than the webpage timeout.
    4. Click OK to close the Persistence section.
  12. Click Done to finish creating the GSLB Virtual Server.
  13. On the left, if you expand Traffic Management > DNS, expand Records, and click Address Records…
  14. You’ll see a new DNS record for the GSLB domain you just configured. Notice it is marked as GSLB DOMAIN, and has a default TTL of 5 seconds. You can also see which GSLB Virtual Server it is bound to.
  15. Configure an identical GSLB Virtual Server on the other Citrix ADC appliance pair. Both Citrix ADC pairs must be configured identically. You can use Traffic Management > GSLB > Dashboard > View GSLB Configuration to copy the add/set/bind gslb vserver commands from this appliance to other Citrix ADC appliances.


GSLB Configuration Synchronization Script

Manual GSLB Synchronization

  1. The synchronization script requires SSH to be enabled on your GSLB Site IPs.

  2. Ports TCP 3008, TCP 3010, and TCP 22 must be opened from the local NSIP to the remote GSLB Site IP. The source IP is NSIP, not SNIP.
  3. To manually run the script that syncs GSLB configuration from one GSLB Site to another, on the left, expand Traffic Management, expand GSLB, and click Dashboard.
  4. On the right, click the button labelled Auto Synchronization GSLB.
  5. Use the check boxes on the top, if desired. It’s usually a good idea to Preview the changes before applying them.
  6. Then click Run to begin synchronization.
  7. Click Close.
  8. You can Run it again without previewing it. It seems to take several seconds to complete.

Automatic GSLB Synchronization

  1. There is an automatic GSLB Configuration Sync feature, which automatically syncs the GSLB config every 15 seconds. To enable it on the master appliance, go to Traffic Management > GSLB > Dashboard. On the right, click Change GSLB settings.
  2. Check the box next to Automatic Config Sync. Only enable this on the one appliance where you are configuring GSLB, and want that GSLB config synced to other appliance.
  3. The automatic sync log can be found at /var/netscaler/gslb/periodic_sync.log.

Some notes regarding GSLB Sync:

  • When syncing GSLB Services, it tries to create Load Balancing Server objects on the remote appliance. If the GSLB Service IP matches an existing Load Balancing Server object, then the GSLB sync will fail. Check the Sync logs for details. You’ll have to delete the conflicting Load Balancing Server object before GSLB Sync works correctly.
  • GSLB Sync runs as a script on the BSD shell and thus always uses the NSIP as the source IP.
  • GSLB Sync connects to the remote GSLB Site IP on TCP 3008 (if RPC is Secure) and TCP 22.

Test GSLB

  1. You can test GSLB DNS name resolution from the GUI by going to Traffic Management > GSLB > Dashboard, and on the right, click the button labelled Test GSLB.

  2. Select a GSLB Domain Name.
  3. Select an ADNS Service IP to test it from, and click Test.
  4. The test performs a dig against the ADNS IP. Verify that the response contains the IP address you expected.
  5. Another method of testing GSLB is to simply point nslookup to the ADNS services and submit a DNS query for one of the DNS names bound to a GSLB vServer. Run the query multiple times to make sure you’re getting the response you expect.
    • The syntax is “nslookup <DNS_name> <ADNS_IP>”. The second argument specifies the DNS server that you send the DNS Query to.
  6. The Citrix ADC ADNS services at both GSLB sites should be giving the same response.
  7. To simulate a failure, if the GSLB Service IP is a Citrix ADC Load Balancing, Content Switching, or Citrix Gateway IP, you can disable the Virtual Server.
  8. Then the responses should change. Verify on both ADNS services.
  9. Re-enable the Virtual Server, and the responses should return to normal.

DNS Delegation

If you are enabling GSLB for the domain gateway.corp.com, you’ll need to create a delegation at the server that is hosting the corp.com DNS zone. For public GSLB, you need to edit the public DNS zone for corp.com.

DNS Delegation instructions will vary depending on what product is hosting the public DNS zone. This section details Microsoft DNS, but it should be similar in BIND or web-based DNS products.

There are two ways to delegate GSLB-enabled DNS names to Citrix ADC ADNS:

  • Delegate the individual record –  For example, delegate gateway.corp.com.
  • Delegate an entire subzone – For example, delegate the subzone gslb.corp.com. Then create a CNAME record in the parent DNS zone for gateway.corp.com that is aliased to gateway.gslb.corp.com. For additional delegations, simply create more CNAME records.
    • The incoming DNS query to the ADNS listener is for gateway.gslb.corp.com and not gateway.corp.com. You’ll need to bind gateway.gslb.corp.com to your GSLB Virtual Server. You can bind multiple FQDNs to a single GSLB Virtual Server.

A delegation consists of the following DNS records:

  • A records (host records) that resolve to each Citrix ADC ADNS IP address. If you have two ADC pairs participating in GSLB, then you’ll need one A record for each ADC pair.
    • The A record names are typically something like ns1.corp.com and ns2.corp.com, just like you would name any other DNS server.
    • You only create the A records once. The A records for ADNS services can be used by multiple delegations.
    • These A records for ADNS are sometimes called glue records.
  • NS records for each delegation. The NS records point to the A records that resolve to the ADC ADNS IP addresses. If you have two ADC ADNS IP addresses, then you need two NS records for each delegation.
    • When delegating individual records, you create separate NS records for each delegation. If you have two ADNS listeners, then you need two NS records for each delegation.
    • When delegating a subzone, you only need NS records for the subzone. To GSLB-enable a DNS name, you create a CNAME that aliases to a record under the subzone.

Delegate an individual DNS record

  1. Run DNS Manager.
  2. First, create Host Records pointing to the ADNS services running on the Citrix ADC pairs in each data center. These host records for ADNS are used for all GSLB delegations no matter how many GSLB delegations you need to create. These are sometimes called glue records.
  3. The first Host record is gslb1, (or similar) and should point to the ADNS service (Public IP) on one of the Citrix ADC appliances.
  4. The second Host record is gslb2, and should point to the ADNS Service (public IP) on the other Citrix ADC appliance.
  5. If you currently have a host record for the service that you are delegating to GSLB (e.g. gateway.corp.com), delete it.
  6. Right-click the parent DNS zone, and click New Delegation.
  7. In the Welcome to the New Delegation Wizard page, click Next.
  8. In the Delegated Domain Name page, enter the left part of the DNS record that you are delegating (e.g. gateway for gateway.corp.com). Click Next.
  9. In the Name Servers page, click Add.
  10. This is where you specify gslb1.corp.com and gslb2.corp.com as delegated name servers. Enter gslb1.corp.com, and click Resolve. Then click OK. If you see a message about the server not being authoritative for the zone, ignore the message. Note: you only add one name server at a time.
  11. Then click Add to add the other GSLB ADNS server.
  12. Once both ADNS servers are added to the list, click Next.
  13. In the Completing the New Delegation Wizard page, click Finish.
  14. The delegation is shown in the DNS Manager console.
  15. For proper delegation, the Name Server records should also be added to Citrix ADC. (source = Citrix CTX241493 Citrix Response on DNS Flag Day)
    1. On the GSLB Citrix ADC appliances, expand Traffic Management, expand DNS, expand Records, and click Name Server Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the name of the delegated DNS name (e.g. gateway.corp.com).
    4. In the Name Server field, leave it set to –<< New >>–, and enter one of the FQDNs for your GSLB ADNS services. This is one of the glue records you created earlier.
    5. Click Create.
    6. Add another Name Server Record for the same domain name. But this time, enter the second GSLB ADNS FQDN. Repeat this process until all GSLB ADNS FQDNs are specified.

  16. Also add an SOA record for the delegation. If you are delegating individual records, then you will need an SOA for each record. If you are delegating a subzone, you only need an SOA record for the subzone.
    1. On the left, in the menu, go to Traffic Management > DNS > Records > SOA Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the FQDN that you delegated to NetScaler. This can be an individual record, or a sub-zone.
    4. In the Origin Server field, leave it set to –<< New >> — and then enter the FQDN that resolves to one of your ADNS listeners. It doesn’t matter which one you enter.
    5. In the Contact field, enter an email address that is publicly viewable. Replace the @ symbol with a period.
    6. Click Create.
    7. Repeat this on the other ADCs that are participating in GSLB for this delegated DNS name.
  17. If you run nslookup against your Microsoft DNS server, it will respond with Non-authoritative answer. That’s because it got the response from Citrix ADC, and not from the original DNS server that you send the request to.

Delegate a Sub-zone

  1. Run DNS Manager.
  2. First, create Host Records pointing to the ADNS services running on the Citrix ADC pairs in each data center. These are sometimes called glue records.

    1. The first Host record is gslb1 (or similar), and should point to the ADNS service (Public IP) on one of the Citrix ADC appliances.
    2. The second Host record is gslb2, and should point to the ADNS Service (public IP) on the other Citrix ADC appliance.
  3. Right-click the parent DNS zone, and click New Delegation.
  4. In the Welcome to the New Delegation Wizard page, click Next.
  5. In the Delegated Domain Name page, enter the left part of the DNS sub-zone that you are delegating (e.g. gslb for gslb.corp.com). Click Next.
  6. In the Name Servers page, click Add.
  7. This is where you specify gslb1.corp.com and gslb2.corp.com. Enter gslb1.corp.com, and click Resolve. Then click OK. If you see a message about the server not being authoritative for the zone, ignore the message. Note: you only add one name server at a time.
  8. Then click Add to add the other GSLB ADNS server.
  9. Once both ADNS servers are added to the list, click Next.
  10. In the Completing the New Delegation Wizard page, click Finish.
  11. The sub-zone delegation is shown in the DNS Manager console.
  12. For proper delegation, the Name Server records should also be added to Citrix ADC. (source = Citrix CTX241493 Citrix Response on DNS Flag Day)
    1. On the GSLB Citrix ADC appliances, expand Traffic Management, expand DNS, expand Records, and click Name Server Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the name of the delegated sub-domain (e.g. gslb.corp.com).
    4. In the Name Server field, leave it set to –<< New >>–, and enter one of the FQDNs for your GSLB ADNS services. This is one of the glue records you created earlier.
    5. Click Create.
    6. Add another Name Server Record for the same domain name. But this time, enter the second GSLB ADNS FQDN.

    7. Repeat this process until all GSLB ADNS FQDNs are specified.
  13. Also add an SOA record for the delegation. If you are delegating individual records, then you will need an SOA for each record. If you are delegating a subzone, you only need an SOA record for the subzone.
    1. On the left, in the menu, go to Traffic Management > DNS > Records > SOA Records.
    2. On the right, click Add.
    3. In the Domain Name field, enter the FQDN that you delegated to NetScaler. This can be an individual record, or a sub-zone.
    4. In the Origin Server field, leave it set to –<< New >> — and then enter the FQDN that resolves to one of your ADNS listeners. It doesn’t matter which one you enter.
    5. In the Contact field, enter an email address that is publicly viewable. Replace the @ symbol with a period.
    6. Click Create.
    7. Repeat this on the other ADCs that are participating in GSLB for this delegated DNS name.

Each GSLB-enabled DNS name must be CNAME’d to GSLB:

  1. In Citrix ADC, go to Traffic Management > GSLB > Virtual Servers, and edit your GSLB Virtual Server.
  2. On the left, click in the GSLB Virtual Server Domain Binding section.
  3. Click Add Binding.
  4. Add a domain binding for the CNAME’d DNS name. For example, if the original DNS name is gateway.corp.com, then enter gateway.gslb.corp.com. gslb.corp.com matches the sub-zone that you delegated to Citrix ADC. Click OK.
  5. Repeat the Domain Binding on the other Citrix ADC appliances.
  6. In DNS Manager, if you currently have a host record for the service that you are delegating to GSLB (gateway.corp.com), delete it.
  7. Right-click the DNS zone, and click New Alias (CNAME).
  8. In the Alias name field, enter the left part of the original DNS name. For gateway.corp.com, enter gateway.
  9. In the Fully qualified domain name (FQDN) for target host field, enter the CNAME’d DNS name that is delegated to Citrix ADC. For example, if you delegated gslb.corp.com to Citrix ADC, then enter gateway.gslb.corp.com. The GSLB Virtual Server must be configured to match this longer DNS name.
  10. Click OK.
  11. If you run nslookup for the delegated DNS name, it will first CNAME to the longer name, and then respond with the IP address returned by Citrix ADC GSLB.
  12. You can repeat these steps to delegate (CNAME) additional DNS names to Citrix ADC GSLB.

RADIUS Authentication – Citrix Gateway

Last Modified: Mar 29, 2021 @ 11:28 am

215 Comments

This article applies to Citrix Gateway 13.0, Citrix Gateway 12.1, and NetScaler Gateway 12.0. Citrix ADC is the new name for NetScaler. Citrix Gateway is the new name for NetScaler Gateway.

Navigation

Change Log

RADIUS Overview

One method of two-factor authentication to Citrix Gateway is the RADIUS protocol with a two-factor authentication product (tokens) that has RADIUS enabled.

  • Another common two-factor authentication method is SAML to an Identity Provider, like Azure Active Directory or Okta. SAML is detailed in the Federated Authentication Service article.

RADIUS Clients and Source IP – On your RADIUS servers, you’ll need to add the ADC appliances as RADIUS Clients. When ADC uses a local (same appliance) load balanced Virtual Server for RADIUS authentication, the traffic is sourced from the ADC SNIP (Subnet IP). When ADC uses a direct connection to a RADIUS Server without going through a load balancing Virtual Server, or uses a remote (different appliance) Load Balancing Virtual Server, the traffic is sourced from the ADC NSIP (ADC Management IP). Use the correct IP(s) when adding the ADC appliances as RADIUS Clients. And adjust firewall rules accordingly.

  • For High Availability pairs, if you locally load balance RADIUS, then you only need to add the SNIP as a RADIUS Client, since the SNIP floats between the two appliances. However, if you are not locally load balancing RADIUS, then you’ll need to add the NSIP of both appliances as RADIUS Clients. Use the same RADIUS Secret for both appliances.

Links:

Some two-factor products (e.g. SMS Passcode) require you to hide the 2nd password field. Receiver 4.4 and newer supports hiding the 2nd field if you configure a Meta tag in index.html.

Two-factor Policies Summary

ADC has two methods of configuring multi-factor authentication:

  • Citrix Gateway Virtual Server has bind points for Primary and Secondary authentication. This functionality is available in all ADC Editions and is detailed in this post.
    • This is the older method of configuring authentication also known as Classic authentication policies. One challenge with Classic policies is that Citrix Workspace app requires the LDAP and RADIUS fields to be swapped.
  • nFactor Authentication supports unlimited factors, but requires ADC Advanced Edition (formerly known as Enterprise Edition) or ADC Platinum Edition.
    • nFactor is the newer authentication configuration method also known as Advanced authentication policies. With nFactor, there’s no need to swap the LDAP and RADIUS fields for Citrix Workspace app.

Workspace app authentication with a Classic Policy configuration looks like a Window that is very difficult to customize.

Workspace app authentication with an nFactor configuration looks like a webpage that is fully customizable.

See the ADC menu page for additional authentication mechanisms supported by Citrix Gateway. Some require nFactor.

When configuring the Citrix Gateway Virtual Server, you can specify both a Primary authentication policy, and a Secondary authentication policy. Users are required to successfully authenticate against both policies before being authorized for Citrix Gateway.

For browser-based StoreFront, you need two authentication policies:

  • Primary = LDAPS authentication policy pointing to Active Directory Domain Controllers.
  • Secondary = RADIUS authentication policy pointing to RSA servers with RADIUS enabled.

For Citrix Workspace app, the classic authentication policies need to be swapped. There’s no need to swap them if doing nFactor (Advanced) policies.

  • Primary = RADIUS authentication policy pointing to RSA servers with RADIUS enabled.
  • Secondary = LDAPS authentication policy pointing to Active Directory Domain Controllers.

With Classic Authentication Policies, if you need to support two-factor authentication from both web browsers and Citrix Workspace app, then you’ll need at least four authentication policies as shown below.

Primary:

  • Priority 90 = RADIUS policy. Expression = REQ.HTTP..HEADER User-Agent CONTAINS CitrixReceiver
  • Priority 100 = LDAP policy. Expression = REQ.HTTP..HEADER User-Agent NOTCONTAINS CitrixReceiver

Secondary:

  • Priority 90 = LDAP policy. Expression = REQ.HTTP..HEADER User-Agent CONTAINS CitrixReceiver
  • Priority 100 = RADIUS policy. Expression = REQ.HTTP..HEADER User-Agent NOTCONTAINS CitrixReceiver

LDAP Server/Action

See the LDAP post for instructions to create an LDAP Server/Action. Only the LDAP server/action is needed. The Policies will be created later.

RADIUS Server/Action

Create a RADIUS Server/Action:

  1. On the left, expand Authentication, and click Dashboard.
  2. On the right, click Add.
  3. Change Choose Server Type to RADIUS.
  4. Give the server a name.
  5. Specify the IP address of the RADIUS load balancing Virtual Server.
  6. Enter the secret key specified when you added the ADCs as RADIUS clients on the RADIUS server. Click Test RADIUS Reachability.
  7. Scroll down, and click More.
  8. Find the Password Encoding drop-down. Change it to mschapv2 if your RADIUS server supports it, c. Microsoft NPS requires mschapv2 to support changing expired Active Directory passwords. 💡
  9. If you want ADC to receive AAA Group information from RADIUS, see CTX222260 Radius Group Extraction from Windows Server 2008/2012 with NetScaler/CloudBridge.
    • RADIUS attribute = 26 (Vendor-Specific)
    • Vendor Code = 3845 (Citrix)
    • Vendor-assigned attribute number = any number (e.g. 1). Configure RADIUS policy on ADC with same attribute number.
    • Attribute value = Group Name
  10. Click Create.

    add authentication radiusAction RSA -serverIP 10.2.2.210 -serverPort 1812 -authTimeout 60 -radKey Passw0rd -passEncoding mschapv2

Advanced Authentication (nFactor) Policies for LDAP and RADIUS

For the older Classic Authentication policies, jump ahead to the Classic Policies section.

Create Advanced Authentication Policies:

  1. In the left menu, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy.
  2. On the right, click Add.
  3. In the Create Authentication Policy window:
    1. Change the Action Type to RADIUS.
    2. Select your RADIUS Action.
    3. Give the policy a name.
    4. Expression = true.
  4. Click Create.
  5. Create another Authentication Policy.
    1. Set Action Type to LDAP.
    2. Select your LDAP Action/Server.
    3. Give the policy a name.
    4. Expression = true.
  6. Click Create.

Create a Policy Label for the second factor, which is typically the RADIUS policy. The first factor (LDAP) does not need a Policy Label.

  1. In the left menu, click Policy Label.
  2. On the right, click Add.
  3. Give the Policy Label a name.
  4. Leave Login Schema set to LSCHEMA_INT. The Login Schema in the first factor will collect both password and passcode in one form so there’s no need for the second factor to collect it again.
  5. Click Continue.
  6. In the Select Policy field, select your RADIUS policy.
  7. Click Bind at the bottom of the page.
  8. Click Done to finish creating the Policy Label.

Create a Login Schema to collect the password and passcode on the same form.

  1. In the left menu, click Login Schema.
  2. On the right, switch to the tab named Profiles and then click Add.
  3. Give the Login Schema a name (e.g. DualAuth).
  4. Click the pencil icon and then open the LoginSchema folder.
  5. Click the DualAuth.xml file on the left. On the right, make sure you click the blue Select button. It’s too easy to miss this step.
    • See my nFactor article for some info on how to customize the Login Schema.
  6. Then click Create.
  7. On the right, switch to the tab named Policies.
  8. Give the Login Schema Policy a name.
  9. Select the Login Schema Profile you just created.
  10. Set the Rule field to true.
  11. Click Create.

Create an Authentication (AAA) Virtual Server to link the factors together.

  1. In the left menu, under AAA – Application Traffic, click Virtual Servers.
  2. On the right, click Add.
  3. Change the IP Address Type to Non Addressable.
  4. Give the AAA vServer a name and then click OK.
  5. In the Certificate section, you can optionally bind a certificate. It doesn’t matter what certificate you choose (typically the Gateway cert). The only thing this certificate binding does is make the AAA vServer show as UP instead of DOWN. Otherwise it has no effect on functionality. Click Continue.
  6. In the Advanced Authentication Policies section, click where it says No Authentication Policy.
  7. In the Select Policy field at the top of the window, select the LDAP policy.
  8. Near the bottom, in the Select Next Factor field, click where it says Click to select.
  9. Select your RADIUS Policy Label and then click Bind. After LDAP is done, nFactor will then move to your RADIUS Policy Label.
  10. Click Continue.
  11. On the right, in the Advanced Settings column, click Login Schemas.
  12. On the bottom left, click where it says No Login Schema.
  13. Select the DualAuth Login Schema you created earlier and then click Bind.
  14. Click Done at the bottom of the page.

Link the AAA vServer to your Gateway vServer:

  1. In the left menu, expand Citrix Gateway and then click Virtual Servers.
  2. On the right, edit your Gateway vServer.
  3. On the right, in the Advanced Settings column, click Authentication Profile.
  4. On the bottom left, in the Authentication Profile section, click the Add button.
  5. Select the AAA vServer you created earlier.
  6. Give the Profile a name and then click Create.
  7. Back in the Gateway vServer, make sure you click OK in the Authentication Profile section. If you forget to click OK then the Authentication Profile won’t be bound.

If you point your Workspace app to the Gateway that has nFactor configured, the authentication window will look like a web page.

Classic Authentication Policies for LDAP and RADIUS

For Advanced Authentication (nFactor) policies, jump back to the Advanced Policies section.

  1. Go to Citrix Gateway > Policies > Authentication > RADIUS.
  2. On the right, in the Policies tab, click Add.
  3. In the Create Authentication RADIUS Policy page:
    1. Name the policy RSA-ReceiverSelfService or similar.
    2. Select the RADIUS server created earlier.
    3. Enter an expression. You will need two policies with different expressions. The expression for Receiver Self-Service is REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver.
      Note: Citrix Gateway 12.1 does not natively support binding of Advanced Authentication Policies so you’ll have to create them as Basic Policies (classic expressions). You can only bind Advanced Authentication Policies using nFactor.
  4. Click Create.
  5. If you see a warning about deprecation, click OK, and ignore it.
  6. Create another RADIUS policy to match the ones shown below. Both RADIUS policies are configured with the same RADIUS server. The only difference between them is the expression (CONTAINS vs NOTCONTAINS):
    Name Expression Server
    RSA-ReceiverSelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver RSA
    RSA-ReceiverForWeb REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver RSA

  7. Go to the Citrix Gateway\Policies\Authentication\LDAP node.
  8. On the Policies tab, create two policies with the expressions shown below. Both LDAP policies are configured with the same LDAP server. The only difference between them is the expression (CONTAINS vs NOTCONTAINS).
    Name Expression Server
    LDAP-Corp-ReceiverSelfService REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver LDAP-Corp
    LDAP-Corp-ReceiverForWeb REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver LDAP-Corp 

add authentication radiusPolicy RSA-ReceiverForWeb "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" RSA

add authentication radiusPolicy RSA-ReceiverSelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" RSA

add authentication ldapPolicy Corp-Gateway-ReceiverForWeb "REQ.HTTP.HEADER User-Agent NOTCONTAINS CitrixReceiver" Corp-Gateway

add authentication ldapPolicy Corp-Gateway-ReceiverSelfService "REQ.HTTP.HEADER User-Agent CONTAINS CitrixReceiver" Corp-Gateway

Bind Two-factor Policies to Gateway

  1. When you create or edit a Citrix Gateway Virtual Server, bind the Basic Authentication Policies as shown in the following table. Priority doesn’t matter because they are mutually exclusive.
    Policy Name Type Bind Point
    LDAP-Corp-ReceiverForWeb LDAP Primary
    RSA-ReceiverSelfService RADIUS Primary
    LDAP-Corp-ReceiverSelfService LDAP Secondary
    RSA-ReceiverForWeb RADIUS Secondary 

    bind vpn vserver gateway.corp.com -policy Corp-Gateway-ReceiverForWeb -priority 100

bind vpn vserver gateway.corp.com -policy RSA-ReceiverSelfService -priority 110

bind vpn vserver gateway.corp.com -policy RSA-ReceiverForWeb -priority 100 -secondary

bind vpn vserver gateway.corp.com -policy Corp-Gateway-ReceiverSelfService -priority 110 -secondary
  2. The Session Policy/Profile for Receiver Self-Service needs to be adjusted to indicate which authentication field contains the Active Directory password. On the Client Experience tab is Credential Index. This needs to be changed to SECONDARY. Leave the session policy for Web Browsers set to Primary.

    set vpn sessionAction "Receiver Self-Service" -ssoCredential SECONDARY
  3. On the StoreFront server, when creating the Citrix Gateway object, on the Authentication Settings page, change the Logon type to Domain and security token. This instructs Receiver / Workspace app to properly handle two-factor authentication. If you change this setting after Receiver / Workspace app has already performed discovery, then users might have to remove the Account from Receiver / Workspace app and re-add it.

LDAP Authentication – Citrix Gateway

Last Modified: Nov 7, 2020 @ 6:34 am

62 Comments

This article applies to Citrix Gateway 13.0, Citrix Gateway 12.1, and NetScaler Gateway 12.0. Citrix ADC is the new name for NetScaler. Citrix Gateway is the new name for NetScaler Gateway.

Navigation

💡 = Recently Updated

Change Log

  • 2018 Dec 21 – updated screenshots for Citrix Gateway 12.1

LDAP Load Balancing

Before you create an LDAP authentication policy, load balance the Domain Controllers. If you don’t load balance your Domain Controllers, then when users enter an incorrect password, the user account will be prematurely locked out because it makes a failed login attempt against each Domain Controller.

If you have multiple domains, create different Load Balancing Virtual Servers for each domain. These multiple Load Balancing Virtual Servers can share the same VIP if their port numbers are different. Or you can use a different VIP for each domain.

Verify LDAPS

Use the tool ldp.exe to verify that the Domain Controllers have valid certificates installed, and the LDAP service account is able to bind to the LDAP tree.

  1. ldp.exe is included with the Remote Server Administration Tools (AD DS Snap-Ins and Command-Line Tools). On Windows Servers, install it from Server Manager > Add Roles and Features > Features > Remote Server Administration Tools > Role Administration Tools > AD DS and AD LDS Tools > AD DS Tools.
  2. Run ldp.exe.
  3. Open the Connection menu, and click Connect.
  4. In the Connect box:
    1. Enter the FQDN of a Domain Controller.
    2. Check the box next to SSL.
    3. Change the port to 636.
  5. Click OK.
  6. If it connected successfully, you can then attempt a bind. If the connection was unsuccessful, then there’s probably an issue with the certificate installed on the Domain Controller.
  7. Open the Connection menu, and click Bind.
  8. In the Bind box:
    1. Change the Bind type to Simple bind.
    2. Enter the service account credentials. You can enter DOMAIN\Username, or you can enter Username@Domain.com.
  9. Click OK.
  10. Look in the right pane to verify a successful bind. If not, fix the credentials and try again.
  11. Once you have successfully binded, you can view the directory tree by opening the View menu, and click Tree.
  12. Click the drop-down to view the directory partitions.
  13. Repeat these steps to verify each Domain Controller, and any load balanced LDAPS.

LDAP Authentication Server

You can configure StoreFrontAuth as an alternative to LDAP. StoreFrontAuth delegates authentication to StoreFront servers instead of performing authentication on Citrix ADC.

To create the LDAP Authentication Server, do the following:

  1. On the left, expand Authentication, and click Dashboard.
  2. On the right, click Add.
  3. Change the Choose Server Type drop-down to LDAP.
  4. In the Name field, enter LDAP-Corp or similar as the name. If you have multiple domains, you’ll need a separate LDAP Server per domain. so make sure you include the domain name.
  5. Change the selection to Server IP. Enter the VIP of the load balancing vServer for LDAP.
  6. Change the Security Type drop-down to SSL.
  7. Enter 636 as the Port. Scroll down.

  8. In the Connection Settings section, do the following:
    1. In the Base DN field, enter your Active Directory DNS domain name in LDAP format.
    2. In the Administrator Bind DN field, enter the credentials of the LDAP bind account in userPrincipalName format. Domain\Username also works.
    3. Enter the Administrator Password.
    4. Click Test Connection. Citrix ADC will attempt to login to the LDAP IP.
  9. Scroll down.
  10. In the Other Settings section, use the drop-downs next to Server Logon Name Attribute, Group Attribute, and Sub Attribute Name to select the default fields for Active Directory.
  11. On the right side of the Other Settings section, check the box next to Allow Password Change.

  12. If you want to restrict Citrix Gateway access to only members of a specific AD group, in the Search Filter field, enter memberOf=<GroupDN>. See the example below:
    memberOf=CN=CitrixRemote,OU=Citrix,DC=corp,DC=local
    You can add :1.2.840.113556.1.4.1941: to the Search Filter so it searches through nested groups. Without this, users will need to be direct members of the filtered group.
    memberOf:1.2.840.113556.1.4.1941:=CN=CitrixRemote,OU=Citrix,DC=corp,DC=local

    Citrix CTX132802 How to Use the ldapsearch Utility on the NetScaler Gateway Enterprise Edition Appliance to Validate a Search Filter
    1. An easy way to get the full distinguished name of the group is through Active Directory Users and Computers.
    2. Open the View menu, and enable Advanced Features. The Attribute Editor is only present if this feature is enabled.
    3. Browse to the group object, right-click it, and click Properties. Note: you cannot use Find. Instead, you must navigate through the tree to find the object.
    4. Switch to the Extensions page. On the right, switch to the Attribute Editor tab. This tab is only visible if Advanced Features are enabled, and you didn’t use the Find feature.
    5. Scroll down to distinguishedName, double-click it, and then copy it to the clipboard.
    6. Back on the Citrix ADC, in the Search Filter field, type in memberOf= and then paste the Distinguished Name right after the equals sign. Don’t worry about spaces.
  13. For another LDAP Search Filter expression, see CTX226808 Expression to exclude multiple domains by using search filter in LDAP on NetScaler 
    !(|(userprincipalname=*@aa.lab.com)(userprincipalname=*@ns.lab.com)
  14. Scroll down, and click More.
  15. For Nested Group Extraction, if desired, change the selection to Enabled. Configuring Nested Group Extraction allows the Nested Groups to be used for AAA Groups.
    1. Set Group Name Identifier to samAccountName.
    2. Set Group Search Attribute to memberOf. Select << New >> first.
    3. Set Group Search Sub-Attribute to CN. Select << New >> first.
    4. For the Group Search Filter field, see CTX123795 Example of LDAP Nested Group Search Filter Syntax.
  16. Scroll down, and click Create.

    add authentication ldapAction Corp-Gateway -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn "corp\\ctxsvc" -ldapBindDnPassword Passw0rd -ldapLoginName samaccountname -searchFilter "memberOf:1.2.840.113556.1.4.1941:=CN=Citrix Remote,CN=Users,DC=corp,DC=local" -groupAttrName memberOf -subAttributeName CN -secType SSL -passwdChange ENABLED
  17. The status of the LDAP Server should be Up.

LDAP Policy Expression

The Authentication Dashboard doesn’t allow you to create the LDAP Policy, so you must create it elsewhere.

You can create the LDAP policy now. Or you can wait and create it later when you bind the LDAP Server to the Citrix Gateway vServer.

To create it now:

  1. Enter LDAP in the menu Search box to find one of the nodes that lets you create Basic Authentication Policies.

    • Or, navigate to Citrix Gateway > Policies > Authentication > LDAP.
  2. On the right, in the Policies tab, click Add.
  3. Change the Server drop-down to the LDAP Server you created earlier.
  4. Give the LDAP Policy a name (one for each domain).
  5. In the Expression box, enter ns_true.
    • Citrix Gateway does not support Advanced Authentication policies bound directly to the Gateway Virtual Server. If you prefer Advanced Authentication Policies, then you’ll instead need to configure nFactor.
  6. Click Create.

     add authentication ldapPolicy LDAP-Corp ns_true LDAP-Corp
  7. If you see a message about classic authentication policies deprecation, click OK and ignore it.

Gateway Authentication Feedback

  1. On the left, under Citrix Gateway, click Global Settings.
  2. On the right, in the right column, click Change authentication AAA settings.
  3. Optionally, near the middle of the page, check the box for Enable Enhanced Authentication Feedback. This feature provides a message to users if authentication fails. The messages users receive include password errors, account disabled or locked, or the user is not found, to name a few. This setting might not be advisable in a secure environment.
  4. Click OK.

    set aaa parameter -enableEnhancedAuthFeedback YES

Next Step

Multiple Domains – UPN Method

Cascade – To support multiple Active Directory domains on a Citrix Gateway, you create multiple LDAP authentication policies, one for each Active Directory domain, and bind all of the LDAP policies to the Citrix Gateway Virtual Server. When the user logs into Citrix Gateway, only the username and password are entered. The Citrix ADC will then loop through each of the LDAP policies in priority order until it finds one that contains the entered username/password.

Same user/password in multiple domains – What if the same username is present in multiple domains? As Citrix ADC loops through the LDAP policies, as soon as it finds one with the specified username, it will try to authenticate with that particular LDAP policy. If the password doesn’t match the user account for the attempted domain, then a failed logon attempt will be logged in that domain and Citrix ADC will try the next domain.

Unfortunately, the only way to enter a realm/domain name during user authentication is to require users to login using userPrincipalNames. To use userPrincipalName, configure the LDAP Policy/Server with the Server Logon Name Attribute set to userPrincipalName.

You can even do a combination of policies: some with samAccountName, and some with userPrincipalName. Bind the userPrincipalName policies with higher priority (lower priority number) than the samAccountName policies so the UPN policies are tried first.

Citrix ADC supports adding a domain name drop-down list to the logon page. Then use Cookie expressions in the auth policies and session policies. However, this probably doesn’t work when authenticating through Workspace app or Receiver. See CTX203873 How to Add Drop-Down Menu with Domain Names on Logon Page for NetScaler Gateway 11.0 64.x and later releases for details.

Another option for a domain drop-down is nFactor Authentication for Citrix Gateway. The newest versions of Citrix ADC 12.1 are supposed to support nFactor authentication in the newest versions of Workspace app.

After authentication is complete, a Session Policy will be applied that has the StoreFront URL. The Citrix Gateway will attempt to Single Sign-on to StoreFront so the user doesn’t have to login again. When logging into Citrix Gateway, only two fields are required: username and password. However, when logging in to StoreFront, a third field is required: domain name. So how does Citrix ADC specify the domain name while logging in to StoreFront?

In a single domain configuration, you simply edit your Session Policy/Profile and on the Published Applications tab configure the Single Sign-on field with your domain name. However, this method won’t work if users are authenticating to multiple domains.

For authentication to multiple domains, Citrix Gateway has two methods of identifying the domain name based on which LDAP Policy/Server authenticated the user:

  • userPrincipalName – the easiest method is to configure the LDAP policy/server to extract the user’s UPN, and then Single Sign-on to StoreFront using UPN. This is the easiest method, but some domains don’t have userPrincipalNames configured correctly. StoreFront needs to accept the userPrincipalName suffixes.
  • AAA Group – as the Citrix ADC loops through the LDAP policies during authentication, once a successful LDAP policy is found, the LDAP Server can put the user in a domain-specific AAA Group. Then you can bind a Session Policy with domain name to the domain-specific AAA Group.
    • LDAP Servers have a field called Default Authentication Group. If the user successfully authenticates with this LDAP Server, then the user is placed in the AAA Group name specified here. Specify a unique Default Authentication Group per LDAP Server. Then create AAA Groups with the same names you specified in the LDAP Servers. Bind domain-specific Session Policies with domain name to each of the AAA Groups. See Multiple Domains – AAA Group Method for details.
    • Another option is to create a unique domain-specific group in each Active Directory domain and add users to these domain-specific groups. Each domain has a different name for this AD group. Citrix ADC will extract this group during the user’s login. Create AAA Groups on Citrix ADC that match these Active Directory group names and bind domain-specific Session Policies with domain name to each of the AAA Groups.

The userPrincipalName method is detailed below:

  1. In each of your Citrix ADC LDAP policies/servers, in the Other Settings section, in the SSO Name Attribute field, enter userPrincipalName (select –<< New >>– first). Make sure there are no spaces after this attribute name. Citrix ADC will pull this attribute from AD, and use it to Single Sign-on the user to StoreFront. Notice that Server Logon Name Attribute is still sAMAccountName.
  2. In StoreFront Console, in the middle, right-click your Store, and click Manage Authentication Methods.
  3. On the right, click the gear icon, and then click Configure Trusted Domains.
  4. In the Trusted domains box, select Any domain.
  5. Or add your UPN domain suffixes in DNS format. The advantage of entering domain names is that you can select a default domain. The DNS format is required for UPN logins (e.g. SSO from Citrix Gateway).
  6. On the Citrix Gateway Virtual Server, bind LDAP authentication polices in priority order. It will search them in order until it finds a match.
  7. In your Session Policies/Profiles, in the tab named Published Applications, make sure Single Sign-on Domain is not configured. Since Citrix ADC is using the userPrincipalName, which inherently contains a domain name, there’s no need for a Session Policy to specify a domain name. If the Single Sign-on Domain field is configured, then Single Sign-on authentication will fail.

Multiple Domains – AAA Groups Method

Another method of specifying the domain name when performing Single Sign-on to StoreFront is to use a unique session policy/profile for each domain. Use AAA Groups to distinguish one domain from another.

  1. Go to Citrix Gateway > Policies > Authentication > LDAP. The easiest way to get there is to enter LDAP in the search box at to the top of the menu.
  2. On the right, switch to the tab named Servers.
  3. Make sure all domains are in the list. Edit the LDAP Server for one of the domains.
  4. Scroll down to the Other Settings section,
  5. On the right, in the Default Authentication Group field, enter a new, unique group name. Each domain must a different group name. This group is only locally significant and does not need to be added to AD. Click OK.
  6. Edit the LDAP Server for another domain.
  7. Specify a new unique group name for this domain. Each domain has a different group name.
  8. In the menu, go to Citrix Gateway > User Administration > AAA Groups.
  9. On the right, click Add.
  10. Name the group so it exactly matches the group name you specified in the LDAP Server. Click OK.
  11. On the right, in the Advanced Settings section, click Policies to move it to the left.
  12. On the left, in the Policies section, click the Plus icon.

    1. In the Choose Type page, select Session, and click Continue.
    2. Click the Add button or plus icon to create a new Session policy.
    3. Give the Session Policy a name that indicates the domain. You will have a separate Session Policy for each domain.
    4. Click the Add button or plus icon to create a new Session Profile.
    5. Give the Session Profile a name that indicates the domain. You will have a separate profile for each domain.
    6. Switch to the tab named Published Applications.
    7. Scroll down and next to Single Sign-on Domain check the Override Global box .
    8. Enter the domain name that StoreFront is expecting for this LDAP Server. Click Create.
    9. If your other Session Policies are created using Advanced syntax, then leave this Session Policy as Advanced Policy and enter true as the Expression.
      • If your other Session Policies are created using Classic syntax, then change this Session Policy to Classic Policy and enter ns_true as the Expression.
    10. Click Create.
    11. In the Priority field, give it a number that is lower than any other Session Policy that has Single Sign-on Domain configured so that this Session Policy will override those other Session Policies. Then click Bind.
    12. Click Done.
  13. Create another AAA Group.
  14. Give it the AAA Group a name that matches the Default Authorization Group configured for the next domain.
  15. On the right, click Policies to move it to the left.
  16. On the left, click the Plus icon to add a policy binding.
  17. For Choose Type, select Session and click Continue.
  18. In the Policy Binding field, click Add to create another Session Policy.
  19. In the Profile drop-down, click Add to create another Session Profile.
  20. On the Published Applications tab, specify the domain name of the next domain.
  21. Set the Session Policy Expression to either true (Advanced) or ns_true (Classic).
  22. Bind the new policy with a low Priority number.
  23. When a user logs in, Citrix ADC loops through LDAP policies until one of them works. Citrix ADC adds the user to the Default Authentication Group specified in the LDAP Server. Citrix Gateway finds a matching AAA Group and applies the Session Policy that has SSON Domain configured. Since the policy is bound with a low priority number, it overrides any other Session Policy that also has SSON Domain configured.

Native One Time Passwords (OTP) – NetScaler Gateway 12 / Citrix Gateway 12.1

Last Modified: Oct 17, 2024 @ 12:50 pm

312 Comments

Navigation

Change Log

Overview

NetScaler Native OTP lets you enable two-factor authentication without purchasing any other authentication product. A typical configuration uses Google Authenticator to generate Passcodes. See the following for an overview:

Here are some notes:

  • NetScaler Native OTP is part of nFactor, and thus requires Citrix ADC Advanced Edition (aka NetScaler Enterprise Edition) or Citrix ADC Premium Edition (aka NetScaler Platinum Edition) licensing. NetScaler ADC Standard Edition licensing is not sufficient.
  • Workspace app 1809 and newer with Citrix Gateway (NetScaler) 12.1 build 49 and newer support nFactor authentication. Older Receivers and older NetScalers don’t support it, so you’ll instead have to use a web browser.  💡
  • Citrix Gateway VPN Plug-in 12.1 build 49 and later support nFactor when authenticating using the VPN Plug-in.  💡
  • nFactor requires a AAA vServer, which can be non-addressable – you don’t need any additional public IPs.
  • OTP stores device enrollment secrets in an Active Directory attribute that accepts Strings. Citrix’s documentation uses the userParameters Active Directory attribute.
    • The LDAP bind account must have permission to modify this attribute on every user.
  • Users can enroll multiple devices. There’s no way to prevent this.
  • The manageotp website is usually only protected by single factor authentication. Since users can add multiple devices, the manageotp website must be protected from external access.
  • Christian in the comments indicated that Microsoft Authenticator also works. Click on plus sign -> other (Google,…).

Here are the OTP configuration objects:

  • Make sure NTP is configured on the NetScaler. Accurate time is required.
  • An LDAP Policy/Server with authentication disabled and OTP Secret configured. This one OTP-specific LDAP Policy/Server can be used for two scenarios:
    • manageotp device enrollment
    • Two-factor authentication to NetScaler Gateway after a device has been enrolled. This LDAP Policy/Server verifies the entered passcode.
  • An LDAP Policy/Server with authentication enabled. This one policy is used for two scenarios:
    • Single-factor authentication to the manageotp authenticator/device enrollment website.
    • Two-factor authentication to NetScaler Gateway after a device has been enrolled.
  • A single non-addressable AAA vServer with two Login Schemas for the following scenarios:
    • A single-factor Login Schema for manageotp.
    • A dual-factor Login Schema for NetScaler Gateway authentication.
  • An Authentication Profile to link the AAA vServer to the NetScaler Gateway vServer.

LDAP Policies/Actions

  1. Go to Security > AAA – Application Traffic > Polices > Authentication > Advanced Policies > Actions > LDAP.
  2. On the right, click Add.

    1. Create a normal LDAP Server if you don’t have one already. This one has Authentication enabled. This LDAP Policy/Server will be used for single-factor authentication to the manageotp website, and for first factor of dual-factor authentication to NetScaler Gateway (second factor is OTP). There are no special instructions for this LDAP Server.
  3. Create another LDAP Action.

    1. This one is used by the manageotp site to set the OTP authenticator in Active Directory, so name it accordingly.
    2. On the right, uncheck the box next to Authentication. If you don’t uncheck it, you will see an error message after configuring the OTP Secret.
    3. Make sure the Administrator Bind DN has permissions to modify the OTP Secret Active Directory attribute for all users.
    4. If you cloned an existing LDAP Server, then make sure you re-enter the Administrator Password or the new one won’t work. Then click Test LDAP Reachability.
    5. Configure the Server Logon Name Attribute to match the one you configured in the normal authentication LDAP Server.
    6. In the Other Settings section, on the bottom right, find the OTP Secret field. Enter the name of the Active Directory attribute where NetScaler will store the user’s OTP secret. You can use the userParameters attribute if that attribute isn’t being used for anything else.
    7. Thomas Rolfs in the comments advises not to enable Nested Group Extraction in this LDAP Action.
    8. Click Create when done.
  4. Create another LDAP Action.
    1. This one will verify the OTP code entered by the user, so name it accordingly. The only difference from the prior one is the addition of an LDAP Search Filter.
    2. On the right, uncheck the box next to Authentication. If you don’t uncheck it, you will see an error message after configuring the OTP Secret.
    3. Make sure the Administrator Bind DN has permissions to read the OTP Secret Active Directory attribute.
    4. If you cloned an existing LDAP Server, then make sure you re-enter the Administrator Password or the new one won’t work.
    5. In the Other Settings section, configure the Server Logon Name Attribute to match the one you configured in the normal authentication LDAP Server.
    6. In the Search Filter field, enter the text userParameters>=#@. This syntax ensures that only users with enrolled authenticators can login. See George Spiers NetScaler native OTP for more info.
    7. In the Other Settings section, on the bottom right, find the OTP Secret field. Enter the name of the Active Directory attribute containing the user’s OTP secret.
    8. Click Create when done.
  5. Go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy.
  6. On the right, click Add.

    1. You probably don’t already have an Advanced Authentication Policy for your normal LDAP server.
    2. Change the Action Type to LDAP.
    3. Select your normal LDAP server, which is the one that has Authentication enabled.
    4. Enter true as the expression. This uses Default Syntax instead of Classic Syntax.
    5. Click Create.
  7. Create another Authentication Policy.

    1. This policy is for OTP management so name it accordingly.
    2. Change the Action Type to LDAP.
    3. Select the Set OTP LDAP Server that has Authentication disabled and OTP Secret configured. This LDAP Action should not have the Search Filter configured.
    4. Enter HTTP.REQ.COOKIE.VALUE(“NSC_TASS”).EQ(“manageotp”) in the Expression box, and click Create.
  8. Create another Authentication Policy.

    1. This policy is for OTP verification so name it accordingly.
    2. Change the Action Type to LDAP.
    3. Select the OTP Verification LDAP Server that has Authentication disabled and OTP Secret configured. This LDAP Action should have the Search Filter configured to prevent unenrolled users from authenticating.
    4. Enter true in the Expression box, and click Create.

Login Schemas

  1. Go to Security > AAA – Application Traffic > Login Schema.
  2. On the right, switch to the Profiles tab, and click Add.

    1. This is the single factor Login Schema for manageotp so name the Schema accordingly.
    2. Click the Edit icon.
    3. On the left, click the LoginSchema folder to open it.
    4. Scroll down, and click SingleAuthManageOTP.xml to highlight it.
    5. On the top right, click Select.
    6. Click Create.
  3. Add another Login Schema profile.

    1. This Login Schema is for two-factor authentication to NetScaler Gateway so name it accordingly.
    2. Click the edit icon. Follow the same procedure as above, but this time select /LoginSchema/DualAuth.xml.
    3. Click More to reveal more options.
    4. Scroll down. In the Password Credential Index field, enter 1. This causes nFactor to save the user’s password into AAA Attribute #1, which we’ll use later in a Traffic Policy to Single Sign-on to StoreFront. If you don’t do this, then NetScaler Gateway will try to use the Passcode to authenticate to StoreFront, which obviously won’t work.
    5. Check the box next to Enable Single Sign On Credentials. Mark in the comments indicates that this checkbox is needed to Single Sign On to RDP Hosts.
    6. Click Create.
  4. On the right, switch to the Policies tab.
  5. Click Add to add a Login Schema policy.
    1. In the Profile field, select the Single Factor Manage OTP Login Schema Profile.
    2. Name the Login Schema Policy for OTP management.
    3. In the Rule field, enter the following. This ensures that this single factor Login Schema is only used if the user enters /manageotp, and if the user is on the internal network. You don’t want manageotp to be accessible externally, because it’s only protected by single factor authentication, and it’s too easy to add multiple devices. 
      http.req.cookie.value("NSC_TASS").eq("manageotp") && client.IP.SRC.IN_SUBNET(10.2.0.0/16)
    4. Click Create.
  6. Create another Login Schema Policy.

    1. In the Profile field, select the dual factor Login Schema.
    2. Name the Login Schema to indicate dual factor authentication.
    3. In the Rule box, enter true.
    4. Click Create.

Authentication PolicyLabel

  1. Go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > PolicyLabel.
  2. On the right, click Add.
  3. This PolicyLabel is for OTP management, and OTP verification, so name it accordingly.
  4. In the Login Schema field, select LSCHEMA_INT, which means noschema.
  5. Click Continue.
  6. In the Policy Binding section, Click to select.
  7. Click the radio button button next to the Manage OTP LDAP Policy that has authentication disabled, and OTP Secret configured. This one should have a policy expression that limits it to manageotp only. Click Select.
  8. Click Bind.
  9. Click Add Binding to add another one.
  10. Click to select.
  11. Click the radio button next to the LDAP Policy that verifies OTP. Click Select.
  12. Click Bind.
  13. Make sure the manageotp policy is higher in the list than the OTP Verification policy. To adjust priorities, right-click on the policies, and click Edit Binding. Click Done.

AAA vServer

  1. Go to Security > AAA – Application Traffic.
    1. If the AAA feature is not enabled, then right-click the AAA node, and click Enable Feature.
  2. Go to Security > AAA – Application Traffic > Virtual Servers.
  3. On the right, click Add.
  4. This AAA vServer is for OTP so name it accordingly.
  5. Change the IP Address Type to Non Addressable.
  6. Click OK.
  7. Click where it says No Server Certificate.

    1. In the Server Certificate Binding section, click Click to select.
    2. Click the radio button next to a certificate, and click Select. You can use the same certificate as NetScaler Gateway.
    3. Click Bind.
  8. Click Continue to close the Certificate section.
  9. In the Advanced Authentication Policies section, click where it says No Authentication Policy.

    1. Click where it says Click to select.
    2. Click the radio button next to the normal LDAP Policy that has authentication enabled. Then click the blue Select button.
    3. In the Select Next Factor field, click where it says Click to select.
    4. Click the radio button next to the OTP PolicyLabel, and click Select.
    5. Click Bind.
  10. In the Advanced Authentication Policies section, click Continue.
  11. On the right, in the Advanced Settings column, click Login Schemas.
  12. On the left, scroll down, and click where it says No Login Schema.

    1. Click where it says Click to select.
    2. Click the radio button next to the Manage OTP Login Schema, and click Select.
    3. Click Bind.
  13. Click where it says 1 Login Schema.

    1. Click Add Binding.
    2. Click where it says Click to select.
    3. Click the radio button next to the dual factor Login Schema, and click Select.
    4. Click Bind.
    5. Make sure the single factor Manage OTP Login Schema is higher in the list (lower priority number) than the dual factor Login Schema. Click Close.
  14. On the right, in the Advanced Settings column, click Portal Themes.
  15. On the left, scroll down, select RfWebUI as the Portal Theme, and click OK.
  16. Click Done.

Traffic Policy for Single Sign-on

  1. On the left, go to NetScaler Gateway > Policies > Traffic.
  2. On the right, switch to the Traffic Profiles tab, and click Add.
  3. This Traffic Profile is for OTP and/or nFactor. Name it accordingly.
  4. Scroll down.
  5. In the SSO Password Expression box, enter the following. This is where we use the Login Schema Password Attribute specified earlier. 
    http.REQ.USER.ATTRIBUTE(1)
  6. Click Create.
  7. On the right, switch to the Traffic Policies tab, and click Add.
  8. In the Request Profile field, select the Traffic Profile you just created.
  9. Name the Traffic Policy.
  10. In the Expression box, enter true (Default Syntax).
    • If your NetScaler Gateway Virtual Server allows full VPN, change the expression to the following. Source = Julien Mooren at NetScaler – Native OTP is breaking SSL VPN. 
      http.req.method.eq(post)||http.req.method.eq(get) && false
  11. Click Create.

NetScaler Gateway and Authentication Profile

  1. Go to NetScaler Gateway > Virtual Servers.
  2. Edit an existing Gateway vServer. If you don’t have one, see the other NetScaler Gateway topics on this site.
  3. Scroll down to the Policies section, and click the plus icon.
  4. Change the Choose Policy drop-down to Traffic, and click Continue.
  5. Click to select.
  6. Click the radio button next to the Traffic Policy you created earlier, and click Select.
  7. Click Bind.
  8. On the right, in the Advanced Settings column, click Authentication Profile.
  9. On the left, scroll down to the Authentication Profile section.
  10. Click Add to create one.
  11. Authentication Profile links the NetScaler Gateway vServer with the OTP AAA vServer, so name it accordingly.
  12. In the Authentication Virtual Server section, Click to select.
  13. Click the radio button next to the OTP AAA vServer, and click Select.
  14. Click Create.
  15. Scroll down again to the Authentication Profile section, and click OK.
  16. The Portal Theme bound to the Gateway vServer should be RfWebUI, or a derivative.
  17. Go to System > Profiles.
  18. On the right, switch to the SSL Profile tab.
  19. Edit the ns_default_ssl_profile_frontend profile.
  20. Make sure HSTS is not enabled in the profile, or RfWebUI, and manageotp won’t work correctly. This is probably a bug. Note: the Rewrite method of enabling HSTS should work.

Update Content Switching Expression for Unified Gateway

If your NetScaler Gateway Virtual Server is behind a Unified Gateway (Content Switching Virtual Server), then you must update the Content Switching Expression to include the manageotp paths.

  1. In the NetScaler GUI, navigate to Configuration> Traffic Management > Content Switching > Policies.
  2. On the right, select the Unified Gateway Content Switching Policy, and then click Edit.
  3. Append the following expression under the Expression area, and then click OK. 
    || HTTP.REQ.URL.CONTAINS("/manageotp")

Manageotp

  1. Point your browser to https://mygateway.corp.com/manageotp or similar. Simply add /manageotp to the end of your Gateway URL.
  2. Notice it’s only single-factor authentication. Login using normal LDAP credentials.
  3. Click Add Device.
  4. Enter a device name, and click Go.
  5. Launch the Google Authenticator application on your phone. Click the plus icon in Google Authenticator, and scan the QRCode that is shown on the screen.
  6. Christian in the comments indicated that Microsoft Authenticator also works. Click on plus sign -> other (Google,…).
  7. Click Test.
  8. Enter the passcode shown in your Authenticator, and click Go.
  9. If you logoff of manageotp, and access your Gateway URL normally, you’ll be prompted for two-factor authentication. Use the passcodes shown in your Google Authenticator application.
  10. It should Single Sign-on into StoreFront.

CLI Commands

Here’s a complete CLI configuration.

add ssl certKey WildcardCorpCom -cert WildcardCorpCom.pfx -key WildcardCorpCom.pfx -inform PFX -passcrypt "abc"
add authentication ldapAction LDAP-Corp -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword abc -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED -Attribute2 userParameters
add authentication ldapAction LDAP_OTP_set_no_auth -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn admin@corp.local -ldapBindDnPassword abc -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED -OTPSecret UserParameters
add authentication ldapAction LDAP_OTP_verify_no_auth -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn admin@corp.local -ldapBindDnPassword abc -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -searchFilter "userParameters>=#@" -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED -OTPSecret UserParameters
add authentication Policy Corp-Adv -rule true -action LDAP-Corp
add authentication Policy LDAP_Manage_OTP-pol -rule "HTTP.REQ.COOKIE.VALUE(\"NSC_TASS\").EQ(\"manageotp\")" -action LDAP_OTP_set_no_auth
add authentication Policy LDAP_Confirm_OTP-pol -rule true -action LDAP_OTP_verify_no_auth

add authentication loginSchema Dual_OTP-lschema -authenticationSchema "/nsconfig/loginschema/LoginSchema/DualAuth.xml" -passwordCredentialIndex 1
add authentication loginSchema Single_Manage_OTP-lschema -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuthManageOTP.xml"
add authentication loginSchemaPolicy Single_Manage_OTP-lschemapol -rule "http.req.cookie.value(\"NSC_TASS\").eq(\"manageotp\") && client.IP.SRC.IN_SUBNET(10.3.0.0/16)" -action Single_Manage_OTP-lschema
add authentication loginSchemaPolicy Dual_OTP-lschemapol -rule true -action Dual_OTP-lschema

add authentication policylabel OTP_pollabel -loginSchema LSCHEMA_INT
bind authentication policylabel OTP_pollabel -policyName LDAP_Manage_OTP-pol -priority 100 -gotoPriorityExpression NEXT
bind authentication policylabel OTP_pollabel -policyName LDAP_Confirm_OTP-pol -priority 110 -gotoPriorityExpression NEXT 

add authentication vserver OTP-AAA SSL 0.0.0.0
bind ssl vserver OTP-AAA -certkeyName WildcardCorpCom

bind authentication vserver OTP-AAA -portaltheme RfWebUI
bind authentication vserver OTP-AAA -policy Single_Manage_OTP-lschemapol -priority 100 -gotoPriorityExpression END
bind authentication vserver OTP-AAA -policy Dual_OTP-lschemapol -priority 110 -gotoPriorityExpression END
bind authentication vserver OTP-AAA -policy Corp-Adv -priority 100 -nextFactor OTP_pollabel -gotoPriorityExpression NEXT

add vpn trafficAction OTP-trafficprofile http -passwdExpression "http.REQ.USER.ATTRIBUTE(1)"
add vpn trafficPolicy OTP-trafficpol true OTP-trafficprofile

add authentication authnProfile OTP-authnprofile -authnVsName OTP-AAA

add vpn vserver Gateway.corp.com SSL 10.2.5.220 443 -downStateFlush DISABLED -Listenpolicy NONE -authnProfile OTP-authnprofile
set ssl vserver Gateway.corp.com -sslProfile ns_default_ssl_profile_frontend
add vpn sessionAction "Receiver For Web" -transparentInterception OFF -defaultAuthorizationAction ALLOW -SSO ON -icaProxy ON -wihome "https://storefront2.corp.com/Citrix/StoreWeb" -ntDomain corp.local -clientlessVpnMode OFF -storefronturl "https://storefront2.corp.com"
add vpn sessionPolicy "Receiver For Web" "HTTP.REQ.HEADER(\"User-Agent\").CONTAINS(\"CitrixReceiver\").NOT" "Receiver For Web"
bind vpn vserver Gateway.corp.com -portaltheme RfWebUI
bind vpn vserver Gateway.corp.com -policy "Receiver For Web" -priority 100 -gotoPriorityExpression NEXT -type REQUEST
bind vpn vserver Gateway.corp.com -policy OTP-trafficpol -priority 100 -gotoPriorityExpression END -type REQUEST
bind ssl vserver Gateway.corp.com -certkeyName WildcardCorpCom

Citrix ADC Fundamental Concepts: Part 2 – Certificates/SSL, Authentication, HTTP, VPN Networking, PXE, GSLB

Last Modified: Jan 9, 2021 @ 7:00 am

7 Comments

Navigation

💡 = Recently Updated

Change Log

  • 2018 Dec 26 – complete proofread, revised, and expanded
  • 2018 Dec 24 – renamed NetScaler to Citrix ADC

Citrix ADC is NetScaler

Citrix renamed their NetScaler product to Citrix ADC. ADC is a Gartner term that means Application Delivery Controller, which is a fancy term that describes a load balancing device that does more than just load balancing.

This article assumes that you have already read the content in Part 1 – Request-Response, HTTP Basics, and Networking

HTTP Encryption

SSL Protocol

SSL/TLS Protocol – SSL (Secure Sockets Layer) and TLS (Transport Layer Security) are two names for the same encrypted session protocol. SSL is the older, more well-known name, and TLS is the newer, less well-known name. The names can usually be used interchangeably, although pedantic people will insist on using TLS instead of SSL. In Citrix ADC, you’ll mostly see the term SSL instead of TLS.

  • HTTP on top of SSL/TLS – HTTP itself does not support encryption. Instead, a Layer 6 SSL/TLS-encrypted Session is established between the Web Client and the Web Server. Then Layer 7 HTTP packets are sent across the Layer 6 SSL/TLS session. (image from wikimedia)
  • SSL/TLS can carry more than just HTTP – for example, Citrix ICA Protocol is carried across an SSL/TLS session when ICA traffic is proxied through Citrix Gateway. There is no HTTP in this encrypted traffic. ICA and HTTP are two completely different protocols. Underneath both of them are the same Layer 6 SSL/TLS session protocol.
  • HTTPS Protocol is the name that web browsers use to describe HTTP running on top of an encrypted TLS/SSL session. It’s the same HTTP data whether the underlying TCP connection is encrypted or not.

HTTPS Protocol:

  • Port 443 – HTTP over SSL/TLS uses a different port number than unencrypted HTTP. The SSL/TLS port number for HTTP data is usually TCP port 443, and is referred to as the https port number. The https port number will not accept HTTP Packets until the SSL/TLS encrypted session is established first.
  • Web Server support for https – Web Servers must be explicitly configured to accept https traffic. Enabling SSL/TLS on a web server requires creation of a key pair, a certificate, and binding them to a TCP 443 listener. No certificate configuration is needed on the client side. Below is a screenshot of enabling https on an IIS Web site.
  • https URL scheme– Users enter https://FQDN into a web browser’s address bar to connect to a web server using the SSL/TLS protocol on TCP 443.
  • Disable http? – Once https is enabled on a web server, you can optionally disable clear-text HTTP over TCP 80. Or you can leave the TCP 80 listener enabled and configure it to redirect unencrypted HTTP TCP 80 connections to https TCP 443 encrypted connections.
    • See SSL Redirect – Methods for information on how to configure an ADC application to redirect HTTP port 80 to HTTPS port 443.

SSL/TLS versions – There are several versions of the SSL/TLS protocol. Here are the versions from oldest to newest: SSLv2, SSLv3, TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3

  • After SSLv3, the protocol was renamed to Transport Layer Security (TLS). All versions of TLS are newer than the SSL versions.
    • Many networking products use the term SSL to refer to all versions of the protocol, including the TLS versions. For example, in Wireshark, the traffic filters use the word “ssl” instead of “tls”. Citrix ADC hosts “SSL” Virtual Servers, but not “TLS” Virtual Servers.
  • TLSv1.3 is very new and only recently started being added to products. Citrix ADC 12.1 added support for TLSv1.3.
  • TLSv1.2 is the current widely-deployed standard.
  • In late 2018 and early 2019, industry security standards are starting to dictate that TLSv1.0 and TLSv1.1 should be disabled in all products and servers. PCI compliance already dictates that TLSv1.0 and TLSv1.1 must be disabled.
  • SSLv3 is an old, vulnerable protocol, and must be disabled on all SSL Virtual Servers.
  • Default Citrix ADC SSL configuration enables SSL protocol versions SSLv3, TLSv1.0, TLSv1.1, and TLSv1.2. One of the first configuration steps that should be performed on every ADC SSL Virtual Server is to disable SSLv3, disable TLSv1.0, and disable TLSv1.1.

    • Newer builds of Citrix ADC let you configure SSL defaults at the global level by enabling the “default SSL profile”. See SSL Profiles for details.
  • SSLLabs.com can check your SSL Listener to make sure it adheres to the latest SSL security standards.

SSL Performance Cost – First, the SSL Client and SSL Server create an encrypted SSL Session by performing an SSL Handshake. Then HTTP is transmitted across this established SSL Session.

  • SSL Handshake is expensive – Establishing the SSL session (SSL Handshake) is an expensive (CPU) operation, and modern web servers and web browsers try to minimize how often it occurs, preferably without compromising security. (image from wikimedia)
  • Bulk encryption – The traffic on top of the established SSL Session is bulk encrypted, which has far less impact than initial SSL Session establishment.
  • ADC Appliance SSL Specs – The Citrix ADC appliance model data sheets provide different numbers for SSL Transactions/sec (initial session establishment) and SSL Throughput (bulk encryption).

SSL Keys

Public/Private key pair – A key pair is called a pair because the Public Key and Private Key are cryptographically linked together. Data encrypted by a Public Key can only be decrypted by one Private Key. Data encrypted by the Private Key can only be decrypted by one Public Key.

  • Asymmetric Encryption – traffic encrypted by a Public Key cannot be decrypted by the same Public Key. Any traffic encrypted by the Public Key can only be decrypted by its paired Private Key. This is called Asymmetric because you encrypt with one key and decrypt with a different key. (image from wikimedia)
  • Private key – The Private Key is called private because it needs to remain private. You must make sure that the Private Key is never revealed to any unauthorized individual. If that were to occur, then the unauthorized person could use the Private Key to emulate the web server, and unsuspecting users might submit private data, including passwords, to the hacker.
    • Hardware Security Module (HSM) – if you store the Private Key on an HSM, then it is not possible to export the private key from the HSM and thus nobody can see it. Any use of the private key occurs inside the HSM. Governments and other high security industries require private keys to be stored in HSMs.
  • Public key – The Public Key is called public because it doesn’t matter who has it. The public key is worthless without also having access to the private key.

Key size – When you create a public/private key pair, you specify the key size in bits (e.g. 2048 bits). The higher the bit size, the harder it is to crack. However, larger key sizes mean exponentially more processing power required to encrypt and decrypt. 2048 is the current recommended key size, even for Certificate Authorities, which use the same key pair for many years. 2048 balances security with performance.

Symmetric Encryption – With Symmetric Encryption, one key is used for both encryption and decryption. Symmetric Encryption is far less CPU intensive than Asymmetric Encryption. In https protocol, bulk data encryption and decryption is performed by a symmetric key, not asymmetric keys. But a challenge with Symmetric Encryption is how to get both sides of the connection to agree on the one symmetric key.

  • During the initial SSL handshake process, the Web Server’s public key is transmitted to the SSL Client.
  • During the initial SSL Handshake, the SSL Client generates a Session Key for symmetric encryption, encrypts the generated Session Key using the Web Server’s Public Key, and then sends the encrypted Session Key to the Web Server. The Web Server uses its Private Key to decrypt the Session Key. Now both sides have the same Symmetric key and they can use that Symmetric Key for bulk encryption and decryption.

Session Key size – the Session Key is much shorter than the private/public key pairs. For example, the Session Key can be 256 or 384 bits, while the public/private key pairs are 2048 bits. Because of their shorter size, Session Keys are much faster at cryptographic operations than public/private key pairs. The length of the Session Key depends on the negotiated cipher, as detailed later.

  • Renegotiation – SSL Clients and SSL Servers will sometimes want to redo the SSL Handshake while in the middle of an SSL Session. This is called Renegotiation.
  • Because the Session Key is relatively small, a new Session Key needs to be regenerated periodically (e.g. every few minutes or hours). Renegotiation is how the new Session Key is transmitted from one side of the connection to the other side.

Forward Secrecy:

  • Without Forward Secrecy, if you take a packet trace, you can use the SSL Server’s Private Key to decrypt Session Keys in the packet trace, and use those decrypted Session Keys to decrypt the rest of the packet trace.
  • With Forward Secrecy, even if the hacker had access to the server’s Private Key, the Private Key cannot be used to decrypt the Session Key, and thus the packet trace cannot be decrypted.
  • DH vs RSA – Diffie-Hellman (DH) Key Exchange algorithm enables Forward Secrecy. RSA Key Exchange does not. ECDHE is the modern version of DH Key Exchange that is preferred by security professionals. To achieve Forward Secrecy (strongly recommended), prioritize ciphers that have ECDHE or DHE in their cipher names. Avoid RSA ciphers.
  • Troubleshooting – if DHE ciphers are used, then a network administrator cannot decrypt a packet trace. Citrix ADC has some packet trace options that can save the traffic without encryption (SSLPLAIN), or it can save the SSL Session Keys in a file separate from the packet trace. Wireshark can use the Session Keys file to decrypt the packet trace.

Certificates

Server Certificate – every Web Server that listens for SSL/TLS traffic must have a Server Certificate. Certificates are small text files that contain a variety of information including: the web server’s FQDN, the web server’s public key, the certificate’s expiration date, and a certificate signature created by a Certificate Authority.

  • Keys and certificates are different things – The public/private key pair, and the server certificate, are two different things. First, you create a public/private key pair. Then you create a certificate that contains the public key.
  • UNIX Key files and Certificate files – Citrix ADC is UNIX-based, which means that keys and certificates are stored in separate files.
  • Windows private keys – Windows stores the private key separately from the certificate, but the location of the private key is not easily reachable by a Windows administrator. When you double-click a certificate on Windows, at the bottom of the certificate window is a message indicating if Windows has a separate private key for that certificate. To get access to the private key, you export the certificate with private key to a .pfx file. The password-protected .pfx file contains both the certificate and the private key.

SSL Handshake and Certificate Download – during the initial SSL Handshake, the Server’s Certificate is downloaded to the SSL Client. The SSL Client extracts the web server’s public key from the downloaded server certificate.

Certificates provide a form of authentication – The SSL Client uses the server’s certificate to authenticate the SSL-enabled web server so that the SSL Client only sends confidential data to trusted web servers. There are several fields in the SSL Server’s certificate that clients use to verify web server authenticity. Each of these fields is detailed later in this section.

  • Subject and/or Subject Alternative Name must match the hostname entered in the browser’s address bar.
  • CA Signature – the server’s certificate must be signed a trusted Certificate Authority. SSL Clients have a mechanism for trusting particular Certificate Authorities.
  • Validity Dates – the certificate must not be expired.
  • Revocation – the certificate must not be revoked.

Types of certificates – there are different types of certificates for different use cases. All certificates are essentially the same, but some of the certificate fields control how a certificate can be used:

  • Server Certificates – when linked to a private key, these certificates enable encrypted HTTP.
  • Certificate Authority (CA) Certificates – used by a SSL client to verify the CA signatures contained within a Server Certificate.
  • Client Certificates – used by clients to authenticate the client machine or user to the web server. Requires a certificate and private key on the client side.
  • SAML Certificate – self-signed certificate exchanged to a different organization to authenticate SAML Messages (federation).
  • Code Signing Certificate – developers use this certificate to digitally sign the applications they developed.

Digital Signatures – Signatures are used to verify that a file has not been modified in any way. A Hashing Algorithm (e.g. SHA256) produces a hash of the file. A Private Key encrypts the hash. When a machine receives the signed file, the receiving machine generates its own hash of the file. Then it decrypts the file’s signature using the signer’s Public Key and compares the hash in the file with the hash that the receiving machine generated. If the computed hash matches the hash in the signature, then the file has not been modified.

  • The machine that received the file must have access to the Public Key that is paired with the Private Key that signed the file at the sender. These Public Keys are usually distributed through certificates.

Server Certificate Signature – Server certificates are digitally signed by a trusted third party, formally known as the Certificate Authority (CA). This third party verifies that the organization that produced the server certificate actually owns the server that is hosting the certificate.

  • Publicly-signed Certificates are not free – For public CAs, the owner of the server certificate pays the public CA to sign the server’s certificate.
  • CA uses the CA’s Private Key to sign the server certificate – The CA generates a hash of the server certificate and signs the hash using the CA’s Private Key.
  • Verify CA signature – The SSL Client extracts the Issuer field from the server certificate and matches the Issuer name with one of the CA certificates installed on the SSL Client machine. The SSL Client then extracts the public key from the locally installed CA certificate and uses that CA’s public key to verify the signature on the server certificate. If the hashes match, then the server certificate is “trusted”.

CA certs are installed on SSL clients –  CA’s pay Microsoft, Chrome, Mozilla, Apple, etc. to install their Root CA Certificates on client machines.

  • Out-of-band installation – Root CA Certificates are always installed out-of-band and are not delivered by the web server during the SSL Handshake. If a CA certificate is missing from the SSL Client machine, then the user must install it manually by using a local Certificates management console, or through some other administrator-controlled process (e.g. group policy).
  • Trust is defined by locally installed CA certificates – Any server certificate signed any of the CA certificates installed on a SSL Client machine are automatically trusted.
  • Stop trusting one CA – Sometimes a Certificate Authority is compromised, or doesn’t do a good enough job of verifying server certificate ownership. To stop trusting certificates signed by a bad CA, simply uninstall the CA’s certificate from the SSL Client machine.

Private Certificate Authority – instead of paying for a public certificate authority to sign your server certificates, you could easily build your own private Certificate Authority. Windows Servers have a built-in role called Certification Authority. Or you can use your Citrix ADC as a private certificate authority.

  • Private CA Root Certificate Installation – the Root CA certificate for the private certificate authority is not installed on client machines by default. Instead, the administrator of the client machines must distribute the private CA Root Certificate using group policy or some other out-of-band installation method.
  • Private CA-signed server certificates are commonly used on internal servers where administrators have full control of the client machines. But if any non-managed client machine needs to trust your private CA-signed server certificates, then it’s usually easier to purchase a public CA-signed server certificate because the public CA root certificates are already installed on all client machines.
  • Cannot purchase public CA-signed server certificates for non-routable DNS names – each server certificate contains the FQDN that users use to access the web server. If the server’s FQDN ends in one of the Internet DNS Top Level Domains (TLD), like .com, then you can pay a public CA to sign your certificate. However, if the FQDN ends in a private DNS suffix, like .local, then you cannot purchase a public CA signature and instead you must build your own private CA to sign the server certificate.

Self-signed certificate – Instead of using a third party CA’s private key to encrypt the certificate file hash, it’s also possible for a certificate to use its own key pair to sign its own certificate. In this case, the Issuer of the certificate and the Subject of the certificate are the same and this is called a Self-signed certificate. Most web browsers will not accept self-signed server certificates for SSL/TLS connections. But Self-signed certificates are useful for other purposes, including Root CA certificates, and SAML certificates.

  • Self-signed certificates and internally-signed certificates are two different things – If you build your own private Certificate Authority and use the private CA to sign your internal server certificates, then the internal server certificates are not self-signed, but rather they are “internally-signed” or “private-signed”. Self-signed certificates have the same value for Issuer and Subject. “private-signed” certificates have different values for Issuer and Subject because the Issuer is a private CA and not itself.

CA Chain – The server certificate can be signed by one CA certificate, or the server certificate can be signed by a chain of CA certificates.

  • Root CA Certificate – the top of the CA certificate chain is the Root CA certificate. The Root CA certificate is self signed. If the Root CA certificate is installed on a SSL Client machine, then all CA certificates that chain to the root are trusted.
  • Intermediate CA certificates – In the CA Signature Chain, between the Server Certificate and the Root CA Certificate, are Intermediate CA Certificates. The Root CA certificate almost never directly signs server certificates. Instead, the Root CA certificate signs an Intermediary or Issuing CA Certificate and the Issuing CA Certificate signs the server certificate.
  • Intermediate CA certificates are not installed on SSL client machines –  Instead, Intermediate CA certificates must be transmitted to the SSL Client from the SSL Server during the SSL Handshake.
    • If Intermediate CA certificate is not transmitted during SSL Handshake, then CA chain is broken – when the SSL Client receives the server certificate, it extracts the server certificate’s Issuer field and looks for a CA certificate that matches that Issuer name. Since the server certificate’s Issuer is an Intermediate CA certificate and not a Root CA certificate, and since intermediate CA certificates are not installed on the client machines, the client machine won’t find a matching CA certificate unless one was sent by the SSL server.
    • Link Intermediate CA Certificate to Server Certificate – On a Citrix ADC, you install the Server Certificate under the Server Certificates Node. You also install the Intermediate CA certificate under the CA Certificates node. Then you right-click the Server Certificate and Link it to the Intermediate CA Certificate. During the SSL Handshake, the Citrix ADC transmits both the server certificate and the intermediate CA certificate.
    • IIS and Intermediate CA certificates – On IIS, you simply install the Intermediate Certificate in the web server computer’s Intermediate CA certificate store. IIS (Windows) automatically knows which intermediate CA certificate goes with the server certificate and it transmits both during the SSL Handshake phase.
  • The Root CA certificate must never be transmitted by the SSL Server during the SSL Handshake – you might be tempted to install the self-signed CA root certificate on the Citrix ADC and then link it to the intermediate CA certificate. Don’t do that. Only the Intermediate CA certificates, not the Root, can be transmitted from the ADC. The Root CA certificate is already installed on the client machine through an out-of-band operation (e.g. included with the operating system). If the Root CA certificate could be transmitted by the SSL Server, then the entire third party trust model is broken.
    • If the root certificate is transmitted during the the SSL Handshake phase, then SSL Labs will report this as “Chain issues: Contains anchor”.

To create a certificate – The process to create a certificate is as follows:

  1. Create keyfile – Use OpenSSL or the Citrix ADC GUI to create an RSA public/private key pair file.

    • Keypairs created by OpenSSL must be converted to RSA format.
    • ECDHE ciphers and DHE ciphers use RSA keypairs.
  2. Create Certificate Signing Request (CSR) – Use OpenSSL or Citrix ADC GUI to create a Certificate Signing Request (CSR). The CSR contains the public key, and several other fields, including: server’s DNS name, and name of the Organization that owns the server.
  3. Send CSR to CA – Send the CSR to a Certificate Authority (CA) to get a CA signature. Public CAs usually charge a fee for this service.
  4. CA verifies ownership – The CA verifies that the Organization Name specified in the CSR actually owns the server’s DNS name.
    1. One method is for the CA to email somebody at the organization that owns the web server.
    2. More stringent verifications include background checks for the organization’s DUNS name. Higher verification usually requires a higher fee.
  5. CA signs the certificate – If owner verification is successful, then the CA signs the certificate and sends it back to the administrator. The CA can use a chained intermediate CA Certificate to sign your Server certificate.
  6. Complete certificate request – The administrator installs the signed server certificate and links it with the key file. In IIS, this is called “Complete Certificate Request”. In Citrix ADC, when installing a cert-key pair, you browse to both the signed certificate file, and the key file.
  7. Create a TCP/SSL 443 listener and bind the certificate to it – Configure the web server to use the certificate. In IIS, add a https binding to the Default Web Site and select the certificate. In Citrix ADC, create a SSL Virtual Server, and bind the certificate key-pair to it.

Certificate/key file storage on Citrix ADC– On Citrix ADC, certificate files and key files are stored in /nsconfig/ssl.

Certificate File Format – There are several certificate file formats: Base64, DER, and PFX.

  • Base64 is the default encoding for certificate files on UNIX/Linux systems, including Citrix ADC. This format is also known as PEM. Base64 files look like text files with the first line that says: “—–BEGIN CERTIFICATE—–”
  • DER Format – On Windows, if your certificate doesn’t have a private key associated with it, then you can save the certificate to a file in DER format. DER format looks like a binary file, not a text file.

    • Newer versions of ADC can automatically detect that a certificate file is in DER format.
    • Older versions of ADC require you to indicate that the certificate file is DER format instead of Base64.
  • PFX format – On Windows, if you export a certificate with private key, then both are stored in a password-protected file with .pfx extension. This file format is also known as PKCS#12.

    • Newer versions of Citrix ADC can directly import .pfx files.
    • Citrix ADC can also use OpenSSL to convert a .pfx file into a Base64 PEM file that contains both the certificate and the RSA key.

Private Keys should be encrypted – the key file that contains the Private Key should be encrypted, usually with a password. On Citrix ADC, when creating a key pair, you enable PEM Encoding and set it to 3DES (Triple DES) or AES 256 encryption. OpenSSL asks you to enter a permanent password to encrypt the private key. You will need this password whenever you install the certificate key pair.

  • When creating an RSA key file, specify PEM Encoding Algorithm and Passphrase – specifying a PEM Encoding Algorithm and Passphrase are optional. Password-protecting the .key file is recommended.
  • When converting a PFX file to PEM, encrypt the PEM private key – Specify a PEM encoding password when performing this conversion.
  • Hardware Security Module (HSM) – Hardware Security Modules (HSM) are physical devices that destroy their contents if there’s any attempt of physical compromise , which means they are the perfect place to store your private keys. The Citrix ADC FIPS appliances include a HSM module inside the FIPS appliance. Or, you can connect a Citrix ADC to a network-addressable HSM appliance. The HSM performs all private key operations so that the private key never leaves the HSM device.
  • Smart Card – Smart Cards require the user to enter a PIN to unlock the smart card to use the private key, similar to an HSM. Smart Cards are typically used with Client Certificates, which are detailed later.

Certificate Fields

Subject field – One of the fields in the Server Certificate is called Subject. Look for the CN= section of this field. CN means Common Name, which might be familiar to LDAP (e.g. Active Directory) administrators. The Common Name is the DNS name of the web server.

  • Public CAs require FQDNs, not short DNS names – Public CAs require that the Common Name of your Subject field be a FQDN and not a short DNS name (left part of the DNS name before the first dot). Internal web servers are frequently accessed using short DNS names instead of FQDNs. Certificates for short DNS names can only be acquired from a private CA.

Subject Alternative Names – Another related Certificate field is Subject Alternative Name (SAN). The Subject field (Common Name) only supports a single DNS name. Subject Alternative Name supports as many DNS names as desired.

  • Public CAs charge extra for each additional SAN Name. When you submit a CSR to a public CA, the public CA gives you an opportunity to enter more SAN Names. The more SAN Names you add, the higher the cost of the certificate.
  • CSRs ask for Common Name, not SAN names – When creating a CSR, put your server’s primary FQDN in the Common Name (Subject) field. When you submit the CSR to a Public CA, the Public CA will automatically copy your Common Name into the Subject Alternative Name field.
    • OpenSSL lets you include SAN Names in the CSR. However, most CAs ignore any SAN Names in the CSR.
  • Microsoft CA does not support SAN Names by default – Microsoft CA does not support SAN names by default. Microsoft CA will not copy the Common Name to the Subject Alternative Name. Search Google for instructions to enable Microsoft CA to accept manually entered SAN Names.

URL Hostname Matching against Server Certificate’s Subject and Subject Alternative Name (SAN) fields

  • User enters URL Hostname in browser address bar – User opens a browser and enters https://hostname in the browser’s address bar to connect to a web server. The hostname is extracted from the entered URL and then matched with the Common Name field or Subject Alternative Name field of the downloaded sever certificate. If the entered hostname doesn’t match the certificate’s Common Name or Subject Alternative Name field, then a certificate error is displayed. To avoid certificate errors, your server certificates must have a Subject Common Name or Subject Alternative Name that matches the DNS Names that users will use to browse to your SSL web server.
  • Server Name Indication (SNI) – If the web server is hosting multiple SSL websites on one IP address, which server certificate should be sent to the client so the client can do its URL host name matching? In newer versions of browsers (Windows XP is too old) and web servers, Server Name Indication (SNI) was added to the SSL handshake. The SSL Client now sends the URL hostname from the browser’s address bar to the web server so the web server can select a certificate to send back to the SSL Client.
  • Chrome only accepts Subject Alternative Names, not Common Name – Chrome recently started ignoring the Subject and Common Name fields of the server certificate and now instead only does hostname matching against the Subject Alternative Name (SAN) field of the server certificate.
  • SAN Names let one certificate match multiple FQDNs – You might have an SSL Server listening on several FQDNs. Instead of buying a separate certificate for each FQDN, purchase one certificate with multiple SAN Names.
    • If your web server is reachable at both company.com and www.company.com, then add both FQDNs to the SAN Names field of the server certificate.

Wildcard certificate – The Certificate Common Name can be a wildcard (e.g. *.company.com) instead of a single DNS name. This wildcard matches all FQDNs that end in .company.com.

  • The wildcard only matches one word and no periods to the left of .company.com. It will match www.company.com, but it will not match www.gslb.company.com, because there’s two words instead of one. It will also not match company.com because it requires one word where the * is located.
  • Wildcard certificates cost more from Public CAs than single name certificates and SAN certificates.
  • Wildcard certificates are less secure than single name certificates, because you typically use the same wildcard certificate on multiple web servers, and if the wildcard certificate on one of the servers is compromised, then all are compromised.
  • Public CAs will automatically copy the wildcard *.company.com into the Subject Alternative Name field. For Microsoft CA, you must manually specify *.company.com as a Subject Alternative Name, assuming you enabled Microsoft CA to accept Subject Alternative Names.

Validity Dates – Another field in the certificate is Valid to (expiration date). If the date is expired, then the client’s browser will show a certificate error. When you purchase a certificate, it’s only valid between 90 days and 3 years, with CAs charging more for longer terms.

  • Expiration Warning – Citrix ADM (Application Delivery Management) can alert you when a Citrix ADC certificate is about to expire. Public CAs will also remind you to renew it.
  • Renew with existing keys? – When renewing the certificate, you can create a new SSL key pair, or you can use the existing key pair. If you create a new key pair, then you need to create a new CSR and submit it to the CA. If you intend to use the existing keys, then simply download the updated certificate from the CA after paying for the later expiration date.
  • Let’s Encrypt issues certificates with 90 days expiration – Let’s Encrypt is a free public CA that is fully automated. Certificates issued from Let’s Encrypt expire 90 days after issuance. Shorter expiration periods are more secure than longer expiration periods. Because of the short expiration periods, you must fully automate the Let’s Encrypt CSR generation, CA signature, and certificate installation process.

Certificate Revocation – certificates can be revoked by a CA. The list of revoked certificates is stored at a CA-maintained URL. Inside each SSL certificate is a field called CRL Distribution Points, which contains the URL to the Certificate Revocation List (CRL). Client browsers will download the CRL to verify that the SSL server’s certificate has not been revoked. Revoking is usually necessary when the web server’s private key has been compromised.

  • CAs might revoke a certificate when Rekeying  – if you rekey a certificate, the certificate with the former keys might be revoked. This can be problematic for wildcard certificates that are installed on multiple machines, since you only have a limited time to replace all of them. Pay attention to the CA’s order form to determine how long before the prior certificate is revoked.
  • Online Certificate Status Protocol – An alternative form of revocation checking is Online Certificate Status Protocol. The address for the OCSP server can be found in the certificate’s Authority Information Access field.

SSL Ciphers

A Cipher is a collection of algorithms that dictate how session keys are created and how the bulk encryption is performed.

Cipher Suites are negotiated – During the SSL Handshake, the SSL Client and the SSL Server negotiate which cipher algorithms to use. A detailed explanation of ciphers would require advanced mathematics, but here are some talking points:

  • Recommended list of ciphers – Security professionals (e.g. OWASP, NIST) publish a list of the recommended, adequately secure, cipher suites. These ciphers are chosen because of their very low likelihood of being brute force decrypted within a reasonable amount of time.
  • Higher security means higher cost. For SSL, this means more CPU on both the web server (Citrix ADC), and SSL Client. You could go with high bit-size ciphers, but they require exponentially more hardware.
  • Each cipher suite is a combination of cipher technologies. There’s a cipher for key exchange. There’s a cipher for bulk encryption. And there’s a cipher for message authentication. So when somebody says “cipher”, they really mean a suite of ciphers.

Ephemeral keys and Forward Secrecy – ECDHE ciphers are ephemeral, meaning that if you took a network trace, and if you had a the web server’s private key, it still isn’t possible to decrypt the captured traffic. This is also called Forward Secrecy.

  • DHE = Ephemeral Diffie Hellman, which provides Forward Secrecy.
  • EC = Elliptical Curve, which is a formula that allows smaller key sizes, and thus faster computation.

Ciphers in priority order – The SSL server is configured with a list of supported cipher suites in priority order. The top cipher suite is preferred over lower cipher suites.

  • The highest common cipher between SSL Server and SSL Client is chosen – When the SSL Client starts an SSL connection to an SSL Server, the SSL Client transmits the list of cipher suites that the SSL Client supports. The SSL Server then chooses the highest matching cipher suite. If neither side supports any of the same cipher suites, then the SSL connection is rejected.

Citrix-recommended cipher suites – See Scoring an A+ at SSLlabs.com with Citrix NetScaler – Q2 2018 update for the list of cipher suites that Citrix currently recommends. Every SSL Virtual Server created on the Citrix ADC should be configured with this list of cipher suites in the order listed.

  • GCM ciphers seem to be preferred over CBC ciphers.
  • EC (Elliptical Curve) ciphers seem to be preferred over non-EC ciphers.
  • Ephemeral ciphers seem to be preferred over non-Ephemeral ciphers.
  • This list does not include TLS 1.3 ciphers so you’ll need to manually add the TLS 1.3 ciphers to the cipher group.

Client Certificates

Client Certificate – Another type of certificate is Client Certificate. This is a certificate with private key, just like a Server Certificate. Client Certificates are installed on client machines, and usually are not portable (the private key can’t be exported). Client machines use the Client Certificate to authenticate the client to web servers. This client certificate authentication can simply verify the presence of the certificate on a corporate managed device. Or the user’s username can be extracted from the client certificate and used to authenticate the user.

Client Private Key – The client certificate authentication process requires access to the paired client private key. If the paired client private key is not accessible, then the client certificate cannot be used for client authentication with the web server. The client private key can be installed on a particular machine (e.g. in the machine’s Trusted Platform Module), or the client private key can be portable (e.g. on a Smart Card).

  • Smart cards have a client certificate and private key installed on them.  Users enter a PIN number to unlock the smart card to use the client certificate’s private key. Smart Cards eliminate needing to enter a password to authenticate with a web server.
  • Virtual Smart Cards – There are also virtual smart cards, which use hardware features of the client device to protect the client certificate. The client’s TPM (Trusted Platform Module) encrypts the private key. If the client certificate were moved to a different device, then the new device’s TPM wouldn’t be able to decrypt the private key. Windows Hello for Business and Passport for Work are examples of this technology.

Device Certificates and User Certificates – some client certificates, called device certificates, are assigned to the machine to identify the compliance status of the machine. Other client certificates are assigned to the user so the user can use the user certificate to authenticate with web-based services.

  • Multi-factor authentication with user certificates – The user certificate can be the only authentication method (password-less), or the user certificate can be provided along with additional authentication material for multi-factor authentication.

Password-less authentication – Client Certificates are used extensively in “password-less” authentication scenarios. For example, your client device can be joined to a cloud-hosted device management service, like Azure Active Directory or Intune. Once enrolled, the cloud device management service pushes down a client certificate that is used for future authentications to the cloud service. The cloud device management service also pushes down security policies that might require the user to enter a PIN number or biometric authentication method to unlock the client certificate. Once unlocked, the client certificate can be used to authenticate the machine and/or user to cloud-based services.

Client Certificates for Machine Authentication – some companies want to restrict access to a web server from only company-managed machines. One method of ensuring that the device is company-managed is to push a client certificate (with private key) to the devices, and then require the device’s client certificate in addition to the user’s normal authentication credentials.

Citrix Federated Authentication Service (FAS) uses user certificates for VDA authentication – In a SAML authentication scenario (described later), Citrix VDA does not have access to the user’s password. The only other option to authenticate with Windows is using a user certificate, also called a smart card certificate. The Citrix FAS server automatically generates user certificates for each user that authenticates to StoreFront. The private keys for these user certificates are stored on the FAS server. When the user connects to the VDA, the VDA retrieves the user’s certificate and private key from the FAS server and uses the user certificate to perform client certificate authentication (smart card authentication) with the Active Directory Domain Controllers.

HTTP Authentication

Citrix ADC Authentication Overview

AAA is short for Authentication, authorization, and accounting. AAA is a generic term for performing authentication against remote authentication servers.

Authentication Policy Bind Points – Citrix ADC supports several authentication mechanisms at three different bind points:

  • Citrix Gateway Virtual Server
  • AAA Virtual Server
    • AAA Virtual Server is only available in Citrix ADC Advanced Edition (formerly known as Enterprise Edition) and Premium Edition (formerly know as Platinum Edition). ADC Standard Edition does not include AAA Virtual Servers.
  • Global – for authentication for management access

Load Balancing and AAA – Load Balancing Virtual Servers redirect users to a AAA Virtual Server to perform the authentication. After authentication, the user is redirected back to the Load Balancing Virtual Server.

Citrix Gateway and AAA – Citrix Gateway can use a AAA Virtual Server for nFactor authentication. Or you can bind classic authentication policies directly to the Gateway Virtual Server.

  • AAA licensing – AAA Virtual Server is only available in Citrix ADC Advanced Edition (formerly known as Enterprise Edition) and Premium Edition (formerly know as Platinum Edition). ADC Standard Edition does not include AAA Virtual Servers.

SSL/TLS – All ADC HTTP-based authentication methods require the client to be connected to the ADC using SSL/TLS protocol. If authentication collects credentials using an HTML Form, then the form submission is transferred to the ADC over the encrypted SSL/TLS connection.

nFactor – nFactor allows a series of authentication web forms and authentication policies to be chained together for almost limitless customization of the authentication process. nFactor can be configured on any AAA Virtual Server, including AAA Virtual Servers used by Citrix Gateway and Load Balancing.

  • New ADC authentication features are nFactor only – Citrix seems to be adding new authentication features only to the nFactor platform. For example, StoreFrontAuth, Native One-time Password (OTP), and Gateway Self-Service Password Reset (SSPR) require nFactor. These features are not available on pure Citrix Gateway without a AAA Virtual Server. Be mindful of the licensing requirement for AAA.
  • Endpoint Analysis Scans in nFactor – nFactor also supports Endpoint Analysis and Device Certificate authentication. These were formerly Gateway-only features. With nFactor, they can be used with Load Balancing authentication too.

Authentication Policy Syntax – On Citrix ADC, Authentication Policies can be created using Classic Syntax, or Default (Advanced) Syntax.

  • Classic Syntax authentication policies can be bound to all three bind points.
    • The expression ns_true is an example of Classic Syntax.
  • Default Syntax (Advanced Syntax) authentication policies cannot be bound to a Gateway Virtual Server. The only way for a Gateway to use Default Syntax authentication policies is through a AAA Virtual Server and nFactor authentication.
    • The expression true is an example of Default Syntax.
  • Classic Syntax deprecation – Citrix has announced that Classic Syntax authentication policies will be removed from future versions of Citrix ADC. It is not clear how this affects Citrix Gateway licensing since ADC Standard Edition does not include AAA or nFactor.

NSIP is Source IP for authentication – By default, Citrix ADC uses its NSIP (management IP) as the Source IP when communicating with authentication servers.

  • To use SNIP, load balance – You can force authentication to use a SNIP by load balancing the authentication servers, even if there’s only one authentication server. In this case, the NSIP connects to a VIP, which uses a SNIP to connect to the authentication server. In a network trace, you’ll see both the NSIP and the SNIP.

Back-end Single Sign-on – Once a user has been authenticated by Citrix ADC, ADC can usually perform Single Sign-on to the back-end resource (web page, Citrix StoreFront, etc.).

  • Different authentication methods for client and server – The authentication method that ADC uses to authenticate the user on the client side doesn’t have to match the authentication method that ADC uses for back-end Single Sign-on. For example, Citrix ADC can use LDAP+RADIUS on the client side, and convert it to Kerberos on the server side.

AAA Groups – some authentication methods support extraction of user group membership from the authentication server. If you run cat /tmp/aaad.debug during a user authentication, it should show you any groups that it extracted for the user. On ADC, you can add matching groups in three different places: System (global), AAA, and Gateway. The groups you add on ADC must have names that match exactly (case sensitive) with the group names that were extracted from the authentication server.

  • System Groups provide authorization to the ADC management console GUI. You bind Command Policies to the System Groups. Command Policies are collections of Regular Expressions that match permitted ADC CLI commands. For details, see LDAP Authentication for Management.
  • AAA Groups (not Gateway) provide authorization to back-end web servers and allow different Single Sign-on configurations for different AAA Groups.
  • Gateway AAA Groups provide different Gateway Policies for different AAA Groups. You can bind the following to each AAA Group: Gateway Session Policies, VPN Authorization Policies, VPN IP Pools, Traffic Policies for SSON to back-end servers, Intranet Applications for VPN Split Tunnel, etc. For details, see SSL VPN: AAA Groups.

Default Authentication Group – Many of the ADC Authentication Policies/Servers have a field called Default Authentication Group. If the user successfully authenticated with this authentication server, then the user is added to the Default Authentication Group. If you create a System Group, AAA Group, or Gateway AAA Group with the same case sensitive name that you specified in the Default Authentication Group field of authentication server, then you can bind policies that only apply to users that authenticated with a particular authentication server.

Citrix ADC Authentication Methods Summary

This section is just a summary of some of the available authentications on Citrix ADC. See later sections for detailed explanations of the most commonly used authentication methods.

Citrix StoreFront authentication methods are limited – Citrix StoreFront has native support for Domain Authentication, Kerberos (aka Domain Pass-though), and SAML. StoreFront’s SAML capabilities are limited. If you need any authentication beyond what StoreFront supports, then you need to offload StoreFront authentication to Citrix ADC and Citrix Gateway. RADIUS is a glaring omission from the list of supported StoreFront authentication protocols.

  • Single Sign-on (SSON) from Citrix Gateway to StoreFront – after the Citrix Gateway authenticates the user, the ADC can SSON to StoreFront so StoreFront doesn’t have to ask for authentication again.
  • Citrix Gateway Callback – for password-less SSON from ADC to StoreFront, StoreFront can initiate a back-channel connection from StoreFront to ADC to verify that the the ADC actually authenticated the user. This is called the Gateway Callback URL.
    • SmartAccess – The Gateway Callback URL is also used by StoreFront to get more information about the authentication context, which can later be used in Citrix Virtual Apps and Desktops (CVAD) SmartAccess configurations.

LDAP for Active Directory authentication – Citrix ADC supports LDAP protocol to authenticate with Domain Controllers.

  • LDAP vs Kerberos – LDAP is just one of the authentication protocols supported by Active Directory. Another common authentication mechanism is Kerberos. Kerberos and LDAP are completely different technologies.
  • HTML logon page – Users typically enter LDAP credentials in a HTML Form logon page generated by the Citrix ADC.
  • LDAP Protocol – Citrix ADC then uses LDAP protocol to transmit the entered credentials to a Domain Controller for verification. Ideally, LDAP Protocol should be encrypted using Domain Controller certificates.

RADIUS for multi-factor authentication – Citrix ADC supports RADIUS protocol to authenticate to multi-factor authentication products.

  • No Native SecurID support – Citrix ADC does not have native support for RSA SecurID so RADIUS must be used instead.
  • RADIUS is supported by almost every multi-factor authentication product – but RADIUS is usually not enabled on the product by default.
    • On-prem RADIUS servers – Cloud-hosted authentication products, like Duo and Azure MFA, require installation of an on-premises RADIUS server. Duo has a program called the Duo Proxy, which supports RADIUS. Azure MFA has a plug-in for Microsoft Network Policy Server, which is a RADIUS server.
  • RADIUS credentials can be collected by a HTML logon page – RADIUS credentials are typically a PIN number plus a passcode displayed on a smartphone. Citrix ADC uses the RADIUS protocol to transmit the entered credentials to an authentication server for verification.
  • RADIUS supports non-password authentication methods, like phone calls and text messaging. For these methods, the user does not enter anything in the RADIUS password field on the HTML logon page. Or, the Citrix ADC administrator can hide the RADIUS password field from the HTML logon page. Even if the field is hidden, Citrix ADC still contacts the RADIUS server to perform the password-less authentication.
  • RADIUS Challenge – RADIUS servers can send back a prompt (RADIUS Challenge) asking the user to provide more authentication information. Some send back an HTML form asking the user what kind of authentication to perform – phone call, SMS, phone notification, etc. Citrix ADC will happily display the RADIUS Challenge to the user.
    • HTML-based RADIUS Challenges might not work in Citrix Receiver or Citrix Workspace app.

RADIUS is typically combined with LDAP.

  • A single HTML logon page can ask the user to enter both the AD password and the two-factor passcode at the same time.
    • Citrix ADC uses LDAP to authenticate the user into Active Directory.
    • Citrix ADC uses RADIUS to verify the two-factor passcodes.
  • Citrix Receiver and Citrix Workspace app require special configuration to support RADIUS as a second password field. Specifically, the LDAP password field and the RADIUS password field must be swapped.

SAML offloads authentication from the website or ADC to a separate Identity Provider (IdP) – The web site (and ADC) the user is trying to access is called the Service Provider (SP), which redirects the user to an Identity Provider (IdP) to perform the offloaded authentication. The SP and IdP can be different organizations.

  • Identity Providers usually require multi-factor authentication.
  • The user’s password stays at the Identity Provider. The Service Provider never sees the user’s password.
  • Trust between the Identity Provider and the Service Provider is provided by certificates. The two entities share certificates with each other to verify each other’s identity using digital signatures.

Kerberos is another method of authenticating with Active Directory.

  • Kerberos authentication and LDAP authentication are completely different authentication methods.
  • Kerberos tickets – Kerberos authentication uses tickets that are provided by a Domain Controller. The client machine must be able to communicate with a Domain Controller to get the tickets. This means Kerberos usually doesn’t work on the Internet, at least not without a VPN connection.
  • If Citrix ADC uses Kerberos to Single Sign-on to the back-end web servers, then Citrix ADC needs connectivity to internal DNS and internal Domain Controllers to get the tickets.

OAUTH allows a user to delegate service access to a separate program. The program can then access a different Service (HTTP API) as the user but without the user being present. This is a form of delegation.

  • OAUTH is used extensively in cloud services. If you see Google, Twitter, Facebook, or Azure Active Directory asking you to authorize a program to access your Profile information, then that’s OAUTH.
    • Azure Active Directory is primarily an OAUTH directory. It also supports SAML.
    • Azure Active Directory does not support Kerberos or LDAP.
  • Consent Form – If a program needs to access a website on your behalf, then the program will redirect you to the website’s OAUTH Authorization Server to authorize the delegation by presenting you with a Consent Form. The Consent Form indicates the permissions that the program will have in your account. Once you approve the access, the program can then access your account directly without needing to ask you for permission again.
    • Access Token – The OAuth Authorization Server returns an Access Token to the program, which can then be used by the program to authenticate to HTTP-based APIs. The program automatically renews the Access Token periodically by asking to OAUTH Authorization Server to refresh the Access Token.
    • Revoke Access Token – A user can revoke a program’s Access Token so the program can no longer access the user’s account.
  • OpenID Connect is an authentication mechanism built on top of OAUTH where the goal is to get an ID Token instead of an Access Token.
    • The ID Token makes OAUTH operate more like SAML and can be used in place of SAML.
    • JWT instead of XML – The OpenID ID Token is a signed JSON Web Token (JWT), instead of an XML document that’s used in SAML.
  • Book on OAuth – For an excellent book on OAuth and OpenID Connect, see OAuth 2 in Action.

StoreFrontAuth delegates Active Directory authentication to an internal Citrix StoreFront server. StoreFront servers are usually domain-joined so it’s easier for StoreFront to perform the domain authentication. With StoreFrontAuth, you no longer need to perform LDAP authentication on the Citrix ADC. However, since StoreFront doesn’t support RADIUS, you’ll still need the ADC to perform RADIUS authentication.

  • StoreFrontAuth requires the ADC appliance to be licensed for nFactor authentication.

Citrix ADC Native OTP (one-time passwords) – instead of purchasing a multi-factor authentication product, Citrix ADC has native support for two-factor passcode authentication using smart phone apps like Google Authenticator.

  • ADC Native OTP requires Citrix ADC Advanced Edition (formerly know as Enterprise Edition) because it relies on nFactor.
  • ADC Native OTP stores client secrets in an Active Directory user attribute.
  • ADC Native OTP has security challenges with device registration. For example, access to the device registration web page only requires single-factor authentication.

LDAP (Lightweight Directory Access Protocol)

LDAP authentication process:

  1. HTML Form to gather credentials – Citrix ADC prompts user to enter a username and password, typically from an ADC-generated HTML Form.
  2. Connect to LDAP Server – Citrix ADC connects to the LDAP Server on TCP 389 or TCP 636, depending on if encryption is enabled or not.
  3. Citrix ADC logs into LDAP using a Bind account. This LDAP Bind account is an Active Directory service account whose password never expires. The only permissions the Bind account needs is to be able to search the LDAP directory. Domain Users group usually has this permission and thus it does not need Domain Admins permission.
  4. Citrix ADC sends an LDAP Query to the LDAP Server. The LDAP Query asks the LDAP Server to find the username that was entered in step 1. An LDAP Query is like a SQL Query. The LDAP Server finds the user somewhere in the directory tree and returns the user’s full Distinguished Name (DN), which is the full path to the user’s account in the directory.
  5. Login as user’s DN – Citrix ADC reconnects to the LDAP Server but this time logs in as the user’s DN (from step 4), and the user’s password (from step 1).
  6. Extract attributes – After authentication, Citrix ADC can be configured to extract attributes from the user’s LDAP account. A common configuration is to extract the user’s group membership. Another is to get the user’s userPrincipalName so it can be used during Single Sign-on to back-end web servers.

Password expiration requires LDAP encryption – If the user’s password has expired, then Citrix ADC can prompt the user to change the password. However, the user’s password can only be changed if the LDAP connection is encrypted, which means certificates must be installed on the LDAP servers (Active Directory Domain Controllers).

  • Password expiration reminders – Citrix ADC generally does not inform the user how long before the user’s password expires.
    • Citrix Gateway 12.1 can show reminder of password expiration in the RfWebUI Portal Theme when connecting to the Citrix Gateway’s built-in portal using Clientless Access.
    • StoreFront through Citrix Gateway does not show a reminder of user’s password expiration.
    • If you configure the VPN Home Page to something other than the built-in portal, then the user will not see any ADC-provided password expiration reminders.
  • Domain Controller certificates – The easy way to install certificates on domain controllers is to build a Microsoft Certification Authority in Enterprise Mode. Once the CA server is online, the Domain Controllers will auto-generate their own domain controller certificates.

LDAP Communication Protocols:

  • Clear text LDAP connects to the LDAP Server on TCP 389.
  • Two encrypted LDAP protocols – If the LDAP server has a certificate, then you can use one of two different encrypted protocols to connect to the LDAP Server.
    • Secure LDAP (LDAPS) – LDAPS is a different port number than LDAP, just like HTTPS is a different port number than HTTP. LDAPS is typically TCP 636 to the LDAP Server.
      • LDAPS is also called LDAP over SSL/TLS.
    • LDAP Start TLS – LDAP Start TLS starts as a clear text connection to the LDAP Server on TCP 389. Then both sides of the connection negotiate encryption parameters, and switch to encrypted communication on TCP 389.
      • Don’t confuse Start TLS with SSL/TLS. SSL/TLS (LDAPS) requires negotiated encryption at the start of the connection. Start TLS doesn’t start encryption until the clear text connection is established. To force LDAP to be encrypted, it’s better to use LDAPS instead of Start TLS.

The LDAP Server configuration on Citrix ADC has some interesting fields:

  • Server Logon Name Attribute is the name of the LDAP Attribute that contains the user name that was entered by the user in the HTML Logon Form. This attribute is typically set to sAMAccountName, which is the short user name. For multi-domain scenarios, you can change it to userPrincipalName, which has values that look like email address. If it’s set to userPrincipalName, then users need to enter their userPrincipalName in the ADC HTML Logon Page. Karim Buzdar at samAccountName Vs userPrincipalName explains the difference between the two.
  • SSO Name Attribute is the name of the LDAP attribute that Citrix ADC extracts from LDAP and then uses as the username when performing Single Sign-on (SSON) to back-end web servers (e.g. Citrix StoreFront). For multiple Active Directory domains and SSON to Citrix StoreFront, this field can be set to userPrincipalName to simplify how domain names are transmitted to StoreFront. For more details, see LDAP Authentication: Multiple Domains – UPN Method.
  • Search Filter controls the LDAP Query that is sent during LDAP authentication. A common usage of the LDAP Search Filter is to only return users that are members of a specific AD Group. For example, you can limit management access to ADC to only members of an ADC Administrator group. See LDAP Authentication for Management

Multiple Active Directory domains – Citrix ADC is based on UNIX, which means it does not understand Active Directory domains. Configuring ADC to handle multiple domains isn’t too difficult, but it’s more challenging to send the domain name when performing Single Sign-on to back-end web servers like Citrix StoreFront. For more details, see LDAP Authentication: Multiple Domains.

RADIUS (Remote Authentication Dial-In User Service)

RADIUS Client – RADIUS will not work unless you ask the RADIUS administrator to add Citrix ADC NSIP (or SNIP if load balancing) as a RADIUS Client. Ask the RADIUS server administrator to add the ADC NSIP and SNIP as RADIUS Clients.

  • Secret key – The RADIUS administrator then gives you the secret key that was configured for the RADIUS Client. You enter this secret key in Citrix ADC when configuring RADIUS authentication.

RADIUS authentication process:

  1. HTML Form to gather credentials – Citrix ADC prompts the user to enter username and passcode, typically from an ADC-generated HTML Form.
  2. Send login request to RADIUS server – Citrix ADC sends a login request (Access-Request) to the RADIUS Server on UDP 1812. Since it’s UDP, there’s no acknowledgment from the Server.
    1. Passcode encryption using shared secret – The user’s passcode in the RADIUS packet is encrypted using the RADIUS Client’s shared secret key that is configured on the Citrix ADC and RADIUS Server. The secret key entered on Citrix ADC must match the secret key configured on the RADIUS Server. Each RADIUS Client usually has a different secret key.
    2. RADIUS Attributes – The RADIUS Client (Citrix ADC) adds RADIUS attributes to the packet to help the RADIUS Server identify how the user is connecting. These attributes include: time of day, client IP, etc.
  3. RADIUS Server:
    1. RADIUS Clients configured on RADIUS Server – The RADIUS Server first verifies that the RADIUS Client (Citrix ADC) is authorized to perform authentication. The NAS IP (Citrix ADC Source IP) of the RADIUS Access-Request packet is compared to the list of RADIUS Clients configured on the RADIUS Server. If there’s no match, RADIUS does not respond.
    2. Shared secret – The RADIUS server finds the RADIUS Client and looks up the shared secret key. The secret key decrypts the passcode in the RADIUS Access-Request packet.
    3. Verify RADIUS Attributes – RADIUS Server uses the RADIUS Attributes in the Access-Request packet to determine if authentication should be allowed or not.
    4. Authenticate the user – RADIUS authenticates the user. Most RADIUS Server products have a local database of usernames and passwords. Some can authenticate with other authentication providers, like Active Directory.
    5. Access-Accept and Attributes – RADIUS sends back an Access-Accept message. This response message can include RADIUS Attributes, like a user’s group membership.
  4. RADIUS Challenge – RADIUS Servers can also send back an Access-Challenge, which asks the user for more information. Citrix ADC displays the RADIUS-provided Challenge message to the user, and sends back to the RADIUS Server whatever the user entered.
    1. SMS authentication uses RADIUS Challenge. The RADIUS server might send a SMS passcode to a user’s phone using SMS. Then RADIUS Challenge prompts the user to enter the SMS passcode.
  5. Extract RADIUS Attributes – Citrix ADC can be configured to extract the returned RADIUS Attributes and use them for authorization (e.g. AAA Groups).

SAML (Security Assertion Markup Language)

SAML uses HTTP Redirects to perform its authentication process. This means that HTTP Clients that don’t support Redirects (e.g. Citrix Receiver) won’t work with SAML.

SAML SP – The resource (webpage) the user is trying to access is called the SAML SP (Service Provider). No passwords are stored or accessible here.

SAML IdP– The authentication provider is called the SAML IdP (Identity Provider). This is where the usernames and passwords are stored and verified.

SAML SP Authentication Process:

  1. User tries to access a Citrix ADC VIP (Citrix Gateway or AAA) that is configured for SAML SP Authentication.
    1. Citrix ADC creates a SAML Authentication Request and signs it using a certificate (with private key) on the ADC.
    2. Citrix ADC sends to the user’s browser the SAML Authentication Request, and a HTTP Redirect (301) that tells the user’s browser to go to the SAML IdP’s authentication Sign-on URL (SSO URL).
  2. The user’s browser redirects to the IdP’s Sign-on URL and gives it the SAML Authentication Request that was provided by the Citrix ADC.
    1. The SAML IdP verifies that the SAML Authentication Request was signed by the Citrix ADC’s certificate.
    2. The SAML IdP authenticates the user. This can be a web page that asks for multi-factor authentication. Or it can be Kerberos Single Sign-on. It can be pretty much anything.
    3. The SAML IdP creates a SAML Assertion containing SAML Claims (Attributes). At least one of the attributes is Name ID, which usually matches the user’s email address. The SAML IdP can be configured to send additional attributes (e.g. group membership).
    4. The SAML IdP signs the SAML Assertion using its IdP certificate (with private key).
    5. The SAML IdP sends the SAML Asseration to the user’s browser and asks the user’s browser to Redirect (301) back to the SAML SP’s Assertion Consumer Service (ACS) URL, which is different from the original URL that the user requested in step 1.
  3. The user’s browser redirects to the ACS URL and submits the SAML Assertion.
    1. The SAML SP verifies that the SAML Token was signed by the SAML IdP’s certificate.
    2. The SAML SP extracts the Name ID (email address) from the SAML Assertion. Note that the SAML SP does not have the user’s password; it only has the user’s email address.
    3. The SAML SP sends back to the user’s browser a cookie that indicates that the user has now been authenticated.
    4. The SAML SP sends back to the user’s browser a 301 Redirect, which redirects the browser to the original web page that the user was trying to access in step 1.
  4. The user’s browser submits the cookie to the website. The website uses the cookie to recognize that the user has already been authenticated, and lets the user in.

Multiple SAML SPs to one SAML IdP – The SAML IdP could support authentication requests from many different SAML SPs, so the SAML IdP needs some method of determining which SAML SP sent the SAML Authentication Request. One method is to have a unique Sign On URL for each SAML SP. Another method is to require the SAML SP to include an Issuer Name in the SAML Authentication Request. In either case, the SAML IdP looks up the SAML SP’s information to find the SAML SP’s certificate (without private key), and other SP-specific information.

SAML Certificates:

  • SP Certificate – Citrix ADC uses a certificate to sign the SAML Authentication Request. This Citrix ADC certificate must be copied to the IdP.
  • IdP Certificate – The IdP uses a certificate to sign the SAML Assertion. The IdP certificate must be installed on the Citrix ADC.

SAML Configuration is usually performed first on the IdP – at the IdP, you add a Relying Party or Service Provider.

  • Provide the following information for the Server Provider (ADC)
    • Service Provider Assertion Consumer Service (ACS) URL – for Citrix Gateway, the URL ends in /cgi/samlauth
    • Service Provider Entity ID – to identify the service provider – configure it identically on both the IdP and on the ADC
    • IdP attribute (e.g. email address) that you want to send back in the Name ID claim
  • Download the IdP’s certificate and import it to the ADC
  • Copy the IdP’s Sign On URL and configure it on the ADC

Shadow Accounts – The SAML IdP sends the user’s email address to the SAML SP. The SAML SP has its own directory it uses to authorize users to SP resources. The email address provided by the SAML IdP is matched with a user account at the SAML SP’s directory. Even though the user’s password is never seen by the SAML SP, you still need to create user accounts for each user at the SAML SP. These SAML SP user accounts can have fake passwords. The SAML SP user accounts are sometimes called shadow accounts. The shadow accounts are assigned permissions to SP resources, like Citrix Virtual Apps and Desktops (CVAD) published applications.

  • Shadow Account userPrincipalNames – If the SAML SP relies on Active Directory for permissions, then the local AD shadow accounts must have a userPrincipalName that matches the email address claim that came from the SAML IdP. You might have to add custom DNS suffixes to your Active Directory forest to make the UPNs match.
  • Citrix Virtual Apps and Desktops (CVAD) is an example Service Provider that relies on Active Directory.

SAML and lack of user password – Not having access to passwords limits the back-end Single Sign-on authentication options at the SAML SP. Without a password, you can’t authenticate to Active Directory using LDAP or NTLM.

  • Kerberos Constrained Delegation (KCD) and Citrix VDA – Citrix ADC supports Kerberos Constrained Delegation (KCD), which means ADC can request Kerberos tickets from a Domain Controller on behalf of another user. KCD does not need access to the user’s password. However, Citrix Virtual Apps and Desktops (CVAD) does not support Kerberos tickets for VDA authentication.
  • Smart Card Logon to Citrix VDA – Instead of Kerberos tickets, Citrix VDA supports authentication using user certificates (smart card certificates) generated by Citrix Federated Authentication Service (FAS). FAS generates certificates for local Active Directory shadow accounts whose UPN matches the email addresses provided by the SAML IdP.

Kerberos

Kerberos authentication process (simplified):

  1. User tries to access a web page that is configured with Negotiate authentication.
  2. To authenticate to the web page, the user must provide a Kerberos Service ticket. The Kerberos Service ticket is requested from a Domain Controller.
    1. The Kerberos Service ticket is limited to the specific Service that the user is trying to access. In Kerberos parlance, the resource the user is trying to access is called the Service Principal Name (SPN). User asks a Domain Controller to give it a ticket for the SPN.
    2. Web Site SPNs are usually named something like HTTP/www.company.com. It looks like a URL, but actually it’s not. There’s only one slash, and there’s no colon. The text before the slash is the service type. The text after the slash is the DNS name of the server running the service that the user is trying to access.
  3. If the user has not already been authenticated with a Domain Controller, then the Domain Controller will prompt the user for username and password.
    1. The Domain Controller returns a Ticket Granting Ticket (TGT).
  4. The user presents the TGT to a Domain Controller and asks for a Service Ticket for the Target SPN. The Domain Controller returns a Service Ticket.
  5. The user presents the Service Ticket to the web page the user originally tried to access in step 1. The web page verifies the ticket and lets the user in.

The Service and the Domain Controller do not communicate directly with each other. Instead, the Kerberos Client talks to both of them to get and exchange Tickets.

Kerberos Delegation – The Kerberos Service Ticket only works with the Service listed in the Ticket. If that Service needs to talk to another Service on the user’s behalf, this is called Delegation. By default, Kerberos will not allow this Delegation. You can selectively enable Delegation by configuring Kerberos Constrained Delegation in Active Directory.

  • In Active Directory Users & Computers, edit the AD Computer Account for the First Service. On the Delegation tab, specify the Second Service. This allows the first Service to delegate user credentials to the Second Service. Delegation will not be allowed from the First Service to any other Service.

Kerberos Impersonation – If Citrix ADC has the user’s password (maybe from LDAP authentication), then Citrix ADC can simply use those credentials to request a Kerberos Service Ticket for the user from a Domain Controller. This is called Kerberos Impersonation.

Kerberos Constrained Delegation – If the Citrix ADC does not have the user’s password, then Citrix ADC uses its own AD service account to request a Kerberos Service Ticket for the back-end service. The service account then delegates the user’s account to the back-end service. In other words, this is Kerberos Constrained Delegation. On Citrix ADC , the service account is called a KCD Account.

  • The KCD Account is just a regular user account in AD.
  • Use setspn.exe to assign a Kerberos SPN to the user account. This action unlocks the Delegation tab in Active Directory Users & Computers.
  • Then use Active Directory Users & Computers to authorize Kerberos Delegation to back-end Services.

Negotiate – Kerberos and NTLM – Web Servers are configured with an authentication protocol called Negotiate (SPNEGO). This means Web Servers will prefer that users login using Kerberos Tickets. If the client machine is not able to provide a Kerberos ticket (usually because the client machine can’t communicate with a Domain Controller), then the Web Sever will instead try to do NTLM authentication.

  • NTLM is a challenge-based authentication method. NTLM sends a challenge to the client, and the client uses the user’s Active Directory password to encrypt the challenge. The web server then verifies the encrypted challenge with a Domain Controller.
  • Negotiate on client-side with NTLM Web Server fallback – Citrix ADC appliances can use Negotiate authentication protocol on the client side (AAA or Citrix Gateway). Negotiate will prefer Kerberos tickets. If Kerberos tickets are not available, then Negotiate can use NTLM as a fallback mechanism. In the NTLM scenario, Citrix ADC can be configured to connect to a domain-joined web server for the NTLM challenge process. By using a separate web server for the NTLM challenge, there’s no need to join the Citrix ADC to the domain.

HTTP

URLs

HTTP URL format: e.g. https://www.corp.com:444/path/page.html?a=1&key=value

  • https:// = the scheme. Essentially, it’s the protocol the browser will use to access the web server. Either http (clear-text) or https (SSL/TLS).
  • www.corp.com = the hostname. It’s the DNS name that the browser will resolve to an IP address. The browser then connects to the IP address using the specified protocol.
  • :444 = port number. If not specified, then it defaults to port 80 or port 443, depending on the scheme. Specifying the port number lets you connect to a non-standard port number, but firewalls might not allow it.
  • /path/page.html = the path to the file that the Browser is requesting.
  • ?a=1&key=value = query parameters to the file. The query clause beings with a ? immediately following the file name. Multiple parameters (key=value pairs) are separated by &. Query parameters are a method for the HTTP Client to upload a small amount of data to the Web Server. There can be many query parameters, or just one parameter.
    • An alternative to query parameters is to put the uploaded data in the body of an HTTP POST request.

URLs must be safe encoded (Percent encoded), meaning special characters are replaced by numeric codes (e.g. # is replaced by %23). See https://en.m.wikipedia.org/wiki/Percent-encoding.

HTTP Methods – HTTP supports several HTTP methods, with the most common being GET, POST, PUT, and DELETE. There are also less common HTTP methods like OPTIONS and CONNECT. Web Browsers typically only use GET and POST in their HTTP Requests. The other HTTP Methods are used by REST APIs.

  • GET method retrieves (downloads) a file.
    • Parameters to the GET request are added to the end of the URL in the Query section.
    • HTTP Request Headers also affect how the file is retrieved.
  • POST method uploads data to a web server (web application). The POST method includes a path to a web server script file that will process the upload. The HTTP Body of a POST Method usually contains one of the following;
    • HTML Form field data – user fills out a form and clicks Submit. This causes the browser to send a POST Request with the Body containing each of the HTML Form field names and the values entered by the user. The format of the POST Body is similar to field1name=value&field2name=value. Web Servers extract the field names and their values and saves them as variables that the web server scripts can access.
    • JSON or XML file upload – these JSON or XML files are generated by scripts or programs. The web server receives the JSON or XML files and does something programmatic with them.
    • Raw file upload – typically a full file that needs to be saved somewhere on the web server.
  • HTTP-based REST APIs use all four of the common HTTP Methods for the following purposes:
    • GET method retrieves an object in JSON or XML format. The arguments for the retrieval of the object (or objects) are specified in a JSON or XML document included in the body of the HTTP Request.
    • POST method creates a new object. The POST method path specifies the name of the object that needs to be created. The arguments for the new object are specified in a JSON or XML document included in the body of the HTTP Request.
    • PUT method modifies an existing object. The PUT method path specifies which object needs to be modified. The arguments for the modified object are specified in a JSON or XML document included in the body of the HTTP Request.
    • DELETE method deletes an existing object. The DELETE method path specifies which object needs to be deleted. The arguments for the object deletion operation are specified in a JSON or XML document included in the body of the HTTP Request.

HOST Header – web browsers insert a HTTP header named Host into the HTTP Request Packet. The value of this Host header is whatever hostname the user typed into the browser’s address bar. It’s the part of the URL after the scheme (http://), and before the port number (:81) or path (/).

  • Web Servers use the Host Header to serve multiple websites on one IP address – Each hosted website has a different Host Header value configured. The web server matches the Host header in the HTTP Request packet with the website’s configured Host Header value and serves content from the matching website.
    • In IIS, if you edit the port number bindings for a website, there’s a field to enter a host name. If you enter a host name value in this field, then the website can only be accessed if the same value is in the HTTP Request’s Host header. If you try to connect to the website by entering its IP address into your browser’s address bar, then you won’t see the website because the Host header won’t match.
  • Citrix ADC Load Balancing Monitors do not include the Host Header by default. If the Web Server requires the Host Header, then you must modify the Citrix ADC Monitor configuration to specify the Host header.

HTTP Body vs HTML Body – HTTP Body and HTML Body are completely different.

  • An HTML file contains an HTML Head section and an HTML Body section. But these are just sections in one HTML file.
  • An HTTP Response Body contains an entire HTML file. Or an HTTP Body can contain non-HTML files or data. HTML is just one of the file types that an HTTP Body can transport.

For a detailed explanation of the HTTP Protocol including the various HTTP headers, see the book named HTTP: The Definitive Guide. This book was published years ago but is still relevant today.

WebSocket – WebSocket enables a client machine and a server machine to use HTTP to establish a long-lived, two-way (bidirectional) TCP communications channel. WebSocket is initiated from the client machine, so you don’t have to open any firewall ports. The client machine sends an HTTP Request to a WebSocket server asking the WebSocket server to upgrade the HTTP Connection to a WebSocket connection. After the connection upgrade, HTTP is no longer needed, and the two machines can transmit anything across the WebSocket connection. The bidirectional aspect of WebSocket allows a server to send packets to the client machine without having to wait for a request to come from the client. One of the main purposes of WebSocket is to bypass inbound firewall restrictions.

  • HTTP and WebSocket – Not all HTTP servers support WebSocket. WebSocket is not HTTP. HTTP is only used to setup the WebSocket connection. Once WebSocket is established, then there’s no more HTTP. WebSocket runs on the same port numbers as HTTP, usually SSL/TLS port 443.
  • WebSocket and Citrix Cloud Connector – Citrix Cloud Connector establishes a WebSocket connection with Azure Service Bus. Citrix Cloud then uses the Azure Service Bus connection to send commands to the on-premises Citrix Cloud Connector machines.
  • WebSocket and Citrix Workspace app for HTML5 – if a user does not have Workspace app installed on the local machine, then the user can instead use a “light” workspace app, which means HTML5. When the user launches an app from StoreFront, the “light” client is downloaded as JavaScript that initiates a WebSocket connection with Citrix Gateway. Citrix Gateway then creates an ICA connection to the VDA machine.

Cookies

Client-side Data Storage – Web Servers sometimes need to store small pieces of data in a user’s web browser. The user’s browser is then required to send the data back to the web server with every HTTP Request. Cookies facilitate this small data storage.

Set-Cookie – Web Servers add a Set-Cookie header to the HTTP Response. This Response Header contains a list of Cookie Names and Cookie Values.

Cookies are linked to domains – The Web Browser stores the Cookies in a place that is associated with the DNS name (host name) that was used to access the web site. The next time the user submits an HTTP Request to that DNS name, all Cookies associated with that host name are sent in the HTTP Request using the Cookie HTTP Request header.

  • Notice that the two headers have different names. HTTP Response has a Set-Cookie header, while HTTP Request has a Cookie header.

Cookie security – Cookies from other domains (other DNS names, other web servers) are not sent. Cookies usually contain sensitive data (e.g. session IDs) and must not be sent to the wrong web server. Hackers will try to steal Cookies so they can impersonate the user.

Cookie lifetimes are either Session Cookies, or Persistent Cookies. Session Cookies are stored in the browser’s memory and are deleted when the browser is closed. Persistent Cookies are stored on disk and available the next time the browser is launched.

  • Expiration date/time – Persistent Cookies sent from the Web Server come with an expiration date/time. This can be an absolute time, or a relative time.

Citrix ADC Cookie for Load Balancing persistence – Citrix ADC can use a Cookie to maintain load balancing persistence. The name of the Cookie is configurable. The Cookie lifetime can be Session or Persistent. The Cookie’s value specifies the name of the Load Balancing Service (web server) that the user’s browser last accessed so the same Service can be used in the next connection.

Web Server Sessions

Web Server Sessions preserve user data for a period of time – When users log into a web site, or if the data entered by a user (e.g. shopping cart) needs to be preserved for a period of time, then a Web Server Session needs to be created for each user.

Web Server Sessions are longer than TCP Connections – Web Server Sessions live much longer than a single TCP Connection, so TCP Connections cannot delineate a session boundary.

Each HTTP Request is singular – There’s nothing built into HTTP to link one HTTP Request to another HTTP Request. Various fields in the HTTP Request can be used to simulate a Web Server Session, but technically, each HTTP Request is completely separate from other HTTP Requests, even if they are from the same user/client.

Server-side Session data, and Client-side Session ID – Web Server Sessions have two components – server-side session data, and some kind of client-side indicator so the web server can link multiple HTTP Requests to the same server-side session.

A Cookie stores the Session ID – On the client-side, a session identifier is usually stored in a Cookie. Every HTTP Request performed by the client includes the Cookie, so the web server can easily associate all of these HTTP Requests with a Server-side session.

Server-side data storage – On the server-side, session data can be stored in several places:

  • Memory of one web server – this method is the easiest, but requires load balancing persistence
  • Multiple web servers accessing a shared memory cache (e.g. Redis)
  • Shared Database – each load balanced web server can pull session data from the database. This is typically slower than memory caches.

Load Balancing Persistence and Web Server Sessions – some web servers store session data on the same web server the user initially connected to. If the user connects to a different web server, then the old session data can’t be retrieved, thus causing a new session. When load balancing multiple identical web servers, to ensure the user always connects to the same web server that was initially chosen by the user, configure Persistence on the load balancer.

Persistence Methods – When the user first connects to a Load Balancing VIP, Citrix ADC uses its load balancing algorithm to select a web server. Citrix ADC then needs to store the chosen server’s identifier somewhere. Here are common storage methods:

  • Cookie – the chosen server’s identifier is saved on the client in a Cookie. The client includes the ADC persistence Cookie in the next HTTP request, which lets Citrix ADC send the next HTTP Request to the same web server as before. Pros/Cons:
    • No memory consumption on Citrix ADC
    • Cookie can expire when the user’s browser is closed
    • Each client gets a different Cookie, even if multiple clients are behind a common proxy.
    • However, not all web clients support Cookies.
  • Source IP – Citrix ADC records the client’s Source IP into its memory along with the web server it chose using its load balancing algorithm. Pros/Cons:
    • Uses Citrix ADC Memory
    • If multiple clients are behind a proxy (or common outgoing NAT), then all of these clients go to the same web server. That’s because all of them appear to be coming from one IP address. The same is true for all clients connecting through one Citrix Gateway.
    • Works with all web clients.
  • Rule-based persistence – use a Citrix ADC Policy Expression to extract a portion of the HTTP Request and use that for persistence. Ultimately, it works the same as Source IP, but it helps for proxy scenarios if the proxy includes the Real Client IP in one of the HTTP Request Headers (e.g. X-Forwarded-For).
  • Server Identifier – the HTTP Response from a web server instructs the web client to append a Server ID to every URL request. The Citrix ADC can match the Server ID in the URL with the web server. Citrix Endpoint Management (XenMobile) uses this method.

Authentication and Cookie Security – If a web site requires authentication, it would be annoying if the user had to login again with every HTTP Request. Instead, most authenticated web sites return a Cookie, and that Cookie is used to authorize subsequent HTTP Requests from the same user/client/browser.

  • Web App Firewall (WAF) Cookie Protection – Since the Web Session Cookie essentially grants permission, security of this Cookie is paramount. Citrix ADC Web App Firewall has several protections for Cookies.

HTML Forms

Get Data from user – if the web site developer wants to collect any data from a user (e.g. Search term, account login, shopping cart item quantity, etc.), then the web developer creates HTML code that contains a <form> element.

Form fields – Inside the <form> element are one or more form fields that let users enter data (e.g. Name, Quantity), or let users select an option (drop-down box).

Submit button – The last field is usually a Submit button.

Field names – Each of the fields in the form has a unique name.

Field values – When a user clicks Submit, typically JavaScript on the client side ensures that the data was entered correctly. This is more about convenience than security. If users enter letters into a zip code field, JavaScript can immediately prompt the user to enter a zip code in the correct format.

GET and POST – The data is then submitted to the web server using one of two methods: GET or POST.

  • With GET, each of the field names and field values is put in the Query String portion of the URL (e.g. ?field1=value1&field2=value2), which is after the path and file name.
  • With POST, the HTTP Request Method is set to POST, and the field names and field values are placed in the Body of the HTTP Request.
  • The POST method is typically more secure. Web Servers can log the entire GET Method, including query strings. But POST parameters in the body are never logged.

Web server validates HTML form data – When a script on the web server receives the HTML form data, the script must validate the input. Do not rely on client-side Javascript to validate the data. Instead, all HTML form data must be inspected by the web server script for SQL Injection, Cross-site Scripting, etc.

  • Citrix ADC Web App Firewall (WAF) can do this inspection before the form data reaches the web server.
  • WAF can also validate the form fields. For example, Citrix ADC WAF can ensure that only numeric characters can be entered in a zip code field.

Web App Firewalls for HTML Forms – HTML Forms are the most sensitive feature in any web application since a hacker can use a form to upload malicious content to the web server. Web Developers must write their web server code in a secure manner. Use features like Citrix ADC Web App Firewall to provide additional protection.

  • WAF for JSON, XML – Other forms of submitting data to web servers, like JSON objects, XML documents, etc. should also be inspected. Citrix ADC Web App Firewall can do this too.

Asynchronous JavaScript (AJAX)

JavaScript AJAX – JavaScript on the client side can send HTTP Requests to Web Servers. Web Servers send back a response in JSON or XML format.

JSON is JavaScript Object Notation – JavaScript scripts can create objects (similar to hash tables) using JSON notation. Curly braces surround the object. Each element is “name”:”value” pair. The values can be more JSONs. And values can be an array of values, including more JSONs. JSONs can be embedded within other JSONs. JSONs are very familiar to any JavaScript developer.

JSON vs XML

  • JSON is smaller than XML. XML is marked up with human-readable tags, bloating the size. JSON contains data, curly braces, colons, quotes, and square brackets. That’s it. Very little of it is dedicated to markup so most of it is pure data.
  • Familiarity – Since JavaScript developers already know how to create JSONs, there’s nothing new to learn, unlike XML.

AJAX enables Single Page Applications (SPA) – JavaScript reads the contents of the HTTP response and uses it for any purpose. For example, JavaScript can use the data in the response to build a table in the webpage and display it to the user. This allows data on the page to change dynamically without requiring a full page reload.

REST API

Commercial systems have a programmatically-accessible API (Application Programming Interface) that allows programs and scripters to control a remote system. Some API commands retrieve information from the system. Other API commands invoke actions (e.g. create object) in the system.

Use HTTP to call API functions – Modern APIs can be activated using the HTTP Protocol. Create a specially-crafted HTTP Request and send it to an HTTP endpoint that is listening for API requests.

SOAP Protocol – Older HTTP-based APIs operate by exchanging XML documents. This is called SOAP (Simple Object Access Protocol). However, XML documents are difficult to program, and the XML tags consume bandwidth.

REST API – Another newer HTTP-based architecture is to use all of the HTTP Methods (GET, POST, PUT, DELETE), and exchange JSON documents. JSON is leaner than XML.

  • Citrix ADC Nitro API is a REST API.
  • Image from TutorialEdge

REST is stateless. All information needed to invoke the API must be included in one HTTP Request.

REST API is HTTP.

  • A REST-capable client is any client that can send HTTP Requests and process HTTP Responses. Some languages/clients have REST-specific functions. Others have only lower level functions for creating raw HTTP Requests.
  • On Linux, use curl to send HTTP Requests to an HTTP-based REST API.
  • In PowerShell, use Invoke-RestMethod to send an HTTP Request to an HTTP-based REST API.
  • Inside a browser, use Postman or other REST plug-in to craft HTTP Requests and send them to an HTTP-based REST API.

To invoke an HTTP REST-based API:

  1. HTTP Request to login – Send an HTTP Request with user credentials to the login URL or session creation URL detailed in the API documentation.
  2. Session Cookie – The REST API server sends back a Session Cookie that can be used for authorization of subsequent REST/HTTP Requests. The REST Client saves the cookie and adds it to every subsequent REST/HTTP Request.
  3. Create a REST API HTTP Request:
    1. Read API Documentation – Use the API’s documentation to find the URLs and HTTP Methods and JSON Arguments to invoke the API.
    2. Content-Type – Some REST API Requests require a specific Content-Type to be specified in the HTTP Request Header. Add it to the HTTP Request that you’re creating.
    3. JSON Object in Request – Most REST API Requests require a JSON object to be submitted in the HTTP Body. Use the language’s functions to craft a JSON object that contains the parameters that need to be sent to the API Call.
    4. URL Query String– Some REST API Requests require parameters to be specified in the query string of the URL.
  4. Send HTTP Request – Send the full HTTP Request with HTTP Method, URL, URL Parameters, Content-Type Header, Cookie Header, and JSON Body. Send it to the HTTP REST server endpoint.
  5. Process Response, including JSON – The REST API sends back a HTTP 200 success message with a JSON document. Or it sends back an error message, typically with error details in an attached JSON document.

Citrix Gateway VPN Networking

IP Pools

SNIP vs IP Pool (Intranet IPs) – By default, when a Citrix Gateway VPN Tunnel is established, a Citrix ADC SNIP is used as a shared Source IP for all traffic that leaves the Citrix ADC to the internal Servers. The internal Servers then simply reply to the SNIP. Instead of all VPN Clients sharing a single SNIP, you can configure IP Pools (aka Intranet IPs), where each VPN Client gets its own IP address.

Use IP Pools if Servers initiate communication to clients – if servers initiate communication to VPN Clients (IP Phones, SCCM, etc.), then each VPN Client needs its own IP address. This won’t work if all VPN Clients are sharing a single SNIP.

Intranet IPs assignment – Intranet IPs can be assigned to the Gateway vServer, which applies to all users connected to that Gateway vServer. Or you can apply a pool of IPs to a AAA Group, which allows you to assign different IP Pools (IP subnets) to different AAA Groups.

IP Pools and Network Firewall – If different IP Pools for different AAA Groups, then a network firewall can control which destinations can be reached from each of those IP Pools.

Intranet IP Subnet can be brand new – the IP subnets chosen for VPN Clients can be brand new IP Subnets that the Citrix ADC is not connected to. Citrix ADC is a router, so there’s no requirement that the IP addresses assigned to the VPN Clients be on one of the Citrix ADC’s data (VIP/SNIP) interfaces.

Reply traffic from Servers to Intranet IPs – If the Intranet IP Pool is a new IP Subnet, then on the internal network (core router), create a static route with the IP Pool as destination, and a Citrix ADC SNIP as Next Hop. Any SNIP on the Citrix ADC can reach any VPN Client IP address.

IP Spillover – if there are no more Intranet IPs available in the pool, then a VPN Client can be configured to do one of the following: use the SNIP, or transfer an existing session’s IP. This means that a single user can only have a single Intranet IP from a single client machine.

Split Tunnel

Split Tunnel – by default, all traffic from the VPN Client is sent across the VPN Tunnel. For high security environments, this is usually what you want, so the datacenter security devices can inspect the client traffic. Alternatively, Split Tunnel lets you choose which traffic goes across the tunnel, while all other client traffic goes out the client’s normal network connection (directly to the Internet).

Enable Split Tunnel in a Session Policy/Profile – the Session Policy/Profile with Split Tunnel enabled can be bound to the Gateway Virtual Server, which affects all VPN users, or it can be bound to a Gateway AAA Group.

Intranet Applications define traffic that goes across the Tunnel – If Split Tunnel is enabled, then you must inform the VPN Client which traffic goes across the Tunnel, and which traffic stays local. Intranet Applications define the subnets and port numbers that go across the Tunnel. The Intranet Applications configuration is downloaded to the VPN Client when the Tunnel is established.

  • Intranet Applications – Route Summarization – If Split Tunnel is enabled, a typical configuration is to use a summarized address for the Intranet Applications. Ask your network team for a short network prefix that matches all internal IP addresses. For example, every private IP address (RFC 1918) can be summarized by three route prefixes. The summarized Intranet Applications can then be assigned to all VPN Clients. Most networking training guides explain route summarization in detail.
    • If your internal servers all have IP addresses that start with 10., then you can create a Intranet Application for 10.0.0.0 with netmask 255.0.0.0. This Intranet Application would send all traffic with Destination IP Addresses that start with 10. across the VPN tunnel.
  • Intranet Applications – Specific Destinations – Alternatively, you can define an Intranet Application for every single destination Server IP  Address and Port. Then bind different “specific” Intranet Applications to different users (AAA Groups). Note: this option obviously requires more administrative effort.
  • For configuration details, see SSL VPN: Intranet Applications.

Split DNS – If Split Tunnel is enabled, then Split DNS can be set to Remote, Local, or Both. Local means use the DNS servers configured on the Client. Remote means use the DNS Servers defined on the Citrix ADC. Both will check both sets of DNS Servers.

VPN Authorization

There are three methods of controlling access to internal Servers across the VPN Tunnel – Authorization Policies, Network Firewall (usually with Intranet IPs), and Intranet Applications (Split Tunnel).

  • Authorization Policies control access no matter how the VPN Tunnel is established. These Policies use Citrix ADC Policy Expressions to select specific destinations and either Allow or Deny. In Citrix ADC 11.1 and older, Authorization Policies use Classic Policy Expressions only, which has a limited syntax. In Citrix ADC 12 and newer, Authorization Policies can use Default Syntax Policy Expressions, allowing matching of traffic based on a much broader range of conditions.
  • Intranet Applications – If Split Tunnel is enabled, then Intranet Applications can be used to limit which traffic goes across the Tunnel. If the Intranet Applications are “specific”, then they essentially perform the same role as Authorization Policies. If the Intranet Applications are “summarized”, then you typically combine them with Authorization Policies.
  • Network firewall (IP Pools) – If Intranet IPs (IP Pools) are defined, then a network firewall can control access to destinations from different VPN Client IPs. If Intranet IPs are not defined, then the firewall rules apply to the SNIP, which means every VPN Client has the same firewall rules.

VPN Tunnel Summary

In Summary, to send traffic across a VPN Tunnel to internal servers, the following must happen:

  1. If Split Tunnel is enabled, then Intranet Applications identify traffic that goes over the VPN tunnel. Based on Destination IP/Port.
  2. Authorization Policies define what traffic is allowed to exit the VPN Tunnel to the internal network.
  3. Static Routes for internal subnets – to send traffic to a server, the Citrix ADC needs a route to the destination IP. For VPN, Citrix ADC is usually connected to both DMZ and Internal, with the default route (default gateway) on the DMZ. To reach remote internal subnets, you need static routes for internal destinations through an internal router.
  4. Network Firewall must allow the traffic from the VPN Client IP – either SNIP, or Intranet IP (IP Pool).
  5. Reply traffic – If the VPN Client is assigned an IP address (Intranet IPs aka IP Pool), then server reply traffic needs to route to a Citrix ADC SNIP. On the internal network, create a static route with IP Pool as destination, and a Citrix ADC SNIP as Next Hop.

PXE

Network Boot and PXE

Network Boot – when you configure a machine to boot from the network, the machine downloads its operating system from a TFTP server while the machine is still in BIOS boot mode. The operating system download happens every time the machine boots. The machine does not need any hard drives because everything it needs it gets from the network.

  • Bootstrap file – the first file downloaded from the TFTP server is called the Bootstrap, which is a small file that starts enough of the operating system so the machine can connect to the network and download the rest of the operating system files.
  • NICs and Network Boot – Almost every Network Card (NIC), including virtual machine NICs, has Network Boot capability.
    • A notable exception is Hyper-V Synthetic NICs; Hyper-V Legacy NIC can Network Boot, but Hyper-V Synthetic NICs cannot.
  • Configure BIOS to boot from network – to configure a machine to network boot, in the machine’s BIOS, there should be an option to Network Boot from a Network Card (NIC). Move that boot option to the top of the list.

PXE (Pre-boot Execution Environment) – PXE is a mechanism for Network Boot machines to discover the location of the bootstrap file. PXE is based on the DHCP protocol. PXE works like this:

  1. Get IP from DHCP – The network boot machine can’t download anything until it has an IP address, which it gets from DHCP.
  2. Discover TFTP Server address – Then the machine uses DHCP to get the IP address of the TFTP Server and the name of the bootstrap file that should be downloaded from the TFTP Server.

Network Boot without PXE – You can also Network Boot without PXE by booting from an ISO file or local hard drive that has just enough code on it to get the rest of the bootstrap from the TFTP server. DHCP is still usually used to get an IP address, but the IP address of the TFTP server is usually burned into this locally accessible code.

PXE works as follows:

  1. DHCP Request to get IP – The NIC performs a DHCP Request to get an IP address.
  2. PXE Request to get TFTP info – The NIC performs a PXE Request (second DHCP Request) to get the TFTP IP address and file name.
  3. Download from TFTP – The NIC downloads the bootstrap file from the TFTP server and runs it.
  4. Run the bootstrap – The bootstrap file usually downloads additional files from a server machine (e.g. Citrix Provisioning Server) and runs them.

TFTP Server – the TFTP Server/Service can be running from Citrix Provisioning Servers, or you can build some Linux machines and run TFTP from them.

PXE and DHCP

DHCP Scope Options for PXE – The TFTP Server Address and the Bootstrap file name are delivered using DHCP Scope Options.

  • The response for the initial DHCP Request for an IP Address can include the TFTP address and bootstrap file in DHCP Scope Options 66 and 67.
  • Or, if the response for the initial DHCP Request for an IP address does not include Options 66 and 67, then the network boot machine does another DHCP Request, this time on port UDP 4011. A PXE Server should be listening for this new port number and the PXE Server can respond with the TFTP Server address and the bootstrap file name.

Two DHCP port numbers – In other words, the Network Boot machine needs to one DHCP Request, or two DHCP Requests. The first DHCP Request is always on UDP 67. While the second DHCP Request is on UDP 4011. Having two separate port numbers allows the two DHCP Servers to perform different functions. the UDP 67 DHCP server is responsible for handing out IP addresses, while the UDP 4011 DHCP Server is responsible for handing out TFTP address and bootstrap file names.

  • PXE Server = DHCP – A PXE Server running a PXE Service is nothing more than a DHCP server that listens on UDP 4011. Citrix Provisioning Servers have a PXE Service that can be optionally started if you are unable able add Options 66 and 67 to your primary DHCP servers.

PXE Request does not cross routers – The second DHCP Request has the same limitations as the first DHCP Request in that neither DHCP request can cross a subnet boundary unless the local router is configured to listen for the UDP 4011 DHCP Request and forward it to a PXE Server. Most routers can be easily configured for UDP 67, but UDP 4011 forwarding is not a typical configuration. It might be easier to put PXE Servers on the same subnet as the Network Boot machines. Or add DHCP Scope Options 66 and 67 to the primary DHCP Servers.

PXE Service Redundancy – If you use a PXE Service that is separate from your main DHCP Servers, then you want at least two PXE Servers that are reachable from your Network Boot clients. PXE Service redundancy works the same as DHCP Server redundancy except that you don’t have to replicate any DHCP databases. An easy way to provide redundancy for PXE is to put the PXE servers on the same subnet as the Network Boot clients.

TFTP Redundancy

If TFTP is not reachable, then your Network Boot clients can’t boot.

DHCP Scope Option 66 can only point to a single TFTP Server IP Address. If you try to add two TFTP Server addresses, then either the Network Boot clients won’t boot, or they’ll only use the first TFTP Server address. Here are some workarounds for this limitation.

  • Load Balance TFTP using Citrix ADC  – Use Citrix ADC to load balance two or more TFTP Servers and configure DHCP Option 66 to point to the Citrix ADC Load Balancing VIP.
  • DNS Round-Robin – Option 66 can point to a DNS Round Robin-enabled DNS name, where the single DNS name resolves to both TFTP Servers’ IP addresses. This assumes the DHCP Client receives DNS Server information from the DHCP Server.
  • Separate Option 66 configured on each DHCP Server – If you have multiple DHCP Servers, each DHCP Server can send back a different Option 66 TFTP Server IP address.

PXE instead of DHCP Scope Option 66 – Another High Availability workaround is to not use DHCP Scope Option 66 and instead install the PXE Service on two servers. The Network Boot Clients would need to be able to reach both PXE Servers. If Network Boot clients and PXE Services are on the same subnet, then each PXE Service can send back a different TFTP Server IP address. Either PXE Service can respond to the PXE Request, so if one PXE Server is down, then the other PXE Server will respond.

  • This option works best if PXE Service and TFTP Service are installed on the same server, like it usually is in Citrix Provisioning environments.

Citrix Provisioning and TFTP

Citrix Provisioning (CPV) is the new name for Citrix Provisioning Services.

TFTP Server is usually installed and running on each Citrix Provisioning server.

In addition to normal DHCP PXE options for Network Boot, Citrix Provisioning has several additional options for delivering the TFTP Server addresses to CPV Target Devices (Network Boot Clients). These options are:

  • PXE Service on CPV servers on same subnet as Target Devices
    • CPV Servers are connected to the same subnet as the Target Devices. PXE Service is installed and running on each CPV server. Either PXE Service can respond to PXE Requests from the Target Devices on the same subnet.
    • For large environments, use a /21 or smaller subnet mask to allow hundreds of Target Devices on one subnet. 21-bit subnet mask allows 2,048 machines on one subnet.
    • You can also install a DHCP Service (e.g. Microsoft DHCP) onto the Citrix Provisioning servers. Then you don’t need to configure the local router to forward DHCP requests to a different DHCP server.
  • Target Devices boot from CPV Boot ISO
    • The Boot ISO has the TFTP Server IP addresses (Citrix Provisioning server IP addresses) pre-configured.
    • Included with CPV installation is a Boot ISO Creator called Boot Device Management.
    • Note: The Boot ISO uses a different TFTP Service than normal PXE. Normal TFTP is UDP 69, while the Boot ISO connects a TFTP service called Two-stage Boot TFTP Service that is listening on UDP 6969.
  • Target Device Boot Partition
    • CPV can burn boot code into a hard disk attached to each Network Boot machine.
    • The boot partition boot process also uses the Two-stage Boot TFTP Service.

Citrix ADC Global Server Load Balancing (GSLB)

GSLB is DNS

GSLB is DNS – Citrix ADC receives a DNS Query and returns an IP address in the DNS Response, which is exactly what a DNS Server does. Enabling Global Server Load Balancing (GSLB) on a Citrix ADC essentially turns your ADC into a DNS server.

GSLB Purpose – The purpose of GSLB is to resolve DNS names that have multiple IP address responses. A web site can be hosted in multiple datacenters. Each data center has different IP addresses. To reach the web site in a particular data center, you use one IP address. To reach the web site in a different data center, you use a different IP address. Instead of creating a different DNS name for each IP address, it would be more convenient for the user if a single DNS name could resolve to both IP addresses.

How GSLB chooses an IP address – GSLB has several methods of choosing the IP address that is given out in the DNS response.

  • IP Address Monitoring – Is the IP address reachable? If not, then don’t give out that IP address.
  • Active/Passive – Is the website only “active” at one IP address? If so, then give out that “active” IP address.
    • If the “active” IP address is down, then give out the “passive” IP address instead. This is automatic and there’s no need to manually change the DNS record.
  • Proximity – Which IP address is closest to the user?
  • Site persistence – Which IP address did the DNS Client get last time it submitted a DNS Query?
  • Load Balancing Method – which IP address is receiving less traffic?

Active IP address Monitoring – GSLB will not give out an IP address unless that IP address is UP. GSLB has two options for determining if an IP address is reachable or not:

  • Ask ADC for VIP status – If the Active IP is an ADC Virtual Server IP, then GSLB can ask the ADC appliance for the status of the VIP.
    • Citrix ADC uses a proprietary protocol called Metric Exchange Protocol (MEP) to transmit GSLB-specific information, including VIP status, between ADC appliances.
  • Monitors – for all other cases, including ADC VIPs, GSLB can use a Monitor to periodically probe the Active IP address to make sure it’s reachable. For TCP services, a simple TCP three-way handshake connection might be sufficient. For UDP, some other monitoring mechanism is needed (e.g. ping).
  • Internet is up? – For public DNS, GSLB needs to determine if Internet clients can reach the Active IP address across the Internet.
    • Active IP remote from GSLB DNS – For Active IPs in a datacenter that is remote from the GSLB DNS listener appliance, configure the GSLB Monitoring Probe to route across the Internet, so the Monitoring Probe is essentially using the same path that an Internet client would use.

Proximity Load Balancing Methods – GSLB supports two Proximity Methods:

  • Static Proximity – The Source IP of the DNS Query is looked up in a location database to determine where the DNS Query came from. The GSLB Active IPs are also looked up in the location database to determine the location of each Active IP. The Active IP address that is closest to the DNS Query’s Source IP is returned.
    • Citrix ADC has a built-in static proximity location database that you can use. Or you can import a database downloaded from a geolocation provider. These databases are CSV files containing IP ranges and coordinates.
  • Dynamic Proximity – each Citrix ADC appliance participating in GSLB pings the Source IP of the DNS Query to determine which ping is fastest.
    • If ping is blocked to the Source IP, then you can configure Static Proximity as a backup method.
  • DNS Query Source IP is the IP address of the client’s DNS Recursive Resolver server, and not the actual IP address of the client machine. If a client machine uses a DNS Server that is in a different city than the client machine, then the proximity results will be distorted.
    • EDNS Client Subnet (ECS) is intended to solve this problem. Newer versions of Citrix ADC support ECS.

GSLB is only useful if a single DNS name can resolve to multiple IP addresses. The purpose of GSLB is for DNS names that have multiple IP address responses. GSLB selects one of those IP addresses and returns it in response to a DNS Query. If the DNS name can only ever respond with one IP address, or if you don’t want GSLB to choose a different IP address automatically, then it would be easier to just leave the single DNS name with single IP address on regular DNS servers.

Limitations of regular DNS Servers:

  • The DNS Server doesn’t care if the IP address is reachable or not. There’s no monitoring.
  • The DNS Server doesn’t know which IP address is closest to the user. There’s no proximity load balancing.
  • The DNS Server can’t do site persistence, so you could get a different IP address every time you perform the DNS Query.
  • DNS records have a Time-to-live (TTL). If TTL is high, and if you manually change the DNS record to a different IP address, then it could take as long as the TTL for the change to be propagated to all DNS Recursive Resolver servers and DNS Clients.
    • GSLB DNS responses have a default TTL of 5 seconds.

GSLB is not in the data path – once GSLB returns an IP address to the user, the user connects to the IP address and GSLB is done until the user needs to resolve the DNS name again. Since GSLB is just DNS, Citrix ADC GSLB can return any IP address, even if that IP address is not owned by an ADC appliance.

  • Short GSLB TTL – GSLB DNS TTL defaults to 5 seconds, so the user might need to resolve the DNS name again in the very near future. HTTP requests are short-lived and thus might require frequent DNS queries. While TCP connections, like Citrix ICA connections, are long-lived and might only need a DNS Query at the beginning of their connection.

Site Persistence – Once an Active IP address is selected for a user, you probably want the user to always connect to that Active IP address for a period of time. This is similar to Load Balancing Persistence needed for Web Sessions. GSLB has three methods of Site Persistence:

  • Source IP – GSLB records in memory the DNS Query’s Source IP and the Active IP that was given in response to a DNS Query. Each GSLB-enabled DNS name has its own Source IP persistence table. Multiple ADC appliances participating in GSLB replicate the Source IP persistence tables with each other using the proprietary Metric Exchange Protocol (MEP).
  • Cookie Persistence – For Active IPs that are HTTP VIPs on a Citrix ADC appliance/pair connected by GSLB MEP, the first HTTP Response from the Citrix ADC VIP will include a cookie indicating which GSLB Site (data center) the HTTP Response came from. The HTTP Client will include this Site Cookie in the next HTTP Request to the HTTP VIP. After the DNS TTL expires, if the client’s DNS Query gets a different IP address response that is in a different GSLB Site, then the HTTP Request will be sent to the wrong VIP. Citrix ADC has two options for getting the HTTP Request from the wrong VIP to the correct VIP:
    • HTTP Redirect – redirect the user to a different site-specific DNS name (a Site Prefix is added to the original DNS name). This requires the SSL VIP’s certificate to match the original GSLB-enabled DNS name, plus the new site-specific DNS name.
    • Proxy – proxy the HTTP Request to the HTTP VIP in the correct GSLB Site. This means that Citrix ADC in the wrong GSLB Site must be able to forward the HTTP Request to the HTTP VIP in the correct GSLB Site.

GSLB Architecture

Multiple ADC GSLB appliances – for redundancy, you will want to enable GSLB on at least two pairs of ADC appliances, usually in different datacenters. The location of the ADC GSLB appliances is unrelated to the IP addresses that are given out in DNS Responses to DNS Queries.

  • Metric Exchange Protocol – the multiple ADC GSLB appliances communicate with each other using Citrix’s proprietary Metric Exchange Protocol (MEP). MEP transmits GSLB-specific information, including: Dynamic Proximity latency results, Site persistence, IP Address Traffic Load, and VIP Status (for monitoring).
  • Identical GSLB Configuration on all appliances – DNS Queries are delegated to multiple ADC GSLB appliances. It’s not possible to control which Citrix ADC appliance/pair resolves the DNS Query. Thus all Citrix ADC appliance/pairs that resolve GSLB DNS names must have identical GSLB configuration, so the DNS responses are the same no matter which Citrix ADC appliance/pair resolves the DNS name.

DNS listener – Each ADC GSLB appliance needs at least one DNS listener. For public DNS (Internet DNS), the DNS listener IP address must be reachable from the Internet. For internal private DNS, then DNS listener IP address should be an internal IP address. ADC has several methods of listening for DNS requests:

  • ADNS Service – ADC listens for ADNS queries on an ADC SNIP. ADNS Services can only resolve DNS names that are created locally on the ADC appliance. The ADNS service cannot ask other DNS servers to resolve DNS names. You can create more than one ADNS service listener on a single ADC appliance.
  • DNS Load Balancing (DNS Proxy) – a Load Balancing Virtual Server VIP with DNS as the protocol. The load balancing services point to your normal DNS servers. When the Load Balancing VIP receives a DNS Query, it will first look in its GSLB configuration for a match. If there’s no match, then ADC will forward the DNS Query to your DNS servers so they can resolve it. This configuration is called DNS Proxy. You can create multiple DNS Load Balancing VIPs on a single appliance

Both Public DNS and Internal Private DNS on one GSLB appliance? – ADC GSLB only has one DNS database. If you create DNS listeners for both internal private DNS and public DNS on the same appliance, then be aware that there is no real separation between the two types of DNS Queries. A more secure approach is to have separate ADC GSLB appliances for public DNS vs internal DNS.

  • DNS Views – in some cases you can configure DNS Views to provide different IP address responses depending on whether the DNS Client is a public machine or an internal machine. You can also use DNS Policies to block DNS Requests from Internet machines for specific internal private DNS names.

Delegate GSLB-enabled DNS names to Citrix ADC GSLB DNS listeners. Delegation is configured by creating NS (Name Server) records in the existing DNS zone. NS records are a way of telling a Recursive Resolver “I don’t have the answer, but these other DNS servers do have the answer”. There are a few methods of doing this delegation:

  • In the existing DNS zone, delegate specific DNS names to Citrix ADC GSLB DNS Listeners.
    • For example, you can delegate gateway.company.com by creating two NS records for gateway.company.com and setting them to the IP addresses of the GSLB DNS Listeners.
    • Each DNS name needs a separate delegation (separate set of NS records).
  • In the existing DNS zone, delegate a sub-zone (e.g. gslb.company.com) to Citrix ADC DNS. Then create CNAMEs for each GSLB-enabled DNS name that are alias’d to an equivalent DNS name in the sub-zone. For example:
    • Create two NS records for gslb.company.com and set them to the IP addresses of the GSLB DNS Listeners.
    • Then create a CNAME for gateway.company.com alias’d to gateway.gslb.company.com. Since the gslb.company.com sub-zone is delegated to Citrix ADC GSLB DNS Listeners, Citrix ADC will resolve this DNS name.
    • Create CNAMES for any additional GSLB-enabled DNS names.
  • Move the entire existing DNS zone to Citrix ADC .
    • Note: Citrix ADC was never designed as a full-fledged DNS Service, so you might find limitations when choosing this option.

Other GSLB Use Cases

GSLB and Multiple Internet Circuits – a common use case for GSLB is if you have multiple Internet circuits connected to a single datacenter and each Internet circuit has a different public IP subnet. In this scenario, you have one DNS name, and multiple public IP addresses, which is exactly the scenario that GSLB is designed for.

  • Local Internet Circuit Monitoring – GSLB Services need a monitor that can determine if the local Internet is up or not. You don’t want to give out a Public IP on a particular Internet circuit if the local Internet circuit is down. You typically configure the GSLB Monitor to ping a circuit-specific IP address (e.g. ISP router).

Internal GSLB – GSLB can also respond to internal DNS Queries by giving out Internal Private IPs. However, there are a couple differences for Internal Private IP addresses when compared to Public IP addresses:

  • Internal Private IPs are not in the location database – If GSLB is configured for static proximity load balancing, then you must manually add each internal subnet to the location database and specify geographical coordinates for each internal subnet.
  • Internal Private IPs are not affected by Internet outage – GSLB monitoring for internal Active IPs is usually configured differently than GSLB monitoring for public Active IPs. If the Internet goes down in a datacenter, then you want GSLB to stop giving out public IP addresses for that datacenter. However, if Internet goes down in a datacenter, then internal users are usually not affected. This means you need different monitoring configuration for Public IPs vs Internal Private IPs.

See Global Server Load Balancing (GSLB) for information on how to configure GSLB on ADC appliances.

nFactor Authentication – NetScaler Gateway 12 / Citrix Gateway 12.1

Last Modified: Apr 16, 2021 @ 2:32 pm

87 Comments

Navigation

💡 = Recently Updated

Change Log

nFactor Overview

nFactor lets you configure an unlimited number of authentication factors. You are no longer limited to just two factors.

Each authentication factor performs the following tasks:

  1. Collect credentials from the user. These credentials can be anything supported by Citrix ADC, including:
    • SAML assertion
    • Client Certificate
    • OAuth OpenID Connect
    • Kerberos ticket
    • StoreFrontAuth – authentication is delegated to Citrix StoreFront
    • Forms-based authentication (traditional web-based logon page) for LDAP, RADIUS, etc.
      • Multiple passwords can be collected with one form.
      • Or prompt the user multiple times throughout the authentication chain.
      • The logon page can contain a domain drop-down.
    • Endpoint Analysis Scan – either pre-authentication, or post-authentication.
    • EULA
    • Google reCAPTCHA
    • Swivel
    • Use a drop-down to select an authentication method
  2. This factor’s credentials are evaluated. The results can be:
    • Authentication success
    • Authentication failure
    • Group extraction
    • Attribute extraction from SAML, Certificate, etc.
  3. Based on the evaluation results, do one of the following:
    • Allow access
    • Select next factor
    • Deny access
  4. If there’s a Next Factor, repeat these steps, until there are no more Next Factors to evaluate.
  5. The Next Factor can also do one of the following:
    • Prompt the user for more credentials
    • If the Login Schema asked for multiple passwords, evaluate the already entered next set of credentials.
    • Use a policy expression to select another Next Factor (no authentication). This is typically used with group extraction so that groups determine the Next Factor.

Here are some nFactor use cases, but the combinations are almost limitless:

  • Choose Authentication method based on Active Directory group: Logon screen asks for user name only. Extract user’s groups from Active Directory. Based on user’s Active Directory groups, either ask user for client certificate, or ask user for LDAP password. If LDAP, the username doesn’t need to be entered again.
  • Ask for Certificate first:
    • If client certificate is valid, perform LDAP only.
    • If no client certificate, perform LDAP + RADIUS
  • Two-factor with passwords checked in specific order: Display logon screen with two password fields. Check the first password. If the first password succeeds, then check the second password. This lets you check RADIUS before LDAP.
  • Run Endpoint Analysis first:
    • If passes, perform LDAP only.
    • If fails, perform LDAP + RADIUS
  • See Sample Configurations later for many more combinations.

All new authentication methods added to Citrix ADC require nFactor configuration and are not supported on native Citrix Gateway. These new authentication methods include:

nFactor is a AAA feature, which means you need Citrix ADC Advanced Edition (aka NetScaler Enterprise Edition) or Citrix ADC Premium Edition (aka NetScaler Platinum Edition). Citrix ADC Standard Edition and Citrix Gateway VPX are not entitled for nFactor.

Citrix ADC supports two types of authentication policies – Classic, and Advanced (aka Default). You can bind Classic Authentication Policies directly to Citrix Gateway Virtual Servers, but today you cannot bind Advanced Authentication Policies to Citrix Gateway. The only way to use Advanced Authentication Policies with Citrix Gateway is to configure nFactor on a AAA Virtual Server and then link the AAA Virtual Server to the Gateway Virtual Server.

  • Workspace app 1809 and newer with Citrix Gateway (NetScaler) 12.1 build 49 and newer support nFactor authentication. Older Receivers and older NetScalers don’t support nFactor, so you’ll instead have to use a web browser.

nFactor configuration summary (detailed instructions below):

  • Each factor is a combination of Advanced Authentication Policies and Login Schema.
    • Advanced policy means it uses an Advanced (Default Syntax) expression as opposed to the classic syntax expression traditionally used in Citrix Gateway authentication policies.
    • Login Schema is a custom HTML form where users enter credentials.
  • The first factor (Advanced Authentication Policies and Login Schema) is bound directly to a AAA Virtual Server.
  • Next factors are bound to Authentication Policy Labels. These Labels are then chained to Advanced Authentication Policies in prior factors.
    • AAA vServer > Advanced Authentication Policy > Next Factor > Authentication Policy Label > Advanced Authentication Policy > Next Factor > Authentication Policy Label > … until there are no more Next Factors configured.
  • Authentication Profile links AAA vServer with Citrix Gateway.

Also see:

This article will detail how to configure nFactor from top to bottom.:

  1. Create AAA vServer
  2. Create Login Schema Profiles
  3. Create Login Schema Policy – select Login Schema Profile, bind Login Schema Policy to AAA vServer
  4. Create Authentication Actions – LDAP, RADIUS, etc.
  5. Create Advanced Authentication Policies – select Authentication Action, bind Advanced Authentication Policy to AAA vServer
  6. Create Authentication Policy Labels – bind Login Schema, bind Advanced Authentication Policies
  7. Edit Advanced Authentication Policy binding and select Next Factor Authentication Policy Label.
  8. Create Citrix Gateway Traffic Policy for Single Sign-on to StoreFront.
  9. Create Authentication Profile
  10. Edit Citrix Gateway – bind Authentication Profile, bind Traffic Policy

Once you are familiar with nFactor, due to the way the objects are linked together, it’s probably easier to configure it from bottom up:

  1. Create Authentication Actions – LDAP, RADIUS, etc.
  2. Create Advanced Authentication Policies – select Authentication Action
  3. Create Login Schema Profiles
  4. Create Authentication Policy Labels – bind Login Schema, bind Advanced Authentication Policies
  5. Create Login Schema Policy – select Login Schema Profile
  6. Create AAA vServer – bind Login Schema, bind Advanced Authentication Policies, select Next Factor Authentication Policy Label
  7. Create Citrix Gateway Traffic Policy for Single Sign-on to StoreFront.
  8. Create Authentication Profile
  9. Edit Citrix Gateway – bind Authentication Profile, bind Traffic Policy

It can be difficult to visualize a nFactor configuration so my ADC Virtual Server Configuration Extractor script now includes a nFactor visualizer. Here’s an example for a Native OTP configuration.

AAA Virtual Server

Create AAA Virtual Server

To use nFactor with Citrix Gateway, you first configure it on a AAA Virtual Server. Then you later link the AAA Virtual Server to the Citrix Gateway Virtual Server.

  1. If AAA feature is not already enabled, on the left menu, expand Security, right-click AAA – Application Traffic, and click Enable Feature.
  2. Go to Security > AAA > Virtual Servers.
  3. On the right, click Add.
  4. Give the Virtual Server a name.
  5. If you are only using this AAA Virtual Server for Citrix Gateway, then you can change the IP address Type to Non Addressable. It’s also possible to content switch to AAA (Citrix CTX201949 One Public IP for AAA-TM Deployments on NetScaler).
  6. Click OK.
  7. In the Certificates section, click where it says No Server Certificate.

    1. Click where it says Click to select.
    2. Click the radio button next to a certificate for the AAA Virtual Server, and click Select. Since this AAA Virtual Server is not directly addressable, the chosen certificate doesn’t matter.
    3. Click Bind.
  8. Click Continue to close the Certificate section.
  9. You probably don’t have any Advanced Authentication Policies yet, so just click Continue.

Bind Portal Theme to AAA Virtual Server

If this AAA Virtual Server is used not just for Citrix Gateway but also directly addressable for traffic management (Load Balancing, Content Switching), then you might want to change the AAA Portal theme.

  1. Go to Citrix Gateway > Portal Themes, and add a theme. You create the theme under Citrix Gateway, and then later bind it to the AAA Virtual Server.
  2. Create a theme based on the RfWebUI Template Theme.
  3. After adjusting the theme as desired, at the top of the portal theme editing page, Click to Bind and View Configured Theme.
  4. Change the selection to Authentication.
  5. Use the Authentication Virtual Server Name drop-down to select the AAA Virtual Server, and click Bind and Preview. You can close the preview window.

Client Certificate Authentication

If one of your authentication Factors is client certificate, then you must perform some SSL configuration on the AAA Virtual Server:

  1. Go to Traffic Management > SSL > Certificates > CA Certificates, and install the root certificate for the issuer of the client certificates. Root certificates do not have a key file.

  2. Go to Traffic Management >SSL > Change advanced SSL settings.

    1. Scroll down. If you see Default Profile: ENABLED, then you must use an SSL Profile to enable Client Certificate Authentication. Otherwise, you can enable Client Certificate Authentication directly on the AAA Virtual Server in the SSL Parameters section.
  3. If Default SSL Profiles are enabled, then create a new SSL Profile with Client Authentication enabled:
    1. On the left menu, expand System, and click Profiles.
    2. On the top right, switch to the SSL Profile tab.
    3. Right-click the ns_default_ssl_profile_frontend profile, and click Add. This copies settings from the default profile.
    4. Give the Profile a name. The purpose of this profile is to enable Client Certificates.
    5. Scroll down and find the Client Authentication checkbox. Check the box.
    6. Change the Client Certificate drop-down to OPTIONAL.
    7. Copying the default SSL Profile does not copy the SSL Ciphers so you’ll have to redo them.
    8. Click Done when done creating the SSL Profile.
    9. Go to Security > AAA – Application Traffic > Virtual Servers, and edit a AAA vServer.
    10. Scroll down to the SSL Profile section and click the pencil.
    11. Change the SSL Profile drop-down to the profile that has Client Certificates enabled. Click OK.
    12. Scroll down this article until you reach the instructions to bind the CA certificate.
  4. If default SSL Profiles are not enabled:
    1. Go to Security > AAA > Virtual Servers, and edit an existing AAA Virtual Server.
    2. On the left, in the SSL Parameters section, click the pencil icon.
    3. Check the box next to Client Authentication.
    4. Make sure Client Certificate drop-down is set to Optional, and click OK.
  5. On the left, in the Certificates section, click where it says No CA Certificate.
  6. Click to select.
  7. Click the radio button next to the root certificate for the issuer of the client certificates, and click Select.
  8. Click Bind.

Login Schema

Login Schema XML File

Login Schema is an XML file providing the structure of forms-based authentication logon pages.

nFactor implies multiple authentication Factors that are chained together. Each Factor can have different Login Schema pages/files. In some authentication scenarios, users could be presented with multiple logon screens.

Or you can have one Login Schema gather information that can be passed on to multiple Factors, so that the later Factors don’t need to display another Login Schema. This is particularly useful for traditional two-password logon screens (LDAP + RADIUS), since each password is evaluated in a separate Factor:

  • The first password is evaluated in the first factor (e.g. LDAP). If successful, then proceed to the second factor.
  • The second factor (e.g. RADIUS) evaluates the second password. However, the second password has already been entered, so there’s no need to ask the user for it again. To prevent a Login Schema from being shown to the user, select noschema (LSCHEMA_INT) in the Authentication Policy Label.

Several Login Schema .xml files are included with Citrix ADC under /nsconfig/loginschema/LoginSchema.

You can edit the Login Schema labels from within the Citrix ADC management GUI. When the labels are changed, Citrix ADC copies the Login Schema to a new .xml file based on the Schema Name entered in this widow, or based on the original file name.

Or you can use WinSCP to connect to the appliance, duplicate one of the existing .xml files, and edit it as desired. For example, you can configure fields (InitialValue tag) to pre-fill information from previous Factors, as shown below:

The structure of the Login Schema is documented at Citrix Common Authentication Forms Language Citrix Developer Documentation.

CTP Sam Jacobs at SYN229 – nFactor and Login Schemas explains how to customize the .xml file.

The login schema can also contain a domain drop-down. See CTX201760 nFactor – Domain Drop-Down in First Factor then Different Policy Evaluations Based on Groups for a sample configuration.

Login Schema and Authentication Factor can be a EULA. See Citrix CTX226488 How to Configure EULA as an Authentication Factor in NetScaler nFactor.

Citrix CTX219545 Custom Login Labels in NetScaler nFactor Authentication: add a Requirement element with a Label sub-element to the Login Schema .xml file. Then use JavaScript to populate the label with any desired HTML. Another example is Morten Kallesoee nFactor – adding custom links.

Several more samples can be found later.

Login Schema Profile

To configure a Login Schema Profile:

  1. Create or Edit a Login Schema .XML file based on your nFactor design.
  2. Go to Security > AAA > Login Schema.
  3. On the right, switch to the Profiles tab, and click Add.
  4. In the Authentication Schema field, click the pencil icon.
  5. Click the LoginSchema folder to see the files in it.
  6. Select one of the files. You can see a preview on the right. The labels can be changed by clicking the Edit button on the top right.
  7. When you Save the changes, a new file is created under /nsconfig/LoginSchema.
  8. On the top right, click Select.
  9. Give the Login Schema a name, and click More.
  10. You typically need to use the entered credentials elsewhere. For example, you might need to use the username and one of the passwords to later Single Sign-on to StoreFront. Near the bottom of the Login Schema Profile, click More, and enter unique values for the indexes. These values can be between 1 and 16.

    1. Later you reference these index values in a Traffic Policy/Profile by using the expression HTTP.REQ.USER.ATTRIBUTE(#).
  11. Click Create to create the Login Schema profile.

Note: if you later edit the Login Schema .xml file, the changes might not be reflected until you edit the Login Schema Profile, and Select the .xml file again.

Login Schema Policy

To bind a Login Schema Profile to a AAA vServer, you must first create a Login Schema Policy. Login Schema Policies are not required when binding the Login Schema Profile to an Authentication Policy Label, as detailed later.

To create and bind a Login Schema Policy:

  1. On the left, go to Security > AAA > Login Schema.
  2. On the right, switch to the Policies tab, and click Add.
  3. Use the Profile drop-down to select the Login Schema Profile you already created.
  4. Enter a Default Syntax expression (e.g. true) in the Rule box, and click Create.
  5. On the left, go to Security > AAA > Virtual Servers, and edit an existing AAA Virtual Server.
  6. On the right, in the Advanced Settings column, click Login Schemas.
  7. On the left, in the Login Schemas section, click where it says No Login Schema.
  8. Click where it says Click to select.
  9. Click the radio button next to the Login Schema policy, and click Select. Only Login Schema Policies appear in this list. Login Schema Profiles (without a policy) do not appear.
  10. Click Bind.

Advanced Authentication Policies

Authentication policies are a combination of policy expression, and policy action. If the expression is true, then evaluate the authentication action.

The Action is always an authentication server (LDAP, RADIUS, etc.).

The policy expression can be either in classic syntax, or in the newer default syntax.

The policy type is either Basic or Advanced. Basic policies can only use classic syntax. Advanced policies only use the newer default syntax. Both types of policies use the same Actions (authentication servers).

nFactor requires Advanced Authentication Policies; Basic policies won’t work.

Note: Citrix Gateway 12.0 and newer have deprecated Basic Authentication Policies (Classic Syntax). The only way to bind an Advanced Authentication Policy (Default Syntax) to Gateway is through nFactor and AAA.

Create Advanced Authentication Policy

You will need Authentication Actions/Servers (e.g. LDAP, RADIUS, CERT, SAML, etc.)

  • When creating an Advanced Authentication Policy, there’s a plus (Add) icon that lets you create Authentication Actions/Servers.
  • Or you can create Authentication Actions (Servers) prior to creating the Advanced Authentication Policy. The Authentication Servers are located under Authentication > Dashboard. On the right, click Add and select a Server Type. The instructions for creating these Authentication Servers is not detailed here. See the Authentication – NetScaler 12 / Citrix ADC 12.1 procedures.

To create an Advanced Authentication Policy:

  1. Go to Security > AAA > Policies > Authentication > Advanced Policies > Policy.
  2. On the right, click Add. You typically create at least one Authentication Policy for each Factor. When you create multiple Authentication Policies for one Factor, Citrix ADC checks each authentication policy in priority order until one of them succeeds.
  3. Use the Action Type drop-down to select the Action Type (e.g. LDAP). Typically each Factor is a different type of Authentication Action.
  4. If you don’t currently have any Actions configured, or if you want to create a new one, click the plus icon (Add button) next to the Action drop-down. The Actions/Servers are created in the normal fashion (not detailed here).
  5. In the Expression box, enter an expression using the Default Syntax. ns_true won’t work because that’s Classic syntax. There’s an Expression Editor link on the right. Or hit Ctrl+Space to see your options. true is a valid Default expression. Click Create when done.
  6. Create more Advanced Authentication Policies as needed for your nFactor design.

Bind First Factor Advanced Authentication Policy to AAA

Only the Advanced Authentication Policies for the first Factor are bound directly to the AAA Virtual Server. The Advanced Authentication Policies for the Next Factors are bound to Authentication Policy Labels as detailed in the next section.

  1. Go to Security > AAA > Virtual Servers.
  2. Edit an existing AAA Virtual Server.
  3. On the left, in the Advanced Authentication Policies section, click where it says No Authentication Policy.
  4. Click where it says Click to select.
  5. Click the radio button next to the Advanced Authentication Policy, and click Select.
  6. In the Binding Details section, if this Advanced Authentication Policy fails, then the Goto Expression determines what happens next. If it is set to NEXT, then the next Advanced Authentication Policy bound to this AAA Virtual Server is evaluated. If it is set to END, or if there are no more Advanced Authentication Policies bound to this AAA Virtual Server, then authentication is finished and marked as failed.
  7. The Select Next Factor field can optionally point to an Authentication Policy Label as detailed in the next section. The Next Factor is only evaluated if this Advanced Authentication Policy succeeds.
  8. Click Bind.

LDAP Group Extraction

Sometimes you only want to extract a user’s groups from Active Directory, but you don’t actually want to authenticate with LDAP. These extracted groups can then be used to select the next authentication Factor.

To configure an LDAP Action/Server for only group extraction:

  1. When creating or editing an LDAP Server/Action, make sure Authentication is unchecked.
  2. In the Other Settings section, make sure Group Attribute and Sub Attribute Name are filled in.

Authentication Policy Label

When configuring the first Factor, you bind two objects directly to the AAA Virtual Server:

  • Login schema – for forms-based authentication
  • Advanced Authentication Policy

When binding the Advanced Authentication Policy to the AAA Virtual Server, there’s a field to Select Next Factor. If the Advanced Authentication Policy succeeds, then the Next Factor is evaluated.

The Next Factor is actually an Authentication Policy Label.

Authentication Policy Labels contain three objects:

  • Login Schema
  • Advanced Authentication Policies
  • Next Factor – the next Authentication Policy Label

Here’s the flow:

  1. User connects to AAA or Citrix Gateway Virtual Server.
  2. If forms-based authentication, the Login Schema bound to the AAA Virtual Server is displayed.
  3. Advanced Authentication Policies bound to the AAA Virtual Server are evaluated.
    1. If the Advanced Authentication Policy succeeds, go to the configured Next Factor, which is an Authentication Policy Label.
      1. If Next Factor is not configured, then authentication is complete and successful.
    2. If the Advanced Authentication Policy fails, and if Goto Expression is Next, then evaluate the next bound Advanced Authentication Policy.
    3. If none of the Advanced Authentication Policies succeed, then authentication failed.
  4. If the Next Factor Authentication Policy Label has a Login Schema bound to it, display it to the user.
  5. Evaluate the Advanced Authentication Policies bound to the Next Factor Authentication Policy Label.
    1. If the Advanced Authentication Policy succeeds, go to the configured Next Factor, which is an Authentication Policy Label.
      1. If Next Factor is not configured, then authentication is complete and successful.
    2. If the Advanced Authentication Policy fails, and if Goto Expression is Next, then evaluate the next bound Advanced Authentication Policy.
    3. If none of the Advanced Authentication Policies succeeds, then authentication failed.
  6. Continue evaluating the Next Factor Authentication Policy Label until authentication succeeds or fails. You can chain together an unlimited number of Authentication Policy Labels.

If you are binding a Login Schema to an Authentication Policy Label, then you only need the Login Schema Profile. There’s no need to create a Login Schema Policy.

Not every Factor needs a Login Schema (logon web page). It’s possible for a prior Factor to gather all of the credential information, and simply pass it on to the next Factor. If you don’t need a Login Schema for a particular Authentication Policy Label, simply select LSCHEMA_INT, which is mapped to noschema. Or create a new Login Schema Profile based on noschema.

Create Authentication Policy Label

To create an Authentication Policy Label:

  1. Authentication Policy Labels are configured at Security > AAA > Policies > Authentication > Advanced Policies > PolicyLabel.
  2. On the right, click Add.
  3. Give the Policy Label a name.
  4. Select a Login Schema Profile. This can be a Login Schema Profile that is set to noschema (LSCHEMA_INT) if you don’t actually want to display anything to the user. Then click Continue.
  5. In the Policy Binding section, click where it says Click to select.
  6. Click the radio button next to an Advanced Authentication Policy that evaluates this Factor. Click Select.
  7. Use the Goto Expression drop-down to select NEXT or END. If you want to bind more Advanced Authentication Policies to this Factor, then select NEXT.
  8. In the Select Next Factor field, if you want to chain another Factor, click where it says Click to select, and bind the next Authentication Policy Label (Next Factor). You can click the Add button to create another Policy Label.
  9. Or don’t select anything, and if this Advanced Authentication Policy succeeds, then authentication is successful and complete. This ends the chaining.
  10. Click Bind when done.
  11. You can click Add Binding to add more Advanced Authentication Policies to this Policy Label (Factor). Note: each Label is a separate factor. If your intent is multi-factor, then create a separate Label for the next factor.
  12. When done, click Done.

Bind Authentication Policy Label

Once the Policy Label (Factor) is created, you bind it to an existing Advanced Authentication Policy binding. This is how you chain Factors together. You can select a Next Factor (Policy Label) in two places:

  • Edit an existing AAA Virtual Server that has an Advanced Authentication Policy already bound to it and edit the binding to include the Next Factor.
  • Edit a different Policy Label, and edit an Advanced Authentication Policy binding to include the Next Factor.

To add a Policy Label Next Factor to a AAA Virtual Server:

  1. Edit an existing AAA Virtual Server that has an Advanced Authentication Policy already bound to it.
  2. On the left, in the Advanced Authentication Policies section, click the existing Authentication Policy bindings.
  3. Right-click an existing binding, and click Edit Binding.
  4. In the Select Next Factor field, click where it says Click to select.
  5. Click the radio button next to the Policy Label for the Next Factor, and click Select.
  6. Click Bind.
  7. The far right shows the Next Factor.
  8. Click Close.

To add a Policy Label Next Factor to a different Policy Label:

  1. Go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > PolicyLabel.
  2. On the right, edit a different Policy Label.
  3. Highlight an existing Advanced Authentication Policy binding, open the Action menu, and click Edit Binding.
  4. In the Binding Details section, next to Select Next Factor, click Click to select.
  5. Click the radio button next to a Policy Label for the next factor, and then click the blue Select button on the top of the window.
  6. Click Bind.
  7. On the far right, you can see the configured Next Factor.
  8. Click Close to close the PolicyLabel.

nFactor for Citrix Gateway

AAA Authentication Profile

Authentication Profile links a AAA Virtual Server to Citrix Gateway and enables nFactor on Citrix Gateway.

  1. Go to Citrix Gateway > Virtual Servers.
  2. On the right, edit an existing Gateway Virtual Server.
  3. On the right, in the Advanced Settings column, click Authentication Profile.
  4. On the left, click the plus icon (Add button) next to the Authentication Profile drop-down.
  5. Give the Authentication Profile a name.
  6. In the Authentication Virtual Server field, click where it says Click to select.
  7. Click the radio button next to the AAA Virtual Server that has Login Schema, Advanced Authentication Policy, and Authentication Policy Labels configured. The AAA Virtual Server does not need an IP address. Click Select.
  8. Then click Create.
  9. And click OK to close the Authentication Profile section.
  10. If one of your Factors is client certificates, then you’ll need to configure SSL Parameters and CA certificate as detailed in the next section.
  11. When you browse to your Gateway, you’ll see the nFactor authentication screens.
  12. Workspace app 1809 and newer with Gateway/ADC 12.1 build 49 and newer should support nFactor authentication. Older clients with older builds do not support nFactor, so those users will have to use a web browser.
    1. CTX223386 nFactor Authentication with Native Clients from NetScaler 11.1: Although Native Receiver Clients can now leverage advanced authentication policies, they still interact using legacy Gateway protocol. That is, Native Clients do not yet support nFactor wire protocol. Gateway acts intelligently based on the clients that are interfacing with it. That is, for Browser client, Gateway redirects to advanced login page with all customizations. For a Native Receiver client, Gateway responds according to the legacy protocol. Since Native clients do not process LoginSchema (even if it is sent), Gateway processes the configured LoginSchema, learns the configured factors, and sends hint to the clients in response to /vpn/index.html.

Gateway Client Certificate Authentication

If one of your authentication Factors is certificate, then you must perform some SSL configuration on the Citrix Gateway Virtual Server:

  1. Go to Traffic Management > SSL > Certificates > CA Certificates, and install the root certificate for the issuer of the client certificates. Certificate Authority certificates do not need key files.
  2. If default SSL Profiles are enabled, then you should have already created an SSL Profile that has Client Authentication enabled.
  3. Go to Citrix Gateway > Virtual Servers, and edit an existing Citrix Gateway Virtual Server that is enabled for nFactor.
  4. If default SSL Profiles are enabled:
    1. Scroll down to the SSL Profile section, and click the pencil icon.
    2. In the SSL Profile drop-down, select the SSL Profile that has Client Authentication enabled and set to OPTIONAL.
  5. If default SSL Profiles are not enabled:
    1. On the left, in the SSL Parameters section, click the pencil icon.
    2. Check the box next to Client Authentication.
    3. Make sure Client Certificate drop-down is set to Optional, and click OK.
  6. On the left, in the Certificates section, click where it says No CA Certificate.
  7. Click where it says Click to select.
  8. Click the radio button next to the root certificate for the issuer of the client certificates, and click Select.
  9. Click Bind.
  10. You might have to also bind any Intermediate CA Certificates that issued the client certificates.

Traffic Policy for nFactor Single Sign-on to StoreFront

When performing Single Sign-on to StoreFront, nFactor defaults to using the last entered password. If LDAP is not the last entered password, then you need to create a Traffic Policy/Profile to override the default nFactor behavior.

  1. Go to Citrix Gateway > Policies > Traffic.
  2. On the right, switch to the Traffic Profiles tab.
  3. Click Add.
  4. Give the Traffic Profile a name.
  5. In the Protocol section, select HTTP.
  6. Set Single Sign-on to ON. Scroll down.
  7. In the SSO Expression fields, enter an HTTP.REQ.USER.ATTRIBUTE(#) expression that matches the indexes specified in the Login Schema.
  8. Click Create.
  9. On the right, switch to the Traffic Policies tab, and click Add.
  10. Give the policy a name.
  11. Select the previously created Traffic Profile.
  12. Enter an Advanced Expression (e.g. true), and click Create.
  13. Edit an existing Citrix Gateway Virtual Server.
  14. Scroll down to the Policies section and click the plus icon.
  15. Select Traffic > Request, and click Continue.
  16. Select the previously created Traffic Policy, and click Bind.

Sample Configurations

From Citrix Docs: Sample deployments using nFactor authentication:

  • Get two passwords up-front, pass-through in next factor. Read
  • Username and 2 passwords with group extraction in third factor. Read
  • Configure nFactor to process the second password before the first password, Read
  • Modify first factor username for second factor. Read
    • NO_AUTHN authentication policy expression checks first factor POST Body login value for UPN format. If true, Next Factor is noschema Login Schema with User Expression that transforms the HTTP.REQ.USER.NAME to DOMAIN\Username before passing to second factor authentication policy.
  • Group extraction followed by certificate or LDAP authentication, based on group membership. Read

  • SAML followed by LDAP or certificate authentication, based on attributes extracted during SAML. Read
  • SAML in first factor, followed by group extraction, and then LDAP or certificate authentication, based on groups extracted. Read
  • Capture email address in first factor, and then choose one of multiple SAML iDP based on email address suffix. Read (Manuel Kolloff)

  • Prefill user name from certificate. Read
  • Certificate authentication followed by group extraction for 401 enabled traffic management virtual servers. Read
  • Certificate fallback to LDAP in same cascade; one virtual server for both certificate and LDAP authentication. Read
  • LDAP in first factor and WebAuth in second factor. Read
  • WebAuth in first factor, LDAP in second factor. Read
  • Domain drop down in first factor, then different policy evaluations based on selected domain. Read

    • Domain drop-down, then send Domain\Username to RADIUS.  Read
  • Google reCAPTCHA first factor, LDAP second. Read (George Spiers)
  • Supporting reCaptcha with NetScaler nFactor. Read
  • CTX225938 nFactor – Customizing UI to Display Images – e.g. Swivel
  • With 12.0 version of NetScaler, EPA is blended into the authentication framework thereby making EPA a conditional or on-demand feature. This reduces the need for multiple virtual servers by allowing for all the clients to gain access to a single virtual server. See CTX223597 Concepts and Entities Used for EPA in nFactor Authentication Through NetScaler.
  • Configure Post-Authentication EPA (Endpoint Analysis) Scan as a Factor. Read
  • Configure Pre-Authentication EPA (Endpoint Analysis) Scan as a Factor. Read
  • Configure EULA (End User License Agreement) as an Authentication Factor. Read
  • Show a drop-down box in the logon form and automatically hide or show certain fields based on drop-down selection. Read

  • Step-up authentication – i.e. one Unified Gateway website needs single factor, while other website needs multi-factor. Read
  • RADIUS authentication with reversed PIN – if user enters reversed PIN, then user is under duress. This sample configuration has some interesting components:  Read  💡
    • Policy Extension Function using the Lua language
      • Usage = HTTP.REQ.BODY(1000).TYPECAST_NVLIST_T(’=’,’&’).VALUE(”passwd1”).RPIN
    • NetScaler Variable of type Map with Expiration timer
      • Responder to set the variable
      • Variable identifies duress state for four hours
    • Custom syslog message (audit messageaction) triggered by a Responder
    • Default Authentication Group to put duressed user on site/farm with Session Recording enabled
    • nFactor sequence:

Certificate auth: If Successful, LDAP only. If Failure, LDAP+RADIUS

This scenario is described in Citrix Blog Post Configuration Notes on nFactor

The authentication process flows like this:

  1. User connects to NetScaler Gateway.
  2. NetScaler Gateway asks user for certificate.
  3. If user selects a certificate, NetScaler Gateway compares certificate signature to the CA certificate that is bound to the NetScaler Gateway. If it doesn’t match, then user certificate is ignored.
  4. Bound to the NetScaler Gateway Virtual Server is an Authentication Profile, which links NetScaler Gateway to AAA nFactor.
  5. Certificate authentication: The lowest priority number authentication policy on the AAA Virtual Server is Certificate. If there’s a valid user certificate:
    1. Extract the user’s userPrincipalName from the certificate.
    2. Next Factor = policy label that displays a logon screen (Single-factor Login Schema)
    3. The username field is pre-populated with the userPrincipalName attribute extracted from the certificate.
    4. User is prompted to enter the LDAP password only.
    5. LDAP policy/server is configured to use userPrincipalName to login to LDAP.
    6. If successful, NetScaler Gateway authentication is complete. Next step is to Single Sign-on to StoreFront.
    7. If LDAP authentication fails, then NetScaler Gateway authentication fails, and the user is prompted to try LDAP-only authentication again.
  6. LDAP authentication: If certificate authentication fails, try next authentication policy bound to the AAA Virtual Server, which is a different LDAP Policy.
    1. Bound to the AAA Virtual Server is a Dual Factor Login Schema that asks for username, LDAP password, and RADIUS password.
    2. LDAP policy/server is configured to use sAMAccountName to login to LDAP. SAMAccountName means users don’t have to enter full userPrincipalName.
    3. If LDAP authentication is successful:
      1. Put username in Credential Index 1 and put password in Credential Index 2. These will later be used by a Traffic Policy to Single Sign-on to StoreFront.
      2. Proceed to next factor (Policy Label), which is RADIUS.
    4. If LDAP authentication fails, NetScaler Gateway login fails, and the user is prompted to try two-factor authentication again.
  7. RADIUS authentication: the second factor Policy Label is configured with Noschema. This means no additional logon form is displayed because the RADIUS password was already collected in the previous factor.
    1. When multiple passwords are collected, they are tried in order. The first password was used by the previous factor. The second password is tried by this factor (Policy Label).
    2. RADIUS policy/profile attempts authentication.
    3. If RADIUS authentication is successful, NetScaler Gateway authentication is complete. Next step is Single Sign-on to StoreFront.
    4. If RADIUS authentication fails, NetScaler Gateway login fails, and the user is prompted to try two-factor authentication again.
  8. Single Sign-on to StoreFront: NetScaler Gateway uses the last password collected by nFactor to Single Sign-on with StoreFront. If the last password is LDAP, then no additional configuration is needed. If the last password is not LDAP, then a Traffic Policy/Profile is needed.
    1. Bound to the NetScaler Gateway Virtual Server is a Traffic Policy.
    2. The Traffic Policy/Profile users Credential Index 1 for username and Credential Index 2 for Password. These are the same indexes configured in the Dual Factor Login Schema.

The order of configuration doesn’t match the authentication flow because some objects have to be created before others.

# Create Auth vServer, bind server cert, bind CA cert for client certificates
# Enable Optional client certificates
add authentication vserver nFactorAAA SSL 0.0.0.0 443
bind ssl vserver nFactorAAA -certkeyName WildCorpCom
bind ssl vserver nFactorAAA -certkeyName CorpRoot -CA -ocspCheck Optional
set ssl vserver nFactorAAA -clientAuth ENABLED -clientCert Optional -ssl3 DISABLED

# Create auth policy for LDAP-UPN. UPN is extracted from certificate.
add authentication ldapAction Corp-UserPrincipalName -serverIP 10.2.2.220 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn "corp\\ctxsvc" -ldapBindDnPassword "MyPassword" -ldapLoginName userPrincipalName -groupAttrName memberOf -subAttributeName CN -secType SSL -passwdChange ENABLED
add authentication Policy Corp-UserPrincipalName -rule true -action Corp-UserPrincipalName

# Create PolicyLabel LDAPPasswordOnly with Single-factor Login Schema
# Login Schema has InitialValue with username from certificate.
add authentication loginSchema SingleAuth -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuth-Corp.xml"
add authentication policylabel LDAPPasswordOnly -loginSchema SingleAuth
bind authentication policylabel LDAPPasswordOnly -policyName Corp-UserPrincipalName -priority 100 -gotoPriorityExpression NEXT

# Create Cert policy and bind to AAA vServer with LDAPPasswordOnly PolicyLabel as Next Factor
# Cert policy must have lower priority number (higher priority) than LDAP-SAM policy
# Cert is evaluated first. If succeed, ask for LDAP password. If fails, ask for two factor.
add authentication certAction Cert_Auth_Profile -userNameField SubjectAltName:PrincipalName
add authentication Policy Cert_Auth_Policy -rule true -action Cert_Auth_Profile
bind authentication vserver nFactorAAA -policy Cert_Auth_Policy -priority 100 -nextFactor LDAPPasswordOnly -gotoPriorityExpression NEXT

# Create LDAP-SAM Auth Policy for two-factor
# Only evaluated if cert auth fails. Login Schema asks for user, password, and passcode.
add authentication ldapAction Corp-Gateway -serverIP 10.2.2.220 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn "corp\\ctxsvc" -ldapBindDnPassword "MyPassword" -ldapLoginName samaccountname -groupAttrName memberOf -subAttributeName CN -secType SSL -passwdChange ENABLED
add authentication Policy Corp-SAMAccountName -rule true -action Corp-Gateway

# Create RADIUS Auth Policy for two-factor
add authentication radiusAction RADIUS-Action -serverIP 10.2.2.42 -serverPort 1812 -radKey MyKey
add authentication Policy RADIUS-Policy -rule true -action RADIUS-Action

# Create Dual-factor Login Schema and bind directly to AAA vServer
# This Login Schema is only shown if Cert auth fails
add authentication loginSchema DualAuth -authenticationSchema "/nsconfig/loginschema/LoginSchema/DualAuth.xml" -userCredentialIndex 1 -passwordCredentialIndex 2
add authentication loginSchemaPolicy DualAuth -rule true -action DualAuth
bind authentication vserver nFactorAAA -policy DualAuth -priority 100 -gotoPriorityExpression END

# Create RADIUS Policy Label with noschema and RADIUS Auth Policy
# Already got passcode from previous factor so don't show Login Schema again
add authentication loginSchema Noschema -authenticationSchema noschema
add authentication policylabel NoSchema-RADIUS -loginSchema Noschema
bind authentication policylabel NoSchema-RADIUS -policyName RADIUS-Policy -priority 100 -gotoPriorityExpression NEXT

# Bind LDAP-SAM Auth Policy to AAA vServer with RADIUS as next factor
# LDAP-SAM Auth Policy must have higher priority number (lower priority) than Cert Policy
bind authentication vserver nFactorAAA -policy Corp-SAMAccountName -priority 110 -nextFactor NoSchema-RADIUS -gotoPriorityExpression NEXT

# Create Authentication Profile to link AAA with Gateway. Bind to Gateway.
add authentication authnProfile nFactor -authnVsName nFactorAAA -AuthenticationHost aaa.corp.com
add vpn vserver gateway.corp.com SSL 10.2.2.220 443 -icaOnly ON -dtls ON -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -appflowLog ENABLED -authnProfile nFactor

# Enable Optional Client certs on Gateway
set ssl vserver gateway.corp.com -clientAuth ENABLED -clientCert Optional -ssl3 DISABLED
bind ssl vserver gateway.corp.com -certkeyName CorpRoot -CA -ocspCheck Optional

# Create Traffic Policy to SSON to StoreFront. Bind to Gateway.
add vpn trafficAction nFactorSSO http -kcdAccount NONE -userExpression "http.req.user.attribute(1)" -passwdExpression "http.req.user.attribute(2)"
add vpn trafficPolicy nFactorSSO ns_true nFactorSSO
bind vpn vserver gateway.corp.com -policy nFactorSSO -priority 100

Group Extraction, followed by LDAP (Active Directory), or Azure MFA (NPS)

Azure MFA is available as a plug-in for Microsoft Network Policy Server (NPS), which is a Microsoft RADIUS server and built-in Windows Server Role.

NPS performs both AD authentication, and Azure MFA authentication. NetScaler sends the user’s AD password to NPS. NPS verifies AD, and then the NPS Azure MFA plug-in calls the user (or push notification to the user). If both AD and MFA are successful, then NPS sends back RADIUS-Accept.

Summary:

  1. First factor Login Schema asks for Username only.
    1. LDAP Group Extraction (with Authentication disabled) reads the user’s groups from AD.
  2. Second factor checks for group membership and sends to one of two different third factors.
  3. If user is in LDAP Group, or Client IP is on internal network, then perform LDAP-only authentication.
    1. Login schema asks for AD password.
    2. LDAP Policy authenticates with LDAP Server (Active Directory).
  4. Otherwise, perform RADIUS (two-factor) authentication.
    1. Login schema asks for AD password.
      • Note: NPS with MFA plugin only needs the AD password. Alternatively, you could use a Login Schema that asks for both LDAP password and RADIUS password.
    2. RADIUS Policy uses the entered AD password to authenticate to Microsoft NPS and Azure MFA.

CLI Commands. Note, these objects are created in the required order, which is backwards from how you would want to configure them.

  1. Add cert for AAA vServer. Link the cert to Intermediate. 
    add ssl certKey WildcardCorpCom -cert WildcardCorpCom.pfx -key WildcardCorpCom.pfx -inform PFX -passcrypt "myPassword"

link ssl certKey WildcardCorpCom Intermediate
  2. Enable AAA feature if not already enabled. 
    enable ns feature AAA
  3. Create first factor LDAP Action (LDAP Server) and LDAP Policy (expression) for Group Extraction. Authentication is disabled. This is the first factor that is bound directly to the AAA vServer. 
    add authentication ldapAction LDAP-Corp-GroupExtract -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword MyPassword -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED

add authentication Policy LDAP-Corp-GroupExtract -rule true -action LDAP-Corp-GroupExtract
  4. Create a third-factor LDAP Action (LDAP Server) and Authentication Policy (expression) for Active Directory Authentication. This is the authentication factor if user is in the LDAP Users group. 
    add authentication ldapAction LDAP-Corp -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword MyPassword -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED

add authentication Policy LDAP-Corp -rule true -action LDAP-Corp
  5. Create a third-factor RADIUS Action (RADIUS Server) and Authentication Policy (expression) for NPS. 
    add authentication radiusAction NPS -serverIP 10.2.2.42 -serverPort 1812 -radKey MySecret

add authentication Policy NPS -rule true -action NPS
  6. Create the second factor NO_AUTHN authentication policies to determine the next factor based on the user’s group membership. NO_AUTHN means don’t authenticate. Instead, these policies will have a Next Factor that points to the Authentication Policies that we created earlier. If the policy expression is true, then go to Next Factor. Next Factor is configured later when binding these policies to the second factor PolicyLabel. Note: the group name is case sensitive and must match the Active Directory group name. 
    add authentication Policy LDAP-Only -rule "http.REQ.USER.IS_MEMBER_OF(\"LDAP\") || client.IP.SRC.IN_SUBNET(10.2.2.0/24)" -action NO_AUTHN

add authentication Policy TwoFactor -rule "client.IP.SRC.IN_SUBNET(10.2.2.0/24).NOT" -action NO_AUTHN
  7. Create first factor Login Schema Profile for username-only group extraction. You can copy the built-in OnlyUsername.xml and modify it with your desired labels. Since this Login Schema Profile is bound to the AAA vServer, it needs a Login Schema Policy (expression). The other two Login Schema Profiles are bound to PolicyLabels and thus don’t need Login Schema Policies. 
    add authentication loginSchema OnlyUsername -authenticationSchema "/nsconfig/loginschema/LoginSchema/OnlyUsername.xml"

add authentication loginSchemaPolicy OnlyUsername -rule true -action OnlyUsername
  8. Create third factor Login Schema Profile for AD Authentication. The .xml file is copied from the built-in PrefillUserFromExpr.xml but with modified labels for AD authentication. The username is pre-filled in from the first factor. 
    add authentication loginSchema LDAPPasswordOnly -authenticationSchema "/nsconfig/loginschema/LDAPPassword.xml"
  9. Create third factor Login Schema Profile for NPS Authentication. The .xml file is copied from the built-in PrefillUserFromExpr.xml but with modified labels for NPS authentication. The username is pre-filled in from the first factor. 
    add authentication loginSchema NPSPasswordOnly -authenticationSchema "/nsconfig/loginschema/NPSPassword.xml"
  10. Create third factor PolicyLabel for Active Directory authentication with Active Directory Login Schema and Active Directory Authentication Policy. 
    add authentication policylabel LDAPPasswordAuth -loginSchema LDAPPasswordOnly

bind authentication policylabel LDAPPasswordAuth -policyName LDAP-Corp -priority 100 -gotoPriorityExpression NEXT
  11. Create third factor PolicyLabel for NPS authentication with NPS Login Schema and NPS Authentication Policy. 
    add authentication policylabel NPSPasswordAuth -loginSchema NPSPasswordOnly

bind authentication policylabel NPSPasswordAuth -policyName NPS -priority 100 -gotoPriorityExpression NEXT
  12. Create second factor PolicyLabel with Policies that choose Next Factor. This PolicyLabel is processed before the two we just created. 
    add authentication policylabel CheckForAuthType -loginSchema LSCHEMA_INT

bind authentication policylabel CheckForAuthType -policyName TwoFactor -priority 90 -gotoPriorityExpression NEXT -nextFactor NPSPasswordAuth

bind authentication policylabel CheckForAuthType -policyName LDAP-Only -priority 100 -gotoPriorityExpression NEXT -nextFactor LDAPPasswordAuth
  13. Create AAA vServer. Bind Login Schema Policy (username only) and Group Extraction Policy. 
    add authentication vserver AAA SSL 10.x.x.218 443
bind authentication vserver AAA -policy OnlyUsername -priority 100 -gotoPriorityExpression END
bind authentication vserver AAA -policy LDAP-Corp-GroupExtract -priority 100 -nextFactor CheckForAuthType -gotoPriorityExpression NEXT
  14. Perform additional steps not detailed here:
    1. For Traffic Management:
      1. Create a Session Policy and bind it to the AAA vServer.
      2. Enable authentication on the Load Balancing or Content Switching vServer.
    2. For NetScaler Gateway, create an Authentication Profile, and bind it to the Gateway vServer.

Citrix Federated Authentication Service (SAML) 2411

Last Modified: Dec 4, 2024 @ 2:28 am

1,097 Comments

Navigation

This article applies to Federated Authentication Service (FAS) versions 2411, 2402 LTSR CU1, 2203 LTSR CU5, 1912 LTSR CU9, and all other versions 7.9 and newer.

Change Log

Overview

Citrix Federated Authentication Service (FAS) enables users to log in to Citrix Gateway and Citrix StoreFront using SAML authentication.

With SAML, Citrix Gateway and StoreFront do not have access to the user’s password and thus cannot perform single sign-on to the VDA. FAS works around this limitation by using issuing certificates that can be used to logon to the VDA.

  • StoreFront asks Citrix Federated Authentication Service (FAS) to use a Microsoft Certificate Authority to issue Smart Card certificates on behalf of users.
  • The certificates are stored on the FAS server.
  • The VDA requests the user’s certificate from FAS so it can complete the VDA Windows logon process.

FAS can be used for any authentication scenario where the user’s password is not provided.

Requirements:

  • Microsoft Certification Authority (CA) in Enterprise mode.
    • When configuring FAS, you tell it what CA server to use.
    • You can build a new CA server just for FAS.
    • You can install CA on the FAS server.
  • Domain Controllers must have Domain Controller certificates. See CTX218941 FAS – Request not supported.
    • The certificates on the Domain Controllers must support smart card authentication. Certificates created using the Microsoft CA certificate template named Domain Controller Authentication supports smart cards. Manually created Domain Controller certificates might not work. See CTX270737 for the Domain Controller certificate requirements.

  • Citrix Virtual Apps and Desktops or XenApp/XenDesktop 7.9 or newer
  • StoreFront 3.6 or newer
  • Citrix Gateway.
    • StoreFront 3.9 and newer also support SAML authentication natively without Citrix ADC.
  • SAML in an nFactor (Authentication Virtual Server) configuration works in both browsers and Workspace app.
  • For multiple domains, see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.

Configuration overview:

  1. Build one or more FAS servers.
    • For security reasons, FAS should be its own server and not installed on a Delivery Controller.
  2. Upload Certificate Templates to Active Directory and configure a CA server to issue certificates using the new templates.
    • Enterprise Admin permissions are needed to upload the Certificate Templates.
    • One of the Certificate Templates is for Smart Card logon to Citrix VDA.
    • The other two Certificate Templates are to authorize FAS as a certificate registration authority.
    • The registration authority certificate does not renew automatically so be prepared to renew it manually every two years. See Renew registration authority certificates at Citrix Docs.
  3. Install the Citrix FAS group policy .admx template into PolicyDefinitions.
  4. Create a group policy object (GPO) and configure the GPO with the addresses of the FAS servers.
    • The GPO must apply to FAS servers, StoreFront servers, and every VDA. It does not need to apply to Delivery Controllers, but there’s no harm in applying it to the Delivery Controllers.
  5. Authorize FAS to request certificates from a Microsoft CA server.
  6. Configure FAS Rules to permit StoreFront servers to request FAS to generate certificates for users and permit VDA machines to retrieve the certificates from FAS.
  7. Configure StoreFront to use FAS for VDA single sign-on.

Links:

From Citrix CTX225721 Federated Authentication Service High Availability and Scalability: you can build multiple FAS servers. Enter all FAS server FQDNs in the Group Policy. StoreFront will then use a hashing algorithm on the username to select a FAS server.

  1. If you have less than 10K users, one FAS server with 4 vCPUs (2.5Ghz) should be sufficient.
  2. You will require a minimum of one FAS server (with 8 vCPUs) per 25,000 users if all users expect to be able to logon under cold start conditions (no keys or certificates cached) within 60-90 minutes.
  3. A single FAS server can handle greater than 50K users under warm start conditions (keys and certificates pre-cached)
  4. One reserve FAS server for every four FAS servers for “Day 1” cold start (Users get new keys/certificates) & disaster recovery scenarios
  5. Split the FAS Certificate Authority from Certificate Authority that performs other tasks for both security and scalability purposes.

Michael Shuster explains the Group Policy configuration for FAS in multiple datacenters at HowTo: Active-Active Multi-Datacenter Citrix FAS.

Also see the Citrix Federated Authentication Service Scalability whitepaper.

Federated Authentication Service Versions

The most recent Federated Authentication Service Current Release is version 2411.

For LTSR versions of Citrix Virtual Apps and Desktops (CVAD) and StoreFront, install the version of FAS that comes with the CVAD LTSR version.

Install/Upgrade Federated Authentication Service

The service should be installed on a secure, standalone server that does not have any other Citrix components installed. The FAS server stores user authentication keys, and thus security is paramount.

  1. On the Federated Authentication Service server, go to the Citrix Virtual Apps and Desktops, or XenDesktop 7.9, or newer ISO, and run AutoSelect.exe. Or you can download the standalone installer and run that.
  2. In the lower half of the window, click Federated Authentication Service.
  3. In the Licensing Agreement page, select I have read, understand, and accept the terms of the license agreement, and click Next.
  4. In the Core Components page, click Next.
  5. In the Firewall page, click Next.
  6. In the Summary page, click Install.
  7. The installer will probably ask for a restart.

    1. After the reboot, and after logging in again, you might see a Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window. Don’t click anything yet.
    2. Go to the Citrix_Virtual_Apps_and_Desktops_7_2411.iso file and mount it.
    3. Go back to the Locate ‘Citrix Virtual Apps and Desktops 7’ installation media window.
    4. On the left, expand This PC, and click the DVD Drive.
    5. Click Select Folder.
  8. Click Finish.

FAS Group Policy

Configure a Group Policy that instructs StoreFront servers and VDAs on how to locate the FAS servers.

  1. On the Federated Authentication Service server, browse to C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions. Copy the files and folder.
  2. Go to \\domain.com\SYSVOL\domain.com\Policies\PolicyDefinitions and paste the files and folder. If PolicyDefinitions doesn’t exist in SYSVOL, then copy them to C:\Windows\PolicyDefinitions instead.
  3. Edit a GPO that applies to all StoreFront servers, all Federated Authentication Service servers, and all VDAs.
  4. Navigate to Computer Configuration > Policies > Administrative Templates > Citrix Components > Authentication.
  5. Edit the setting Federated Authentication Service.
  6. Enable the setting and click Show.
  7. Enter the FQDN of the Federated Authentication Service server. You can add more than one Federated Authentication Service server.
  8. Click OK twice.
  9. On the Federated Authentication Service server, and VDAs, run gpupdate.
  10. On the FAS server, and on VDAs, look in the registry at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses. Make sure this key and value exists. The number one cause why FAS doesn’t work is because this key is missing from VDAs. The FAS Address GPO must apply to VDAs too.
  11. If the VDAs and Users are in different domains, see CTX220497 Users from one AD Domain not able to get FAS user certificates from another trusted domain: add the Citrix StoreFront Servers, FAS server and VDA servers to the Windows Authorization Access Group in the users’ domain. Also see Deployment Guide: Multi-Domain FAS Architecture at Citrix Tech Zone.
  13. By default, the VDAs will verify the certificates aren’t revoked by downloading the Certificate Revocation List. You can disable CRL checking by configuring HKEY_Local_Machine\System\CurrentControlSet\Control\LSA\Kerberos\Parameters\UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors (DWORD) = 1 as detailed at CTX217150 Unable to login using the FAS Authentication – Getting Stuck on Please wait for local session manager.
  14. If your VDAs have third party credential providers (e.g., Duo), then it might interfere with FAS Single Sign-on.

FAS 1909+ Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

FAS 1909 and newer have a different configuration GUI than FAS 1906 and older.

Here are 1909 and newer GUI configuration instructions:

  1. Log into the FAS server as an Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. In the tab named Initial Setup, in the row named Deploy certificate templates, click Deploy.
  4. Click OK to deploy the templates to Active Directory.
  5. In the row named Set up a certificate authority, click Publish.
  6. Select an Enterprise Certificate Authority that will be issue the FAS certificates and click OK.
  7. In the row named Authorize this service, click Authorize.
  8. Select a CA that will issue this FAS server a Registration Authority certificate. Later, you will need to open the Certificate Authority console on the chosen server. Click OK.
  9. The row named Authorize this service has a new icon indicating it is waiting on the registration authority certificate to be approved.
  10. Open the Certification Authority console and point it to the CA server. In the Pending Requests node, find the certificate request for the FAS server and Issue it.
  11. Back in the FAS Administration Console, on the top right, click Refresh.
  12. The row named Authorize this service should now have a green check mark.
  13. In the row named Create a rule, click Create.
  14. In the Rule name page, leave it set to Create the default rule and click Next.
  15. In the Template page, click Next.
  16. In the Certificate authority page, select the CA that has the issuing templates configured and click Next. You can select more than one CA server.
  17. In the In-session use page, click Next.
  18. In the Access control page, click the link to Manage StoreFront access permissions.
  19. In the Permission for StoreFront Servers page, add your StoreFront servers and give them the permission Assert Identity. Click OK.
  20. Back in the Create Rule wizard, click Next.
  21. In the Restrictions page, you can optionally reduce the VDAs that are authorized to use FAS. Click Next.
  22. In the Summary page, click Create.
  23. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • In the row named Authorize this service, you can click the link for authorization certificate to see when it expires. Before expiration, use the Reauthorize button on the right of the same row.
  24. Jump ahead to Certificate Templates.

FAS 1906 and older Configuration

If you prefer to script the FAS configuration, then see Citrix Blog Post Automating the Citrix Federated Authentication Service with PowerShell.

Here are GUI configuration instructions for FAS 1906 and older:

  1. Log into the FAS server as a Domain Administrator or Enterprise Administrator that can upload certificate templates to Active Directory.
  2. On the FAS server, from the Start Menu, run Citrix Federated Authentication Service as administrator. Make sure you run it elevated.
  3. The Federated Authentication Service FQDN should already be in the list (from group policy). Click OK.
  4. In Step 1: Deploy certificate templates, click Start.
  5. Click OK to add certificate templates to Active Directory. Sufficient permission is required.
  6. In Step 2: Setup Certificate Authority, click Start.
  7. Select a Certificate Authority to issue the certificates, and click Ok.
  8. In Step 3: Authorize this Service, click Start.

    • Step 3 automatically submits an online request for the Registration Authority certificate to the CA and stores the non-exportable private key in the standard Microsoft Enhanced RSA and AES Cryptographic Provider.
    • Alternatively, you can submit the certificate request manually, and store the private key in TPM or HSM as detailed at Federated Authentication Service private key protection at Citrix Docs. When running New-FasAuthorizationCertificateRequest, the -UseTPM switch is optional.
  9. Select the issuing Certificate Authority, and click OK.

    • Authorize this Service only lets you select one Certificate Authority. If you want to load balance certificate requests against multiple Certificate Authorities, then see Set up multiple CA servers for use in FAS at Citrix Docs. 
      Set-FasCertificateDefinition -Name default_Definition -CertificateAuthorities @("ca1.corp.local\CA1.corp.local", "ca2.corp.local\ca2.corp.local")
  10. Step 3 is now yellow.
  11. On the Microsoft CA server, go to the Certification Authority Console > Pending Requests. Find the pending request, and Issue it.
  12. In a minute or two, Federated Authentication Service will recognize the issued certificate and Step 3 will turn green.
  13. After FAS authorization with the CA, in the FAS Configuration tool, switch to the User Rules tab.
  14. Use the Certificate Authority drop-down to select the issuing Certificate Authority.
  15. Use the Certificate Template drop-down to select the Citrix_SmartcardLogon template.
  16. Click Edit next to List of StoreFront servers that can use this rule.
  17. Remove Domain Computers from the top half, and instead add your StoreFront servers. You could add an Active Directory security group instead of individual StoreFront servers.
  18. On the bottom half, make sure Assert Identity is Allowed. Click OK.
  19. By default, all users and all VDAs are allowed. You can click the other two Edit boxes to change this.
  20. When done, click Apply.
  21. Click OK when you see Rule updated successfully.
  22. The FAS Registration Authority certificate expires in two years. You’ll need to manually renew the FAS Registration Authority certificate before it expires. Put a notification on your calendar. For details, see Renew registration authority certificates at Citrix Docs.
    • To see the expiration date of the authorization certificate, run the following PowerShell command after running add-pssnapin Citrix.Authentication.FederatedAuthenticationService.V1: 
      Get-FasAuthorizationCertificate -FullCertInfo -address myFASServer

Certificate Templates

The deployed FAS Certificate Templates from older versions of FAS have Autoenroll enabled. Newer versions of FAS (e.g., 2203) no longer have Autoenroll enabled.

  1. Open the Certificate Templates console. One option is to open the Certification Authority console, right-click Certificate Templates, and then click Manage.
  2. There should be three templates with names starting with Citrix_. Open the properties on each one.
  3. On the Security tab, highlight each group assigned to the template.
  4. On the bottom half, uncheck the box in the Autoenroll row but leave Enroll checked. Perform this step for every group assigned to this template. Then click OK.
  5. Repeat disabling autoenroll for the other two templates.

The Registration Authority certificate templates are permitted to all Domain Computers. You might want to change that.

  1. Open the Properties of one of the Citrix_RegistrationAuthority certificate templates.
  2. On the Security tab, remove Domain Computers.
  3. Add your FAS servers and enable the Enroll permission.
  4. Repeat for the other Registration Authority certificate.

To further restrict who can be issued certificates, go to your Certificate Authority’s Properties and use the Enrollment Agents tab to restrict enrollment agents.

StoreFront Configuration

Once FAS is enabled on a StoreFront store, it applies to all connections through that store, including password-based authentications. One option is to create a new store just for FAS users.

  1. Check the registry at at HKLM\Software\Policies\Citrix\Authentication\UserCredentialService\Addresses to confirm that the group policy with FAS addresses has been applied to the StoreFront servers.
  2. On the StoreFront 3.6 or newer server, run the following elevated PowerShell command: 
    & "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1"
  3. Run the following commands. Adjust the store name as required. 
    $StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "FASClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider "FASLogonDataProvider"
  4. If you have multiple StoreFront servers, Propagate Changes.
  5. In Web Studio (CVAD 2212 and newer), go to Settings and Enable XML Trust.

    • Or on a Citrix Delivery Controller, run the following PowerShell command: 
      Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true

If you ever need to disable FAS on StoreFront, run the following commands. Adjust the store name as required.

$StoreVirtualPath = "/Citrix/Store"
$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store
Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "standardClaimsFactory"
Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider ""

SAML Configuration

SAML Flow

SAML flows like this:

  1. (Optional) User goes to the web application aka Service Provider (e.g. Citrix Gateway).
    • The Service Provider (SP) redirects the user’s browser to the Identity Provider’s (IdP) SAML Single Sign-on (SSO) URL and includes an authentication request in the Redirect. The IdP SSO URL might be different for each Service Provider.
    • The Authentication Request from the Service Provider includes a Service Provider Entity ID. The IdP matches the SP Entity ID with an entry in its database so it knows which SP is making the authentication request. The Entity ID must match on both the SP and the IdP.
    • If the Authentication Request is signed by the Service Provider’s certificate private key, then the IdP will verify the signature using the Service Provider’s certificate public key. In this scenario, the Service Provider’s certificate (without private key) must be loaded into the IdP.
  2. The user authenticates to the IdP, typically using Multi-factor Authentication.
    • If the user was redirected from the SP, then the IdP already knows which SP to authenticate with.
    • If the user went directly to the IdP, then the user typically needs to click an icon representing the web application (Service Provider).
  3. IdP generates a SAML Assertion containing the user’s userPrincipalName or email address.
    • Configure the IdP to include the user’s UPN or email address in the NameID field of the assertion. SAMAccountName won’t work with Citrix FAS.
    • The SAML Assertion also includes the Service Provider’s Entity ID. The ID in the Assertion must match the ID configured on the SP.
    • IdP signs the SAML Assertion using an IdP certificate private key.
    • IdP has a configuration for the SP that includes a SAML Assertion Consumer Service (ACS) URL. IdP redirects the user’s browser to the SP’s ACS URL and POST’s the SAML Assertion.
      • The ACS URL on Citrix Gateway ends in /cgi/samlauth
  4. SP uses the IdP certificate’s public key to verify the signature on the SAML Assertion.
    • The IdP’s certificate (without private key) is installed on the Citrix ADC so it can verify the Assertion’s signature.
  5. SP extracts the user’s userPrincipalName from the Assertion and uses the UPN for Single Sign-on to StoreFront and the rest of the Citrix components.
    • Note that the SP does not have access to the user’s password and thus that’s why we need Citrix FAS to generate certificates for each user.

Configure the SAML IdP

You typically start the configuration on the Identity Provider (IdP). Every IdP has unique instructions. Search Google for your IdP and Citrix ADC and you might find a IdP-specific guide. After IdP configuration, you download the IdP’s certificate and copy the IdP’s SSO URL so you can configure them on Citrix ADC.

Azure AD as SAML IdP

  1. In Azure Portal, go to Azure Active Directory.
  2. On the left, click Enterprise applications.
  3. In the new blade that appears, on the All applications page, on the right, click New application.
  4. In the All Categories view of the gallery, on the top right, click Non-gallery application.
  5. Give the application a descriptive name. Azure AD shows this name in the myapps portal. Click Add.
  6. After the application is created, on the left, in the Manage section, click Single sign-on.
  7. On the right, click the big button for SAML.
  8. In section 1 labelled Basic SAML Configuration, click the pencil icon.
  9. In the Identifier (Entity ID) field, enter an identifier in URI format. Usually it matches the FQDN of the Citrix Gateway and can be entered in https://gateway.corp.com format. You’ll later need to specify the exact same Identifier on the Citrix ADC.
  10. In the Reply URL (Assertion Consumer Service URL) field, enter a URL similar to https://mygateway.company.com/cgi/samlauth. The path must be /cgi/samlauth. The scheme should be https. And the FQDN is your Citrix Gateway’s FQDN.
  11. Click Save. Then you might have to click the x on the top right to make it go away.
  12. In section 2 labelled User Attributes & Claims, notice that it defaults to sending the userprincipalname. You can click the pencil to change the attribute used for the Name identifier value. Whatever value you send will need to match the userPrincipalNames of local Active Directory accounts (aka shadow accounts).


  13. In section 3 labelled SAML Signing Certificate, click the Download link in the Certificate (Base64) line.
  14. Citrix ADC 12.1 and newer support SAML metadata so feel free to copy the App Federation Metadata Url field.
  15. If you are running NetScaler 12.0 or older, then you will need to copy the Login URL field from section 4 labelled Set up gateway5.corp.com
  16. On the left, under Manage, click Users and groups.
  17. Use the normal process to assign Azure AD users and groups to this application. Click Assign.
  18. Jump to the section named Citrix ADC SAML Configuration.

ADFS as SAML IdP

The screenshots in this section use ADFS as an example IdP. Your IdP will be different.

  1. In your SAML IdP, create a Relying Party Trust (aka service provider trust) or new Application.
  2. Since we’re configuring the IdP before we configure Citrix ADC and thus don’t have access to the SP metadata, select the option to Enter data about the relying party manually.
  3. For the Assertion Consumer Service URL (aka relying party service URL), enter the URL to your Citrix Gateway with /cgi/samlauth appended to the end (e.g. https://gateway.corp.com/cgi/samlauth)
  4. Enter a Relying party trust identifier in URI format. You must specify the same identifier (Issuer Name) on the Citrix ADC as detailed in the next section.
  5. Configure the SAML IdP to send email address or User-Principal-name as Name ID. Citrix ADC receives the Name ID and sends it to StoreFront. StoreFront will look in Active Directory for an account with userPrincipalName that matches the Name ID.
  6. Citrix ADC will sign the authentication requests it sends to the IdP. On the Citrix ADC, you will soon configure the Citrix ADC SAML SP signing certificate with private key that signs the authentication requests that are sent to the IdP. In your SAML IdP, import the same Citrix ADC SAML SP signing certificate but without the private key.
  7. Copy the SAML authentication URL (aka Token Issuance URL) from your SAML IdP. You’ll need to enter this same URL on your Citrix ADC later.
  8. Export the IdP Token-signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping, etc.

Citrix ADC SAML Configuration

SAML Server/Action

  1. Instructions for Citrix ADC 13.0, Citrix ADC 12.1, NetScaler 12.0, and NetScaler 11.1 are essentially the same.
    • Citrix ADC 12.1 and newer support SAML Metadata while older versions of NetScaler do not support SAML Metadata.
    • NetScaler 11 is very similar, except Certificates are in a different place in the NetScaler menu tree.
  2. Workspace app support – If you bind a SAML Authentication Policy directly to the Gateway Virtual Server (no nFactor/AAA), then Workspace app and Gateway VPN plug-in won’t work. To support SAML with Workspace app and Gateway VPN plug-in, configure nFactor (Authentication Virtual Server with Authentication Profile) instead of directly on the Gateway Virtual Server.
  3. IdP Signing Certificate – On Citrix ADC, if you are not importing IdP metadata, then manually import the IdP SAML token-signing certificate (without private key) under Traffic Management > SSL > Certificates > CA Certificates. Citrix ADC uses this certificate to verify the signature of the SAML assertion from the IdP.
    Note: when you later create the SAML Action on Citrix ADC, there’s a place to add a SAML certificate. Unfortunately, the SAML Action is trying to import the wrong type of certificate since it wants the private key, which you don’t have access to. If you import the certificate here under CA Certificates, then there’s no prompt for private key.


    • SAML IdP certificates are shown in the Unknown Certificates node.
  4. If you want ADC to sign the authentication requests it sends to the IdP, then do the following:
    1. Move up two nodes to Server Certificates and Import or create a SP SAML signing certificate with private key. This can be the same certificate used on Citrix Gateway. Or a more common practice is to create a self-signed certificate.

    2. You’ll also need to import this SAML SP signing certificate (without private key) to your SAML IdP so it can verify the SAML authentication request signature from the Citrix ADC.
  5. Go to Citrix Gateway > Policies > Authentication > SAML. The quickest way to get here is to enter SAML in the search box on top of the menu.
  6. On the right, switch to the tab labelled Servers, and click Add.
  7. In the Name field, give the SAML Action a name that indicates the IdP’s name.
  8. If your Citrix ADC is 12.1 or newer, then get the SAML Metadata URL (or file) from the IdP.

    1. In the SAML Server on Citrix ADC, in the SAML IDP Metadata URL field, paste in the URL. ADC should be able to extract the IdP’s certificate from the Metadata URL.
    2. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    3. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. To avoid relay state “does not match” error, make sure users enter the Gateway URL instead of using a bookmark. 💡 
      AAA.LOGIN.RELAYSTATE.EQ("https://gateway5.corp.com/")

    4. Scroll down and click More.
    5. You can optionally check Force Authentication to prevent users from doing SAML authentication using cached credentials. This prompts for MFA every time the user accesses Citrix Gateway.
    6. Scroll down and click Create.
    7. Edit the SAML Server again.
    8. If you uncheck the box next to Import Metadata, you can see the fields that it filled in for you. Unfortunately, other fields must be configured manually as detailed soon.
  9. Configure the SAML Server based on the data provided by your IdP. If you imported Metadata, then some of the fields might already be populated.
    1. For IDP Certificate Name, select the SAML IdP’s certificate that was exported from the SAML IdP and imported to Citrix ADC. Citrix ADC will use this IdP certificate to verify SAML assertions from the IdP.
      Note: the Add button here does not work correctly. Instead, if you need to import the SAML IDP certificate, then do it at the CA Certificates node as detailed earlier in this section.
    2. For Redirect URL, enter the URL to the SAML IdP’s authentication page. Citrix Gateway will redirect users to this URL. For ADFS, enter your ADFS URL appended with /adfs/ls (e.g. https://adfs.corp.com/adfs/ls). For other IdP’s, get the URL from your IdP.
    3. For User Field, enter the name of the SAML Claim from the IdP that contains the value that matches the userPrincipalName of your local Active Directory users (aka shadow accounts). This defaults to the NameID field, but you might have to use a different claim, like emailaddress.
    4. In the Issuer Name field, enter the ID that the SAML IdP is expecting for the Relying Party.  This Issuer Name must match the name you configured on the IdP’s Relying Party (Service Provider) Trust. Azure AD calls this the Identifier or Entity ID.
    5. Near the bottom, configure a Relay State Rule to prevent session hijack. It should check the Relay State field to make sure it matches the URL that users using to reach the Gateway Virtual Server. Make sure you include the forward slash at the end of the URL. Sample expression below. Pattern set is also possible. See CTX316577 for details. 💡
    6. Optionally, for Signing Certificate Name, select the SAML SP certificate (with private key) that Citrix ADC will use to sign authentication requests to the IdP. This same certificate (without private key) must be imported to the IdP, so the IdP can verify the authentication request signature. This field usually isn’t needed by most IdPs.
    7. Scroll down and click More.
    8. Citrix ADC defaults to SHA1. You might have to change the Signature Algorithm and Digest Method to SHA256.
    9. Review the other settings as needed by your IdP. Click Create when done.

SAML Policy – Advanced (nFactor) Method

Workspace app and Gateway Plugin (i.e. VPN plugin) require nFactor (Advanced Authentication Policies) to support SAML authentication.

Licensing – nFactor requires NetScaler ADC Advanced Edition or NetScaler ADC Premium Edition. The newest builds of NetScaler ADC 13 have added nFactor support for NetScaler ADC Standard Edition, but the configuration of an Authentication Virtual Server is not directly accessible from the main menu. If you only have Standard Edition, then do the following to get to the Authentication Virtual Server:

  1. Go to Citrix Gateway > Virtual Servers and edit one.
  2. On the right, add the Authentication Profile section.
  3. On the left, in the Authentication Profile section, click Add to create an Authentication Profile.
  4. In the Authentication Virtual Server row, click Add to create an Authentication Virtual Server.
  5. The rest of the nFactor configuration is similar to what’s detailed below.

If you prefer to configure the older Classic Method, which doesn’t work with Workspace app, then skip to the Classic Method.

Do the following to create an Advanced Authentication Policy, an Authentication Virtual Server, and bind it to the Gateway Virtual Server:

  1. In the left menu, expand Security, expand AAA – Application Traffic, expand Policies, expand Authentication, expand Advanced Policies, and then click Policy.
  2. On the right, click the button labelled Add.

    1. Change the drop-down for Action Type to SAML.
    2. Change the drop-down for Action to the SAML Action you created earlier.
    3. In the box labelled Expression, enter true.
    4. Give the policy a name and click Create.
  3. In the left menu, expand Security, expand AAA – Application Traffic and then click Virtual Servers.
  4. On the right, click the button labelled Add.

    1. Change the drop-down named IP Address Type to Non Addressable and then click OK.
  5. You can optionally bind a Server Certificate. If you don’t bind a certificate, then the AAA vServer will be down but it will still work. It doesn’t matter what certificate you choose. Click Continue when done.
  6. On the left, in the section named Advanced Authentication Policies, click the row that says No Authentication Policy.

    1. Click where it says Click to select.
    2. Click the small circle to the left of the SAML Policy that you created earlier. Then click the blue button labelled Select at the top of the screen.
    3. There’s no need to configure Select Next Factor unless you want to bind an LDAP Policy with Authentication Disabled so you can extract groups from Active Directory and use those groups for Gateway authorization. This configuration procedure is detailed in the next section.
    4. Click the blue button labelled Bind at the bottom of the window.
  7. Click Continue,
  8. At the bottom of the page, click Done to finish creating the AAA vServer.
  9. In the left menu, expand Citrix Gateway and click Virtual Servers.
  10. On the right, edit your existing Gateway Virtual Server.
  11. On the right side of the screen, in the Advanced Settings column, click Authentication Profile.
  12. On the left side of the screen, find the Authentication Profile section and then click the button labelled Add.
  13. Click where it says Click to Select and then select your AAA vServer.
  14. Give the Authentication Profile a name and then click the blue button named Create.
  15. Make sure you click the blue OK button before you click Done. If you don’t click OK then your changes won’t be saved.

Here are some sample CLI commands for this nFactor SAML configuration.

# SAML Actions
# ------------
add authentication samlAction "Azure AD" -samlIdPCertName AzureADSAML -samlSigningCertName WildcardCorpCom -samlRedirectUrl "https://login.microsoftonline.com/815e26a9-4a9b/saml2" -samlIssuerName gateway5.corp.com -Attribute1 emailaddress -logoutURL "https://login.microsoftonline.com/815e26a9/saml2" -logoutBinding REDIRECT -relaystateRule "aaa.LOGIN.RELAYSTATE.EQ(\"https://gateway5.corp.com/\")"

# SAML Authentication Policies
# ----------------------------
add authentication samlPolicy "Azure AD" ns_true "Azure AD"

# Advanced Authentication Policies
# --------------------------------
add authentication Policy "Azure AD Advanced" -rule true -action "Azure AD"

# Authentication Virtual Servers
# ------------------------------
add authentication vserver nFactor-AzureAD-SAML SSL 0.0.0.0
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -gotoPriorityExpression NEXT

# Authentication Profiles
# -----------------------
add authentication authnProfile nFactor-AzureAD-SAML -authnVsName nFactor-AzureAD-SAML

# Citrix Gateway Virtual Servers
# ------------------------------
set vpn vserver gateway5.corp.com -authnProfile nFactor-AzureAD-SAML

SAML nFactor LDAP Group Extraction

If you use AAA Groups with Citrix Gateway, then be aware that SAML usually does not provide the user’s group membership. Instead, configure a LDAP Policy to get the user’s groups from Active Directory so the groups can be later used by Citrix Gateway.

If you don’t need LDAP Group Extraction, then skip ahead to the StoreFront section.

Do the following to configure LDAP Group Extraction.

  1. Create a new LDAP Action.
    1. Use the Search in Menu to find LDAP then pick any of the results.
    2. Check the box next to an existing LDAP policy and click Add to copy its configuration. Or create a new one.
    3. Change the name of the LDAP Action.
    4. On the top right, uncheck the box next to Authentication.
    5. Scroll down a bit and in the right side re-enter the Administrator Password. Copying an existing LDAP Action does not copy the Bind password.
    6. Scroll down to the Other Settings section.
    7. On the left, change Server Logon Name Attribute to –<< New >>–.
    8. Enter userPrincipalName. The UPN is extracted from the SAML Assertion.
    9. Scroll down and click Create.
  2. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy and click Add to create a new Policy.

    1. Change Action Type to LDAP.
    2. Expression = true.
    3. Click Create.
  3. On the left, go to Security > AAA – Application Traffic > Policies > Authentication > Advanced Policies > Policy Label. On the right, click Add.

    1. Give the Policy Label a name and click Continue. The Login Schema should be LSCHEMA_INT.
    2. Select your LDAP Group Extract policy and then on the bottom click Bind.
    3. Click Done to close the Policy Label.
  4. On the left, go to Security > AAA – Application Traffic > Virtual Servers. On the right, edit your SAML AAA vServer.

    1. Click where it says 1 Authentication Policy.
    2. Right-click the Authentication Policy and then click Edit Binding.
    3. In the Select Next Factor field, click where it says Click to select.
    4. Select your LDAP Group Extract Policy Label and then click Bind.
  5. Skip ahead to the StoreFront section.

Here are some sample CLI commands for this nFactor SAML LDAP Group Extract configuration.

# LDAP Actions
# ------------
add authentication ldapAction LDAP-GroupExtract -serverIP 10.2.2.11 -serverPort 636 -ldapBase "dc=corp,dc=local" -ldapBindDn ctxsvc@corp.local -ldapBindDnPassword ****** -ldapLoginName userPrincipalName -groupAttrName memberOf -subAttributeName cn -secType SSL -authentication DISABLED

# LDAP Policies
# -------------
add authentication ldapPolicy LDAP-Corp ns_true LDAP-Corp

# Authentication Policy Labels
# ----------------------------
add authentication policylabel LDAP-GroupExtract -loginSchema LSCHEMA_INT
bind authentication policylabel LDAP-GroupExtract -policyName LDAP-GroupExtract -priority 100 -gotoPriorityExpression NEXT

# Authentication Virtual Servers
# ------------------------------
bind authentication vserver nFactor-AzureAD-SAML -policy "Azure AD Advanced" -priority 100 -nextFactor LDAP-GroupExtract -gotoPriorityExpression NEXT

Configure StoreFront for SAML Citrix Gateway

  1. In StoreFront 3.6 or newer, in the StoreFront Console, go to Stores, right-click the store, and click Manage Authentication Methods.
  2. Make sure Pass-through from Citrix Gateway is selected.
  3. Click the bottom gear icon on the right, and click Configure Delegated Authentication.
  4. Check the box next to Fully delegate credential validation to Citrix Gateway and click OK twice.
  5. In StoreFront, add a Citrix Gateway object that matches the FQDN of the Citrix Gateway Virtual Server that has SAML enabled.
  6. On the Authentication Settings page, make sure you configure a Callback URL. It won’t work without it.
  7. Then assign (Configure Remote Access Settings) the Gateway to your Store.

  8. Next step: create Active Directory Shadow Accounts

Native SAML on StoreFront without Citrix ADC

StoreFront 3.9 and newer have native support for SAML Authentication without Citrix ADC. Notes:

  • SAML overrides Explicit and Pass-through authentication.
  • SAML in StoreFront without Citrix ADC seems to work in Workspace app and Receiver Self-Service for Windows.

For an example configuration using StoreFront PowerShell commands and SAML metadata, see CTX232042 Configure StoreFront with OKTA.

To configure native SAML in StoreFront 3.9 or newer:

  1. Export the signing certificate from your SAML IdP. The IdP could be ADFS, Okta, Ping Identity, etc.
  2. In StoreFront 3.9 or newer console, right-click a Store, and click Manage Authentication Methods.
  3. Check the box next to SAML Authentication. If you don’t see this option (because you upgraded from an older version), click the Advanced button on the bottom of the window, and install the authentication method.
  4. On the right, click the gear icon for SAML, and click Identity Provider.
  5. Change the SAML Binding to the method your IdP expects.
  6. Enter the IdP token issuance endpoint URL. For example, in ADFS, the path is /adfs/ls.
  7.  Click Import.
  8. Browse to the signing certificate exported from your IdP, and click Open.
  9. Then click OK to close the Identity Provider window.
  10. On the right, in the SAML Authentication row, click the gear icon, and then click Service Provider.
  11. Click the first Browse button.
  12. Give the Signing certificate a name, and save it somewhere.
  13. Click the second Browse button.
  14. Give the Encryption certificate a name, and save it somewhere.
  15. Copy the Service Provider Identifier. Or you can change it to your desired value. Then click OK.
  16. In your IdP (e.g. ADFS), create a Relying Party Trust.
  17. Import the Encryption certificate that you exported from StoreFront.
  18. Enable SAML 2.0.
  19. For the Assertion Consumer Service (ACS) path, enter something similar to https://storefront.corp.com/Citrix/StoreAuth/SamlForms/AssertionConsumerService. The hostname portion of the URL is equivalent to your StoreFront Base URL. /Citrix/StoreAuth matches your Store name with Auth on the end. The rest of the path must be /SamlForms/AssertionConsumerService. You can get this ACS value by looking in the SAML metadata at the bottom of https://<storefront host>/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata.

  20. For the Relying party trust identifier, enter the identifier you copied from the Service Provider window in StoreFront.
  21. Configure the Claim Rules to send the user’s email address or userPrincipalName as Name ID.
  22. Edit the Relying Party Trust. Import the Signing certificate that you exported from StoreFront.

  23. Create Active Directory Shadow Accounts. Federated users must be userPrincipalName mapped to local Active Directory accounts.
  24. If you point your browser to https://<storefront-host>/Citrix/<storename>Auth/SamlTest, it should perform a SAML Login, and then show you the assertion that was returned from the IdP. See Citrix CTX220639 How to configure SAML Authentication-Test Configuration.
  25. See Citrix CTX220682 Storefront SAML Troubleshooting Guide for event logs, SAML Metadata, Active Directory account mapping, Trust XML, etc.
  26. When you go to your Receiver for Web page, it should automatically redirect you to your IdP. After authentication, it should redirect you back to StoreFront and show you your icons.
  27. ADFS also works in Receiver 4.6 and newer, and Workspace app.
  28. When you logoff, it won’t let you log on again unless you close your browser and reopen it.

  29. To fix this problem, see CTP Sacha Thomet StoreFront – Allow relogin without browser close. Edit the file C:\inetpub\wwwroot\Citrix\StoreWeb\custom\script.js, and add the following line: 
    CTXS.allowReloginWithoutBrowserClose = true

  30. Now when you logoff, you’re given an option to log on again.

Active Directory Shadow Accounts

To login to Windows (Citrix VDA), every user must have an Active Directory account in a domain trusted by the VDA. For Federated Users, you typically need to create shadow accounts for each Federated user in your local Active Directory. These Shadow accounts need a userPrincipalName that matches the SAML attribute (usually email address) provided by the SAML IdP.

If the email address provided by the SAML IdP does not match the UPN suffix for your domain, then do the following:

  1. Open Active Directory Domains and Trust.
  2. Right-click the top left node (not a domain node), and click Properties.
  3. In the UPN Suffixes tab, add a UPN suffix that matches the email suffix provided by the SAML IdP.
  4. When creating a shadow account in your Active Directory, the new UPN suffix is available in the drop-down list. Note that the pre-Windows 2000 logon name can’t conflict with any other user in the domain.
  5. The password for these Shadow accounts can be any random complex password since the Federated users never need the Shadow account’s password.
  6. If the shadow account is already created, edit the account, and on the Account tab, use the drop-down to select the new UPN suffix.
  7. Create a shadow account for every federated user. There are third party Identity Management tools that can automate this. Or get an export from the IdP and use PowerShell scripting to create the acccounts.

Verify FAS

When FAS is enabled on StoreFront, every user that logs into StoreFront (local or remote) causes a user certificate to be created on the FAS server. You can see these user certificates by running the following PowerShell commands:

Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
Get-FasUserCertificate -address fas01.corp.local

Citrix uses these certificates to logon to the VDA as the user. No password needed.