The configuration page here is for 3.50 release if you search for the config page for the 3.45 release, you should go here Configuring LDAP for 3.45
|The information in this article (or section) relates to SiT! v3.50 and later. Earlier versions may not have this functionality.|
Configuring LDAP Support
LDAP support currently covers the following areas:
- Admin, Manager, User and Contact authentication based on group membership
- Auto creation of Contacts from incident requests
This guide uses screenshots from Windows and Active Directory, though this shouldn't scare you since LDAP Directories look very much alike, with very little visible differences.
SiT Supports either of these
- Novell eDir
- Windows Active Directory
Ensure that the ldap module for php is installed.
You should take notice to this little section, it might shed some light if you are new to LDAP
LDAP is structured the same way as folders and files if you view it with a graphical editor.
Root / Folder / Folder / File
LDAP names are abit different from the names of folders and files
- "Root" is the name of the domain
- "Folders" can be of 2 types (explained later), Containers or Organizational Units (OU)
- "Files" are called Objects
Some examples of Objects (but not limited to):
so instead of a file path you now see
Domain / container / OU / object
|Tip: Base DN and groups cannot use the top level of the domain, it requires at least a container or organizational unit as it's highest level, which they both have in common|
This -->Doesn't work<--
domain.com |-Users / Admin Group |-My Org / My Users Common base DN = dc=domain,dc=com
domain.com |-My Org |-Users |-Groups Common base DN = OU=My Org,DC=domain,DC=com
Some LDAP directories have defined some default Containers that cannot be deleted or moved, since they are used by the system (just like your inbox in your mail), these containers are defined as containers, where as if they are user created they are called Organizational Units (OU). If you are using Windows AD and are looking in "Active Directory Users and Computers" you will notice that the system created containers like "Users" (blue square in the picture below) and "Computers" are pure yellow (looks like a folder) where the user created (red square in the picture below) have a small gray AD icon aswell.
If you created all your users in the "Users" container you should use CN as a definition (see below) and If you made a nice structure and created an OU called eg "Sales" then you should use OU as a definition
- ou=Organizational Unit
- dc=domain name eg "amazon"
- dc=top level domain name eg "com"
The confusing part is that when you need to talk to LDAP and get information from it, you need to ask for it from the opposite direction, and define what it is you are looking for.
So when you want to define the group for eg SiT Managers (look in the config below), and you put that group in an OU as shown in the example picture above, you define it as this:
So you actually ask from right to left.
Still confused?, let me try and break it up what just happend. asking for an object is almost like writing an email address, "user @ this-domain . com" or since we are using groups "distribution-list @ this-domain . com" so we ask for the object "sitmanagers" in "sit" OU in "sit.local" domain. Each part of the domain must be split up with a "dc" definition. If you are part of a large organization, you are sitting in a branch office with a domain called "london.domain.com" and using the above syntax, this example would then look like:
I'll put some more examples:
- cn=sitmanagers,cn=users,dc=sit,dc=local -- the "sitmanagers" group is located in the system created "Users" container
- cn=situsers,ou=IT,ou=support,dc=sit,dc=local -- the "situsers" group is located in the user created "IT/Support/" OU's
|Info: You cannot use Domain Users as a group, as it is lacking some required attributes|
Enable LDAP - Set this to true if you want to use both LDAP and Standard authentication
- Choices True/False
Choose a LDAP technology you want to configure SiT! up against
- Choices eDir (Novell)/AD (Windows)/OpenLDAP (*nix)/Custom
Type in the IP address or the hostname of the LDAP server / Directory Server / Domain Controller etc.
- Preferably either the IP address or the FQDN (Fully Qualified Domain Name), examples: win2003.sit.local, my.linux.box, freebsd or localhost
LDAP port choice, if you are unsure what to write here, leave blank or use default settings (389). Port 636 is usually used as a secure port, when you want to run fx SSL
LDAP has been developed through the time and uses different versions. You should research what version of LDAP your LDAP server runs. Newer technology such as recent versions of OpenLDAP and Windows Server 2003 uses Version 3.
- Choices 1/2/3
If you want to configure a secure connection to your LDAP server, you can enable this to either SSL or TLS, don't forget to configure your LDAP server as well.
- note: Configuring Secure LDAP Connections are not part of this guide
To be able to make a lookup into the LDAP servers database a username and password from that database is necessary.
- Recommendation: don't use any user with higher access like an administrator. Any user will do, even a guest account, as long as it's located in the LDAP database.
- Syntaxes: the user can be looked up differently. If one doesn't work, the other might.
- cn=Acme,cn=MyUsers,dn=linux,dn=box - Mostly OpenLDAP
- firstname.lastname@example.org - Mostly Used for Windows AD
At the password field for the above user, there is also a Check LDAP details button, after filling out the above, you can click on this to see if everything is OK. If it isn't you should go through your settings again. The Reveal button makes you able to see the password you've entered.
The LDAP Base settings, this is the Container or OU in which your users are located. If your users are spread out in several sub OU's, you should go up to the OU where all users can be found beneath. In large scale networks choosing the OU or Container closest to the domain can impact performance, and is not recommended.
- The syntax as described earlier is necessary here
The LDAP user status, sets the chosen status for all new users that logs in.
- The choices you have here are the same choice you can se on the profile page.
- There are no recommended settings here, you might want to discuss this with your co-workers and/or boss.
The SiT! LDAP permissions are set in the LDAP Directory where you create up to 4 groups. The choice is yours what to call these groups, just make sure you document them properly. Now you just have to add members to the groups and they'll have the rights you give them.
- SiT admins - This group is the one that can configure the site, make changes etc. They have the same rights as the Admin user. It's not recommended that too many people have this access.
- SiT managers - This group is the ones that can distribute the different assignments when required, this is usually given to department leaders or even a secretary.
- SiT users - This group is the Engineers/Technicians/Supporters/Sales people etc. that handle the incidents, customers, sites etc
- Customer group - The members of this group are the ones who can ask for help, create new incidents etc. If your target users are inside the network this is what you should setup. If otherwise you are an external support company with independent customers, you might want to leave this blank, and use the normal user database.
- To use the normal user database, just leave this field blank, and create the sites and contacts inside SiT.
LDAP Customer default site. This is the site where all new customers are being bound to when logging in for the first time.
- This doesn't happen if you removed the Customer group from the above step.
If a user sent a mail, instead of logging in to the customer portal, setting this to Yes, will try to pull information about the user from the LDAP server.
- Recommended setting is : Yes
- Allow SiT to cache users passwords
- Allow use of cached passwords
Setting the 'Allow SiT to cache users passwords' to Yes and 'Allow use of cached passwords' to No, you might think why? let me explain in the following scenario..
You don't want SiT to use cached passwords (for some reasons), but the only domain controller crashes. Now no-one is able to enter sit. Unless the Admin sets the 'Allow use of cached passwords' to yes. Now because of the 'Allow SiT to cache users passwords' the passwords are stored in SiT and a user can logon without connecting to the domain controller. IF 'Allow SiT to cache users passwords' were set to No, no users would be able to access SiT since no user credentials was cached in SiT.
Periodic Synchronisation allows users and contacts to be created periodically in SiT! from users in your directory, this has the benefits that accounts exist before the users' or contacts' first login allowing for further configuration of their account and call assignment prior to them logging in. Contact synchronisation is particularly useful when users log calls other than via the portal or email as their account is created in advance.
For obvious reasons this does not synchronise users passwords this occurs at login.
To configure this you should enable the ldapSync scheduler action.
|Info: ldapSync will only sync LDAP user objects from your directory to either users or contacts within SiT, it can not currently sync LDAP contact objects.|
If LDAP authentication isn't working it can sometimes be difficult to see why. Here are some tips:
- Enable Debug mode and error logging
- Check that Scheduler is running, you can do this by going to by going to SiT! -> Control Panel -> Scheduler and checking that the action ldapSync has run recently and is coloured blue. Red would indicate an error and Grey would indicate it is disabled.
- After waiting a few minutes to give the scheduler (auto.php) time to run at least once, check the contents of your error logfile.
- A message like "ERROR: Application Error Username must be unique" means that you have a SiT! user that has the same username as an LDAP user, in order to switch a users authentication method from SiT! native to LDAP authentication you must manually edit the user record in the database to change user_source from 'sit' to 'ldap'.
- There have been some issues regarding using special characters in Windows Active Directory, where an error occurred when trying to bind account. If you get this error, try changing to alpha numeric only.