LDAP Authentication – NetScaler Gateway 12 / Citrix Gateway 12.1

Last Modified: Dec 21, 2018 @ 11:43 am


💡 = 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:
    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.

    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
  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 -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.
    • NetScaler Gateway 12 and Citrix Gateway 12.1 do 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.

17 thoughts on “LDAP Authentication – NetScaler Gateway 12 / Citrix Gateway 12.1”

  1. Is it possible to restrict Citrix Gateway access to only members of TWO AD groups?
    I mean, by configuring the LDAP filters, it is possible to filter by 1 group, but not for 2 or more.
    I’ve tried to do it by changing security settings of Session policies. It worked in general, but not for those policies with EPA OPSWAT expressions.
    Thanks in advance & regards.

  2. Carl,

    How would we configure the session policies for receiver for multiple domains? Would we only need one session policy for receiver or two session policies, one for each domain?

  3. Would the NetScaler be able to handle the following scenario:

    When creating a LDAP Authentication Server create only one server and use a common FQDN, e.g. ldap.domain.com
    In DNS ldap.domain.com resolves to the IP addresses of two or more Domain Controllers.

    What will the NetScaler do when it gets two or more IP addresses returned as the result of the DNS query for ldap.domain.com?
    What will happen if one of the IP addresses proves to be unresponsive, will the NetScaler try one of the other IP addresses that it got?

    It would be great if this would work because this would make things simpler. Changes in Domain Controllers names and/or IP addresses would only require DNS changes and no changes in the NetScaler configuration.

  4. Carl,
    We’re at a point where we’ve hit a limit of 32 authentication policies bound to a gateway vserver and can’t provision any more customers/domains. Citrix support says we’re out of luck, there was a feature request 5 years ago to increase this limit, but nothing happened with it. I’m pretty sure this limit is completely arbitrary since there has been no performance impact so far. Now we’re stuck trying to figure out a design that will work for multiple domains but not hit some sort of limit. Any thoughts?

      1. They don’t seem to be… I just tried to add a 33rd binding on a policy label and it said we’ve reached the limit of 32. I did look for a way to bind policy labels directly to an AAA vserver, but it seems like they can only be added to a regular authentication policy binding and selected as the “Next Factor”, which is how we currently use them

  5. When create an LDAP server the Allow Password Change is not in the other settings. Did this get moved to a new location in 12.1?

  6. Hi Carl,
    do you know how or which Option is to choose that user get alermessage by Login on Nestcaler “your Password will expire in…Days, please Change it..”?

    1. Citrix Gateway 12.1 will show you this information in the RfWebUI theme if you access the Clientless Access portal (not direct to StoreFront). I don’t think it works any other way.

  7. Hi Carl, I’ve created an LDAP LB VIP, per your steps. The LB VIP vserver is up/green. I then go to create an LDAP server via Authentication\Dashboard and when I try to Test LDAP Reachability, the NS hangs and becomes unresponsive. I have to reboot the NS, to gain control back via mgmt GUI. I have an LDAP monitor created using the same Bind account/pw and that is successful. I also created an LDAP server via System\Authentication\Basic Policies\LDAP\Server tab and am successful adding an AD server with the same creds. So I don’t believe it has something to do with my bind account. Any thoughts why my NS keeps hanging when I try to create the LDAP server with the use of the LDAP LB VIP? Thanks! I’m running 12.1_48.13

  8. Hey Carl, great documentation as always! I noticed in Step 12 under “LDAP Authentication Server” your screenshot shows the “cn” value in the “SSO Name Attribute” drop-down although you mention to select the “Sub Attribute Name”. Just thought I’d share.

Leave a Reply