Back when we were developing The Bug Genie 3.1, we promised LDAP support. Sadly we were not able to include it with the final release of 3.1, but the good news is that a testing version of The Bug Genie 3 is now out, with LDAP support included. This is release number 3.1.4, and a beta is available to download today, though we recommend you read the release announcement first (download link included).
On top of LDAP support, this fixed a few other issues with the mailing module (looking at you, guys who wanted delayed mailing!), as well as a few regressions from 3.1.3.
Read on for some important notes and some preliminary documentation.
Stuff to note
There are a few important things to note if your going to try this out. We haven’t yet written any documentation (this will be done before the final release), so you should take note of these points before you get started:
- The module will connect via a LDAP v3 connection.
- It was written, testing against an Active Directory server on Windows Server 2008 R2. We haven’t had any chance to test on a Linux-based directory server (I did give Fedora’s a go, but couldn’t get it to work), so testing in this area will be very much appreciated.
- If a user does not have an email set, it will be silently ignored by the code. This does mean the user will not receive any email notifications. As soon as an email is set in the directory, TBG will pick it up.
- If a full name attribute is not set, then this will be set to the user’s username. The user’s buddy name will be set to the user’s full name, so it will either be that or the username as appropriate.
- A LDAP call will be made on every page load, so if the user has their LDAP account removed in the middle of doing something, they will be logged out.
- No checks to see if the account is marked as ‘disabled’ or ‘locked out’ (etc.) as there seems to be no standardised way of doing this (as far as I can see)
- The control user specified in configuration only needs to be read only. It will not need access to user’s passwords, but it will need access to the user and group DNs specified, as well as the properties specified, in addition to:
- The account details for this control user will be stored plaintext in the database, so you may want to severely lock it down. If anyone knows of any better way of doing this, let us know! This is the only way we could think of for TBG to check if a user exists when validating the session, as we can not store the user’s password – nor ask them for it on every page load (so we cannot re-bind).
- If a group restriction is in place:
- Users who are not a member of any of the groups will not be allowed to log in. If they are already logged in, they will be logged out.
- Upon importing users, only users who are members of those groups will be imported. This needs testing*.
- Upon pruning users, if a user exists in LDAP but is not a member of any of the groups, the user will be removed from TBG’s database. This also needs testing*.
* These have been tested for a single group restriction, but not for cases where we have limited to (say) 3 groups
- Pruning users may remove TBG’s Administrator account, but will not remove the Guest account. Therefore guest access will still work in an LDAP environment, but the guest account will not be tied to the LDAP database. You can, also, turn off guest access.
- Each time the user connects to LDAP (i.e. on every authenticated page view), the user’s email address, full name and buddy name will be reset from the directory. Therefore these will always be in sync.
- If you do not import users, then the first time a LDAP user successfully logs in to TBG, they will have a TBG profile automatically created, with their email, buddyname and fullname imported from the directory. If a TBG user of the same username already exists, that user will be updated from LDAP data, and that user will be used.
Now that is all out of the way…
Setting up LDAP Authentication
Until the full documentation is written later, this short guide should help you get up and running:
- Install The Bug Genie 3.1.4 Beta
- Install the LDAP Module, from the module manager
- Open the LDAP Module settings page
- Insert the details required, see your system administrator for details. For the control account, on an Active Directory domain, this will need to be in the form DOMAIN\accountname, where DOMAIN is your AD Domain. All users will need to use this format too.
- After saving, run a connection test. This will check to see whether TBG can connect to the directory with the settings you have provided, and will check to see if the control account details are correct.
- If it all is, go to the import box. Put your DOMAIN\ prefix (or whatever other prefix) in the box if necessary, then press Import. This will import all allowed users into The Bug Genie. This means all LDAP items in the DN specified which are of objectType person. The group restriction will be taken into account here. The user’s full name and email address will also be imported, if they exist.
- Go to the Users section, and make at least one of them an Administrator. Unless a user was imported with the exact same username as an administrator already existing in The Bug Genie, it will not be accessible after the switchover. This is a must for AD users, as all your accounts will have the DOMAIN\ prefix.
- Go to Authentication settings. Choose LDAP as the authentication method, and then place some helpful messages for users. This may be details like ‘To reset your password, please dial 190 for IT’ on the Lost Password page, and so on. You can use Wiki Formatting in these boxes, and note that the Lost Password tab will only appear if email notification is enabled. If you want to alter the message on the login page, you can do this from the Wiki article it loads. That would be a good place to mention to include the DOMAIN\ prefix for AD users!
- Press save, you will be logged out and the new authentication method is now in use.
- Log back in with a LDAP account (preferably one you made an administrator!) If all is well you are now good to go!
- Optionally run the prune option to remove non-accessible TBG accounts.
What if it goes wrong?
If things go wrong, you can revert back to using TBG Authentication by opening the settings table in the database, and changing auth_method from auth_ldap to tbg.
All users from LDAP will still be accessible! You will just need to perform password resets (users were imported with random passwords), which you should be able to do from the Forgot my password tab. Note that if you were already logged in via LDAP, this will not log you out.
How do I go back to TBG auth?
If things are going well, but you just want to go back, this can be done from the Authentication page, just choose internal authentication. This will log you out, but other LDAP sessions should be unaffected. Otherwise the rest of the above applies.
We want your feedback! Please let us know on IRC and the forums what your experiences are with this module, and if you have any issues, please file a bug on our tracker. We want this module to be top quality before we do the final release of The Bug Genie 3.1.4 next month.
If you have any other questions, please let us know.