NetScaler Gateway LDAP Authentication

Last Modified: Jul 10, 2016 @ 1:53 pm


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.

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 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)
  2. Run ldp.exe

  3. Open the Connection menu, and click Connect.
  4. Check the box next to SSL. Change the port to 636. Then enter the FQDN of a Domain Controller, and click OK.
  5. 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.
  6. Open the Connection menu and click Bind.
  7. Change the Bind type to Simple bind. Then enter the service account credentials. You can use DOMAIN\Username, or you can use Click OK.
  8. Look on the right pane to verify a successful bind. If not, fix the credentials and try again.
  9. Once you have successfully binded, you can view the directory tree by opening the View menu, and click Tree.
  10. Click the drop-down to view the directory partitions.
  11. Repeat these steps to verify each Domain Controller and any load balanced LDAPS.

LDAP Server

To create the LDAP Authentication Server, and LDAP Authentication Policy, do the following:

  1. On the left, expand NetScaler Gateway > Policies > Authentication, and click LDAP.
  2. On the right, switch to the Servers tab, and click Add near the top.
  3. Enter LDAP-Corp 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.
  4. Change the selection to Server IP. Enter the VIP of the NetScaler load balancing vServer for LDAP.
  5. Change the Security Type to SSL.
  6. Enter 636 as the Port. Scroll down.
  7. Note: there is a checkbox for Validate LDAP Server Certificate. If you want to do this, see Citrix Discussions for instructions for loading the root certificate to /nsconfig/truststore.
  8. In the Connection Settings section, in the Base DN field, enter your Active Directory DNS domain name in LDAP format.
  9. In the Administrator Bind DN field, enter the credentials of the LDAP bind account in userPrincipalName format. Domain\username also works.
  10. Check the box next to BindDN Password and enter the password. Scroll down.
  11. In the Other Settings section, use the drop-down next to Server Logon Name Attribute, Group Attribute, and Sub Attribute Name to select the default fields for Active Directory.
  12. On the right, check the box next to Allow Password Change.
  13. If you want to restrict access to only members of a specific 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 query 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 Administrative Center. Double-click the group object, and switch to the Extensions page. On the right, switch to the Attribute Editor tab.
    2. Scroll down to distinguishedName, double-click it, and then copy it to the clipboard.

    3. Back on the NetScaler, in the Search Filter field, type in memberOf=, and then paste the Distinguished Name right after the equals sign. Don’t worry about spaces.
  14. Scroll down and click Nested Group Extraction to expand it. If desired, change the selection to Enabled.
  15. Set the Group Name Identifier to samAccountName.
  16. Set the Group Search Attribute to memberOf.
  17. Set the Group Search Sub-Attribute to CN.
  18. For the Group Search Filter field, see CTX123795 Example of LDAP Nested Group Search Filter Syntax.
  19. Click Create.

LDAP Policy Expression

  1. On the left, expand NetScaler Gateway > Policies > Authentication, and click LDAP.
  2. On the right, switch to the Policies tab, and click Add.
  3. Name the policy LDAP-Corp. If you have multiple domains, then you’ll need a separate LDAP Policy for each domain, so make sure you include the domain name.
  4. Select the previously created LDAP-Corp server.
  5. On the bottom, click the Saved Policy Expressions drop-down, and select the ns_true expression.
  6. Click Create.

     add authentication ldapPolicy LDAP-Corp ns_true LDAP-Corp

Gateway Authentication Feedback and Licenses

  1. On the left, under NetScaler Gateway, click Global Settings.
  2. On the right, in the right column, click Change authentication AAA settings.
  3. If you are using Gateway features that require Gateway Universal licenses, then change the Maximum Number of Users to the number of Gateway Universal licenses you have installed on this appliance. This field has a default value of 5, and administrators frequently forget to change it, thus only allowing 5 users to connect.
  4. If desired, check the box for Enable Enhanced Authentication Feedback. This feature provides a message to users if authentication fails. The message users receive include password errors, account disabled or locked, or the user is not found, to name a few. Click OK.

    set aaa parameter -enableEnhancedAuthFeedback YES -maxAAAUsers 200

Next Step

For two-factor, configure RADIUS Authentication

Otherwise, Configure NetScaler Gateway Session Policies

Multiple Domains

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

What if the same username is present in multiple domains? As NetScaler 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 NetScaler 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, set 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. The samAccountName policies would be searched in priority order, and the userPrincipalName policies can be used to override the search order. Bind the userPrincipalName policies higher (lower priority number) than the samAccountName policies.

After authentication is complete, a Session Policy will be applied that has the StoreFront URL. The NetScaler Gateway will attempt to log into StoreFront using SSO so the user doesn’t have to login again. When logging into NetScaler 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 NetScaler specify the domain name while logging in to StoreFront?

There are two methods of specifying the domain:

  • AAA Group – Configure multiple session policies with unique Single Sign-on Domains.  Inside the Session Policy is a field called Single Sign-on Domain for specifying the NetBIOS domain name. If there is only one Active Directory domain, then you can use the same Session Policy for all users. However, if there are multiple domains, then you would need multiple Session Policies, one for each Active Directory domain. But as the NetScaler loops through the LDAP policies during authentication, once a successful LDAP policy is found, you need a method of linking an LDAP policy with a Session Policy that has the corresponding SSO Domain. This is typically done using AAA groups. This method is not detailed here but the general steps are: In the LDAP policy/server, specify a Default Authentication Group. Create a AAA Group that matches it. Then bind the corresponding Session Policy to that AAA group.
  • userPrincipalName – Alternatively, configure the LDAP policy/server to extract the user’s UPN and then authenticate to StoreFront using UPN. This is the easiest method but some domains don’t have userPrincipalNames configured correctly.

The userPrincipalName method is detailed below:

  1. In each of your NetScaler LDAP policies/servers, in the Other Settings section, in the SSO Name Attribute field, enter userPrincipalName. Make sure there are no spaces after this attribute name. NetScaler will use this pull this attribute from AD, and use it to Single Sign-on the user to StoreFront.
  2. In StoreFront Console, right-click  the 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 domains in DNS format. The advantage of entering domain names is that you can select a default domain if internal users forget to enter a domain name during login. The DNS format is required for UPN logins (e.g. SSO from NetScaler Gateway).
  6. On the NetScaler 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 Published Applications tab, make sure Single Sign-on Domain is not configured. Since NetScaler is using the userPrincipalName, there’s no need to specify a domain. If Single Sign-on Domain is configured, then Single Sign-on authentication will fail.

Email this to someonePrint this pageTweet about this on TwitterShare on LinkedInShare on FacebookPin on PinterestShare on RedditShare on StumbleUpon

66 thoughts on “NetScaler Gateway LDAP Authentication”

  1. Hi, I am configuring Netscaler 10.5 with StoreFront 3.6, but, I get “HTTP Error 404. The requested resource is not found.” error.. after logging in.
    Any suggestions to debug this problem!

      1. Hi Carl, Thanks for the reply.
        The earlier problem got resolved by updating Bindings in IIS on StoreFront Server.
        But, now after login I am continuously getting error – “Cannot complete your request”

  2. Carl, I am having an issue where no domain user can log on,only the local nsroot logon works. I’ve run through the Verify LDAPs section and all is good, the LDAP servers and policy look ok too. If I run the aaad.debug tool I am seeing a 4003 error,connection timed out, my network provider has checked and say they can see the traffic flowing out through the firewall, but no more than that. Do you have any suggestions for where to look?

    1. Did it ever work? Is routing properly configured? If you to a port 636, do you see R packets coming back? Are you load balancing LDAP? If so, are the monitors working?

      1. Its never worked, its using port 389, i’ll have a look and see what the nstcpdump shows, Yes we are loadbalancing and it all looks fine, if I do a show bindings and use the service account and password all looks ok.

        Thanks for such a quick reply, I read these blogs and tips a lot. Been really useful

        1. If you’re using the script, that is sourced from the NSIP. Actual load balancing is sourced from SNIP. Make sure firewall allows both.

          1. Thank you I was thinking it was something not right on the firewall, we have had all sorts of hoops to jump through to get it looked at. I’ll get the firewall rules checked as you suggest.

            Thanks again for your lightening fast responses.


    1. Are you asking about multiple domains and the domain drop-down list or similar? Those only work on web. I’m hoping Citrix adds web-based auth to Receiver so both can be the same.

  3. Carl,

    Can I use the existing Netscaler Citrix storefront certificate for LDAPS authentication too? Because I do not want to maintain multiple certificates that will be difficult when a new admin has to take over the job & have to remember to renew at each location. Currently, I m using netscaler server test certificate for LDAPS authentication. In future, I can only remember to update the certificates only in Netscaler & in storefront assuming certificate already has SAN entries for receiver email, storefront call back etc.


  4. Hi Carl,

    I’m stuck here for multiple domain authentication.

    “But as the NetScaler loops through the LDAP policies during authentication, once a successful LDAP policy is found, you need a method of linking an LDAP policy with a Session Policy that has the corresponding SSO Domain. This is typically done using AAA groups. This method is not detailed here but the general steps are: In the LDAP policy, specify a Default Authentication Group. Create a AAA group that matches it. Then bind the corresponding Session Policy to that AAA group.”

    userpriniciplemethod doesn’t work for me so I had to create two session policies. I have one domain in Americas & another in asia. I created two LDAP policies & two session policies. During netscaler virtual server configuration, I gave first LDAP policy as Americas & second as asia. User has same user name in both domain but password differs. Similarly I have two session policy, first bind has America as SSO & second has asia as SSO. The authentication works fine for America user but for asia user, it logs on & during storefront SSO, it fails stating cannot complete request. On the event viewer it still shows first domain name. Switching the policies works but America user will have same problem. I created AAA group in Netscaler & mapped session policy for asia & changed the priority but still it fails. Please help

    1. In the LDAP policy/servers, did you configure a unique Default Authentication Group for each LDAP server? These are your AAA groups.

      The session policies bound need a lower priority number than any other session policy that has SSO Domain configured.

      1. Hi Carl, thanks a lot for these great articles. They have really helped me with the implementation of our Netscaler. Apologies for resurrecting an old reply but this issue of Balaji is identical to the problem I am currently having.

        Netscaler has been running perfectly on our Europe domain for months but now I need to add a 2nd domain for another region. I am having the same issues of needing a 2nd LDAP and session policy to bring in the different SSO domain string. I have followed the steps of creating AAA groups etc but I am struggling with how to bind the policy to these AAA groups, specifically this part of what you wrote “Then bind the corresponding Session Policy to that AAA group.”

        Can you briefly describe how this is done as I can’t seem to find any option for that anywhere.

        Thanks in advance.

        1. Create a Session Policy/Profile that has only the SSON Domain specified.

          In Gateway > User Mgmt > AAA Groups, add a group that matches the Default Authentication Group you configured in your LDAP policy/server. Bind the session policy to this group.

  5. Carl, I’m relatively new to Citrix (avent touch it in years before this XenApp 7.6 depolyment) and have never worked with these NetScaler VPX appliances, we already have our system in production. We want the ability for end users to change their own passwords via Receiver. Is this the right solution? How difficult is this to implement, what are the things I should look for so I don’t screw this up?…LOL

    1. It can definitely be done using the browser but I’m not sure about Receiver. In StoreFront, enable the password change option. When users connect using a browser, after logging in, there’s a link or icon to change the password.

      Or are you asking about changing the password if it has expired? That definitely works in the browser when connecting to NetScaler Gateway assuming you enable LDAPS. Not sure about Receiver.

      1. Well I guess both. Can a user change a password when they wish? Or only when it expires? We are hosting a Citrix environment in a Tenant environment. We want to be able to unload all the password reset requests we get daily onto the users so they can do it themselves and add another layer such as verification via text to a smartphone.

        1. In StoreFront, enable password changes and users can change it anytime after they login.

          In NetScaler Gateway, ensure LDAPS (636) is configured and check the to box to Allow Password Changes.

          Otherwise, you’ll need some sort of SSPR tool. Citrix is working on a tool for a future release of StoreFront.

  6. Hi Carl,
    Great post you have here. We’re seeing the issue whereby we have multiple domains in a trust that we’re migrating users between (old to new domain). The issues is the same user account exists in both domains as they are transitioned. We can’t find a way to pass through the UPN so the StoreFront recognises the domain the user’s trying to authenticate against. I.e. “” and “”, they user is always authenticated against the first LDAP that matches. Any ideas on how to pass through the UPN correctly?

  7. I carl, I am new to Netscaler, in our environment there is a policy for account lockout which has been set to 50 attempts, we are in the plan to reduce as per the industry best practise 10. All the users in my organization uses citrix to logon. On our netscaler they have physically given some 5 domain controllers for authentication. I gave a solution to remove all the physical domain contollers to a domain name example when I do a nslookup of it will display all my ip’s associated to the domain. ( e.g.,, My question how to configure this in LDAP for authentication with domain name and ip address

    1. In the LDAP policy/server, there’s a radio button on top that lets you enter a domain name instead of an IP address.

  8. Hi Carl,

    We are having issues when uploading files larger than 64 kb to Netscaler 10.5, build 59.1305

    Installation: Netscaler 10.5, build 59.1305. IIS 8.5. Content switch, AAA login with SSO (Web applications) and persistent cookie. URL:s in trusted sites.

    Conditions: After upgrade to Netscaler 10.5, build 59.1305. Form based login in Netscaler AAA with persistent cookie is used.

    Result: When uploading files to SharePoint smaller than 64 kb all works as expected and files are uploaded. When uploading files larger than 64 kb users are prompted with Windows Security login popup (IIS windows authentication). If entering correct credentials in Windows Security upload starts and finishes as expected. If not entering credentials I receive “401 Unauthorized.”

    Before upgrade we used Netscaler 10.5, build 56.12, IIS 8.5 and AAA login and it always worked as expected and we were never prompted Windows Security login.

    Thanks for a great blog!


    1. I’m guessing App Firewall is enabled. If you edit the App Firewall profile, there’s a setting for maximum POST size or something like that.

  9. Hi Carl

    I have just query regarding the LDAPS configuration
    1.What all certificates(root,intermediate,Server) are required ?
    2.Where exactly i need to bind those certificates during LDAPS configuration?
    3.Do i need to bind a certificate in service as well?

    I have wild card certificate as if now and Netscaler Gateway is configured with SAML authentication

    Thanks in advance

    1. For Microsoft Domain Controllers, Windows will not accept wildcard certs. It needs to be a cert with only the DC’s FQDN.

      Otherwise you need cert on the LDAP servers and cert on the LDAP LB vServer. That’s it. The LDAP LB vServer cert is not needed if you do TCP instead of SSL_TCP.

  10. awesome post – just one question

    I don’t have netscaler license for load balancing and i really don’t want to pay extra $7000 just for LDAP load balancing to work. Is there another work around to make LDAP authentication work with two domain controllers in place via authentication policies?

        1. Kind of. Most of my Load Balancing procedures involve Backup vServers.

          Here’s CLI documentation –

          If you’re only licensed for NetScaler Gateway then you have a Virtual Server and Services node instead of a Load Balancing node. Other than the name the instructions are essentially the same. Except that you can only bind one service per vServer.

    1. It’s an expression that always evaluates to “true”. In classic syntax you can’t just enter true. In the newer “default” or “advanced” syntax you could type in just “true”. AAA in NetScaler 11 supports advanced policies and I suspect Gateway will support it eventually.

      1. Thanks for your fast response… I really meant: Client wants “clientless” access using Netscalers to allow internal access to different resources (internal web sites, RDP, etc), BASED on his LDAP Users-Group attributes / policies. <– Can I do that with only the Standard license? So UserA in LDAP can access Web1 but not RDP1, UserB can access all of them, UserC can access only RDP2, etc… If yes, do I need different vServers, one for each internal resource ?

        Im not very sure what is the AAA vServers feature for… neither the AAA Traffic manager for.. Im still googling those ones. Your help is appreciated!

        1. NetScaler Gateway has a clientless feature with multiple links based on AAA groups. You need NetScaler Gateway Universal licenses for each concurrent user. Standard Edition is sufficient.

          1. Done. I successfully authorized defined resources (ssh, web, etc) to AAA groups. But now, how can I use an LDAP attribute to give authorization to those resources instead of using AAA groups ? (since 1 user could be in several groups at the same time, but it can have 1 single attribute value)
            I can’t find where to do the “link” between attribute-value and resources.
            [I know how to read the ldap attribute in the LDAP server setting “search filter” I believe… but what to do after that?.. I assume that attribute-value will be passed on to the netscaler and could be read in other settings, policies, etc]

      2. Carl,

        I’m doing a build on NS 10.5 59.13, standard edition. Is it possible to configure a single NS Gateway, allow client choices, and limit access to the SSL VPN by AAA group and corresponding AD/LDAP group?

        So, with a single gateway vserver can we:

        1: VPN user group gets client choices, and Universal license is allocated to that user session if they launch SSL VPN.
        2: Non-VPN users don’t see client choices, and ICA only for their session. Or, perhaps they see client choices but can’t launch VPN or consume a license.
        3: Bonus – if VPN user selects the Citrix XenApp link in client choices, they also get ICA only and don’t consume a license.

        I could do this with two gateways, but it would be nice for the end users to have a single link.

        1. You can certainly bind different session policies to different AAA groups connecting to a single Gateway vServer.

          However, licensing applies to all users of a Gateway vServer whether VPN or not. That’s because of SmartAccess, which doesn’t need VPN. If you want some with licenses and some without then you need differnet Gateway vServers.

  11. Hi Carl,

    Thank you for your great job. how can i configure one citrix netscaler for two farms located in different domain ?

    Domain A:
    2-Delivery controller

    Same configuration for Domain B.

    if a User from domain A log in using netscaler he will get application published the application published in Domain A ?

    Thank you in advance.


    1. AAA groups is probably easiest. In the LDAP auth policies, configure a unique Default Authorization Group for each policy. Add AAA groups that match those names. Bind session policies to those AAA groups. The session policy points to the StoreFront server for that domain and has the SSO Domain configured for that domain.

    2. Simply create a second NetScaler Gateway vServer. That will allow you to have different authentication, farms, etc. It will have a different IP address so a second external IP will be required so you can forward TCP 443 on the new external IP to the new internal one.

  12. I am thinking another possible way to get around the Multiple Domains issue could be to combine all the directories to create a single directory using MS ADLDS and then use the UserPrincipalname attribute for single Sign On to Storefront

  13. This is great and I love all your posts Carl. Great work. But I do have a question here. For the LDAP with UPN to work then it means users will always have to logon using UPN right? Because if the same username exists on multiple domains I think the problem will still exist. Am I missing something?



    1. If Server Logon Attribute is userPrincipalName then yes. If Server Logon Attribute is samAccountName but SSO Name Attribute is userPrincipalName then no; NetScaler will search the auth policies and for the first one that matches it will pull the UPN and use that to authenticate with StoreFront. I’m hoping some day Citrix will fix multi-domain drop-down lists on NetScaler so that it works for both browsers and Receivers.

  14. Great article Carl! If you happen to find yourself in an environment where UPN is not configured correctly can you use another SSO Name Attribute that you can use to achieve this multi-domain configuration?

    1. You can try but I’m not sure if Windows will accept it. The idea is to send a username and password to StoreFront so StoreFront can authenticate the user with Windows.

  15. If configure this for userPrincipal name with multiple domains, does the user have to logon to the Netscaler Gateway logon page as or does it just search the domains that way and they can still logon with just the username?

    1. If you configure serverLoginAttribute as samAccountName then you only need the username. NetScaler will extract the UPN from AD and use that to authenticate with StoreFront.

    2. Hi Again,

      I have tested authentication at the netscaler using AAA groups, how can i authenticate user using his UPN …. i have tried the above configuration without luck, would you please write the steps for UPN authentication ?

      Thanks in advance

    3. Hi Again,

      would you please mention the steps for Netscaler authontication using user UPN, i have tried the above configuration without any luck.

      Thank you in advance


      1. Which part is not working? If you want UPN at the Gateway then you set LDAP Policy with Server Logon Attribute = userPrincipalName. If you want samAccountName at the Gateway but UPN for SSO to Storefront then you set the LDAP Policy with SSO Logon Attribute = userPrincipalName. This assumes the UPNs are configured correctly in AD. If you are logging into gateway with UPN then you need to edit the Session Policies and remove the SSO Domain from the Published Apps tab.

Leave a Reply