Troubleshooting LDAP &amp; ActiveDirectory Integration

Understanding LDAP

The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over the Internet. It allows one application (in this case SpiraTeam) to connect to a directory service (LDAP server) to find out if a user is authenticated and authorized.

In the case of SpiraTeam, we only use LDAP for authentication, so that a company can have a central list of usernames and passwords that SpiraTeam uses. For authorization, since SpiraTeam uses project, role based security, we don't rely on LDAP for user permissions or roles.

For a full understanding of LDAP structure, please refer to the guide, however in general, you have the following structure:

diagram reproduced from https://www.pks.mpg.de/~mueller/docs/suse10.1/suselinux-manual_en/manual/sec.ldap.tree.html

where LDAP trees have the following elements:

DC = domain controller
OU = organizational unit
CN = container

The path in an LDAP system is concatenated from bottom to top, separated by commas. In this example above, you would have:

CN=Tux Linux,OU=devel,DC=suse,DC=de

What about Microsoft ActiveDirectory?

Microsoft has provided an implementation of LDAP with Windows Server since Windows 2000 called Microsoft Active Directory (aka AD). ActiveDirectory is a specific implementation of LDAP that has some idiosyncrasies. One of the challenges of integrating with ActiveDirectory is that the built-in administration tools don't always display the LDAP names of objects and ActiveDirectory uses some custom attributes that we shall highlight in this article.

For the remainder of this article we shall use the term LDAP to include ActiveDirectory, but we shall include specific information on the differences where it affects the configuration.

Integrating with SpiraTeam

To use SpiraTeam with LDAP, the first thing you need to do is go to the LDAP Configuration screen inside SpiraTeam:

You should put in the following attributes:

LDAP Host - this should be the name of your LDAP server (e.g. MyServer or myserver.company.com)
Use SSL - If you are in an intranet environment, typically you will use LDAP, so set this to 'No', for external use, you may be using LDAPS, in which case set to 'Yes'.
Base DN - This needs to be the LDAP path to the Container (CN) or Organizational Unit (OU) that contains your users (it can have sub folders)
Bind DN - This needs to the full LDAP path of a user that has permissions to access your LDAP server and retrieve the list of users. This is the user that will be used by SpiraTeam in the second step, when we import users.
Bind Password - This needs to be the password for the user you entered in the Bind DN.

Here is an example setup:

If you are using Microsoft ActiveDirectory, you can get the Base DN path from the Windows Server Manager:

The following ActiveDirectory objects map to LDAP:

corp.inflectra.com is the domain and becomes: DC=corp,DC=inflectra,DC=com
Users is a container, so it becomes: CN=Users
If we had used Domain Controllers, that is an organizational unit, so we'd have used: OU=Domain Controllers
Typically a user is a Container, so use CN=[Full Name]

The next step is to populate the various attributes:

If you are using any LDAP server other than ActiveDirectory, these values are correct and should not be changed!

If you are using Microsoft ActiveDirectory, you need to change the following:

So it would look like:

If you want to test the configuration, in the Sample User and Sample User Password box, copy the LDAP Bind DN and LDAP Bind Password into the sample user box. Then click Save:

Assuming it passes, you can now move onto the next stage.

Importing Users from LDAP

Once you have setup the LDAP connection (in the previous step), now you need to go to the View/Edit Users page in Administration:

Click on the button Import Users From an LDAP Server:

You will now have the option to import the selected users into SpiraTeam. The user list will be relative to the Base DN that you specified previously. Only users in the Base DN container / organizational unit (and any sub folders) will be displayed in the list. Also, any users that already have a login to SpiraTeam will be excluded from the list. If you want to convert an existing user to LDAP, please read the separate section below.

Once its imported, the user will be available as a new user in SpiraTeam and their user will have a profile that looks like the following:

Note that the user has the flag "LDAP Managed User" set to "Yes" and the password fields will be blank. The full LDAP Distinguished Name (aka LDAP DN) will be part of their profile. This is what SpiraTeam will use to connect to the LDAP server for authentication purposes, when the user tries to log in.

That means, if you change the location of the user in your LDAP directory (e.g. moving the user from being under CN=Users to being in OU=Headquarters Users), you will need to update the LDAP DN for their profile. You cannot re-import the user from LDAP, because their profile already exists.

Converting an Existing SpiraTeam User to LDAP

If you have an existing SpiraTeam user that currently uses the built-in SpiraTeam password management features and you want to convert to an LDAP Managed User, you cannot use the Import Users from LDAP option described in the previous section.

Instead you need to find that user's profile inside SpiraTeam using the View/Edit Users list and manually set the LDAP Managed User flag to "Yes" and enter their LDAP DN in the appropriate field.