Configuring LDAP with TWiki

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: 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:

TWiki LDapContib Finished

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:

Topic Parameter Setting
Authentication LoginManager TWiki::LoginManager::TemplateLogin
User Mapping UserMappingManager TWiki::Users::LdapUserMapping
Passwords PasswordManager TWiki::Users::LdapUser

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.

Settings Example / Default Definition
Ldap Host domainname.local Your AD or domain server.
Ldap Post 389 Ldap server port number
Ldap Version 3 Ldap version. Should only be changed if an older version of Ldap is used.
Ldap Base dc=domainname,dc=local The base of your AD structure. The example is based off the LDap server name.
Ldap BindDN CN=TWikiUser,CN=Users,
(One Line)
Username Twiki should use for accessing user data.  Only needs read-only access to active directory.  Don’t use an admin account.
Ldap Bindpassword password Password for the user defined in Ldap BindDN

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.

Settings Example / Default Definition
Ldap UserBase CN=Users,
The path to the list of users you want to authenticate in TWiki.
Ldap LoginFilter objectClass=user This is a filter which will tell TWiki what to consider a user account.  If this is set incorrectly users won’t be recognized.
Ldap LoginAttribute cn The attribute of the object that should be used for logging in.  cn would give a login such as username@domain.local. Find a setting that works for you.
Ldap WikiNameAttribute name Attribute used for the Wiki Name. This will show up when the user edits an article or comments.
Ldap NormalizeWikiNames Enabled Normalizes names coming in from AD, to prevent errors. Leave enabled unless specifically needed.
Ldap NormalizeLoginNames Enabled Performs normalization on login names.
Ldap WikiNameAliases Connects old Wikinames to accounts in AD.
Ldap AllowChangePassword Disabled Allows users to change their password through TWiki. I see no reason to allow this, but to each their own.
Ldap SecondaryPasswordManager none Provides an additional form of authentication if Ldap fails. Can be set to apache authentication, or none.

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:

Settings Example / Default Definition
Ldap GroupBase CN=Users,
The path to the list of groups you want to use in TWiki.
Ldap GroupFilter objectClass=group This is a filter which will tell TWiki what to consider a group.  If this is set incorrectly groups won’t be made, or the wrong things will be considered groups.
Ldap GroupAttribute name This attribute will be the name of the group within TWiki.
Ldap MemberAttribute member Members of the group.  TWiki will assign members to groups if this is set correctly.
Ldap MemberIndirection Disabled If your member records for groups all appear as “DN=User” or similar, this will correct that.
Ldap TWikiGroupsBackoff Enabled Tells TWiki to fall back on TWiki-based groups if needed.
Ldap NormalizeGroupNames Disabled Normalizes group names to prevent errors. Leave enabled unless specifically needed.
Ldap MapGroups Enabled Allows use of the LDAP groups on TWiki.  If this is disabled LDAP groups won’t be used.

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!

  1. Dear Sir,

    It very good post. Thanks for your time.

    I have question about this :

    “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”

    Which authentication method you use at initial installation and configuration. I mean Local authentication or Apache?

    I have configured template login, twiki internal auth and registration work. Can I use this doc to switch from template login from Ldap?

    Any suggestion or guide.

    – Mohan L

    • Local authentication was used at the beginning. The setup even has an option where you can specify local as a fall-back authentication. I recommend doing this until LDAP is properly configured.

  2. Thx for the hint about the Login Manager, took me hours to figure that out 😉

  3. Dear Sir,

    Could you please tell me if this could work on Debian Squeeze ?


  4. Hi John,

    It is a very good post.It helpmed me a lot.Thanks a lot.
    In my case ,I have an user attribute called title in LDap directory.I need to map twiki group based on that attribute.How can I achieve this?

Leave a Comment

NOTE - You can use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>