LDAP Authentication Configuration Gotchas

This introduction article will help Admins to troubleshoot LDAP Authentication. The user must have the Admin access in TDAdmin.

Overview

LDAP user authentication is the process of validating a username and password combination with a directory server such MS Active Directory, OpenLDAP or OpenDJ.

Users can run into issues when setting up LDAP for their TeamDynamix environment and this article will help avoid or troubleshoot these common issues.

Where to Find This

This feature appears in the TDAdmin.

Navigate to setup LDAP authentication following these paths:

• TDAdmin> Organization Settings > Authentication Providers > create New or Edit existing

How the LDAP Process Works in TeamDynamix

When Not Using a Proxy User

1. User enters credentials in TeamDynamix
2. The user's authentication username and password are used to bind to the LDAP server. If the user has no authentication username, their TDX username will be used instead.
3. If step 2 is successful, an LDAP query is performed against the specified search base using the specified search string to ensure that the user object actually exists. The LDAP query will use the user's authentication username. If no authentication username is specified, the TDX username will be used instead. For this step, the username is put into the specified user format string as specified in the authentication configuration.
4. If step 3 successfully finds a result, authentication passes.

When Using a Proxy User

1. User enters credentials in TeamDynamix.
2. The proxy user's credentials are used to bind to the LDAP server.
3. If step 2 is successful, an LDAP query is performed against the specified search base using the specified search string to ensure that the user object actually exists. The LDAP query will use the user's authentication username. If no authentication username is specified, the TDX username will be used instead.
4. If step 3 successfully finds a result, the system checks whether not to further look up the user's true distinguished username.
   1. If the authentication settings say not to look up the user's distinguished name, the process skips to step 5.
   2. If the authentication settings say to look up the user's distinguished name, that value is retrieved and is used in place of any username value previously used.
5. The user's username (which might have been replaced with a full distinguished name in step 4) and password are used to perform a second bind against the LDAP server for authentication only. For this step, the username is put into the specified user format string as specified in the authentication configuration.
6. If step 5 succeeds, authentication passes.

This processes follows the recommended standard Microsoft authentication process for AD as specified here. We only follow their pattern though. Instead of using the referenced DirectorySearcher classes, we use the Microsoft LdapConnection classes.

Gotchas & Pitfalls

• Don't forget to allow the TeamDynamix IPs if the client is SaaS. See the related article for that information. If the user is installed, be sure to make the appropriate firewall rules for the web server(s) to communicate with the LDAP server(s). 
• When using SSL, be sure that you have the correct port specified. 
• When using SSL, you almost always need to verify the server certificate. If you are using Active Directory you will absolutely need to do this. This is to verify that the source (client) server is who they say they are to prevent LDAP server spoofing. This is a low-level LDAP thing and cannot be configured around. Items to verify for LDAP SSL certificate verification: 
  • Valid certificate files should be in the format of .cer or .crt and should not include the private key. There might be other formats which work but these are the ones we commonly see.
  • The certificate should be for the forwards-facing domain server that TeamDynamix will interact, not a root certificate.
• Common LDAP ports are 389 for insecure (read non-SSL) and 636 for SSL.
• Common Active Directory ports are 3268 for globally insecure connections (non-SSL) and 3269 for globally secure connections (SSL). Active Directory can be configured to map ports 389/636 to a specific AD server in a farm while 3268/3269 go against the entire AD farm itself and not a specific server in the farm. 
• Sometimes clients have their actual usernames stored with a unique fully distinguished name format and let their user’s authentication with some sort of "friendly" name. This process works due to a round-robin approach where their LDAP uses the friendly name to lookup up their real username and then authenticate with that value. TeamDynamix can do this too by using a proxy user account and specifying the Use Distinguished Name option. When using this configuration, the TeamDynamix username or auth username is swapped out with the user's real username when authentication happens.
• Be sure that your search queries, search bases and username format strings are correct. For instance, authentication won't work when you search on a base of OU=1,dc=client,dc=edu if the user is in OU=2,dc=client,dc=edu!