John-AM.com

I’m currently trying to get a knowledge base set up at my place of work.  Initially, I had used 68kb to set it up.  It was fantastic to work with (especially after installing TinyMCE as a plug in) but it had no access control or authentication, so management asked I look into alternatives with those features.  I found TWiki and set it up with LDAP / AD (Active Directory) authentication.  Since the documentation wasn’t helping me, I wrote some of my own in case anyone else needs some help, or if I would need to do it again.

For background, I’m installing this in Ubuntu desktop edition with apache server.  Also, this assumes the TWiki itself has been set up.  You should be able to go to http://yourserver/twiki/bin/view/TWiki/WebHome and see the TWiki main screen.

First get LDapContrib from here: http://twiki.org/cgi-bin/view/Plugins/LdapContrib at the time of writing the files are under “attachments” at the bottom.

Unzip it in your TWiki directory (on my VM this is /var/www/TWiki/ ) the zip has everything structured in the proper directories.

This next part is somewhat more difficult. The Perl dependencies for LdapContrib need to be installed.  Open a command line and run

sudo perl LdapContrib_installer

in your Twiki directory.  It will prompt you to install some software dependencies, and finish after downloading and installing.  You should see a screen like this:

If it is successful, skip the next section, you’re ready to configure LDAP.

If it hangs, you’ll have to install the Perl dependencies manually.  The list of dependencies is here in the documentation. If installing on Ubuntu, you’ll need the following from Synaptic Package Manager:

• libauthen-sasl-perl
• libnet-ldap-perl
• libio-socket-ssl-perl
• libunicode-maputf8-perl

DB_File is a core module and comes with the Perl installation.  The same applies to Digest::MD5.  If you don’t have them there are a few options: Try installing the above packages then run LdapContrib_installer again.  It will grab the modules if it can.  Otherwise, look up install instructions in the links provided. Finally, you could try updating Perl, which would bring in those modules – and it’d be a good excuse to keep your software secure and up to date.

Once the installation is done, you can proceed to set up your LDAP settings. You can manually configure everything via (file name) but it’s just as simple to do it via the configure script at http://yourserver/twiki/bin/configure.  There should be some new settings now for LDAP.

Before digging into those though, look at the security settings.  There are three settings we’re worried about here.  Authentication, User Mapping, and Passwords.  The settings you’ll need for LDAP Authentication are as follows:

This allows you to use LDAP credentials for login.  You will still be using the TWiki login screen to give users access, so if you need automatic sign in or SSO, you may need to find another solution. Speficially, you’ll want to look into Kerberos authentication and mod_kerb. However, it’s beyond what I’m attempting in this article.

If you’re receiving an error “Action “viewauth”: authentication required.” Then you may have set the LoginManager to TWiki::LoginManager::LdapApacheLogin. Change it to the settings above to correct the problem.

Under LDAP Settings the server, binding strings, and username / password will need to be configured first.  Then we’ll need to specify paths to users, the criteria used to determine what is a user, and what parts of that are the WikiName / login.  If you’re not familiar with LDAP binding strings, you’ll want to use this reference or use an Active Directory browser that can generate the bindings.  I used Apache Directory Studio, but it’s a large program for this task.  If a smaller program is found I will update this article.

The first thing to configure is connection settings.  This is just pointing the TWiki installation towards your AD / Ldap server, and giving it a username and password with which to perform authentication.

There are several other settings detailing security and certificates.  In my installation I was able to leave them all on their default values.  However if you use SASL / TLS / etc. You’ll need to fill out those fields.

The next section is user settings, this part gave me the most trouble, as I was unfamiliar with how TWiki was looking for user records. The way they do it is unintuitive, but incredibly flexible.  The important setting here is Login Filter.  This will tell TWiki what type of objects it should consider users.  And from there we can specify what it should use as a username, etc. The strength in this is that you can specify specifically what you want, and will not need to deal with assumptions on the part of TWiki’s designers on what end users would want for names or login settings.

Because of this these settings could vary significantly depending on your installation.

At this point you should be able to go to the TWiki main page and log in using your domain credentials. If not, double check your LoginFilter, and LoginAttribute. If these are set incorrectly your TWiki install won’t accept any usernames. Be sure to check the connection settings as well.

The final section is setting up group names. This is very similar to setting up users. Specify a path, and filter the results. Then add an attribute to determine members from.

Here are the settings:

If you’re not seeing the groups appear, try double checking the GroupFilter.  Also, if TWiki is creating a bunch of users named DN=Username, be sure to enable MemberIndirection.

That covers all the settings to get LDAP running.  It was quite a trip getting this all working, especially with my limited background with Ldap terms and settings.  When I was tweeting about it, I was actually asked by the TWiki Twitter Account to help update the documentation, which I plan to do soon.  Hopefully others will be able to benefit from my documentation on how to get it running as well.  Thanks for reading!