Tags:
create new tag
, view all tags, tagging instructions

LdapContrib

Powered by
WikiRing Consultants

This package offers basic LDAP services for TWiki and offers authentication of TWiki users by binding to an LDAP server as well as incorporate LDAP user groups into TWiki's access control. Note, however that you need at least TWiki-4.0.3 for that. Optionally, if you need an interface to query your LDAP directory and display the results in a TWiki topic install the TWiki:Plugins/LdapNgPlugin which will make use of the LdapContrib services. This work is a rewrite of the TWiki:Plugins/LdapPlugin by TWiki:Main/GerardHickey while bringing authentication, user management and other LDAP applications onto a common base.

Note: This package downloads all relevant records from your LDAP server into a local cache the first time you use it. This can take a noticeable period of time depending on the size of your LDAP database. This cache will be refreshed on a configurable interval (defaults to once a day). You can also disable automatic refreshing and refresh the LdapContrib's cache manually using the "Refresh Cache" button below. Read the documentation of the MaxCacheAge variable in the section "Performance Settings" below on how to configure the refesh intervals.

Tip: You can add this button on any page by adding

%INCLUDE{"%TWIKIWEB%.LdapContrib"}%
to it.

LDAP questionary

Before you can further configure TWiki's LDAP connection you will have to answer a set of basic questions about your LDAP server. These are:

  1. What's the host name (or IP address) of the LDAP server (e.g. ldap.my.domain.com)?
  2. What port does it listen to LDAP requests (e.g. 389)?
  3. Does your LDAP Server use SASL to authenticate connections? If so which authentication mechanism does it use (EXTERNAL, DIGEST-MD5, ...)?
  4. Do you have a kind of "proxy" user that TWiki can use to perform the initial connection? You need its DN and credentials. Advice: don't use the LDAP admin account, you only need a simple user that has read access to all of the directory (or the relevant parts); it does not need any write access.
  5. What is the "base dn" of the directory (e.g. dc=my,dc=domain,dc=com )?
  6. What is the common root/branch for all users? For example, Are they all found under ou=people,dc=my,dc=domain,dc=com or are they are scattered all over the place?
  7. What is the common root/branch where all groups are defined (e.g. ou=group,dc=my,dc=domain,dc=com)?
  8. What object class do user records have (e.g. objectClass=organizationalPerson )?
  9. What object class do group records have (e.g. objectClass=group )?
  10. Which attribute of a user record should be used to log in (must be unique)?
  11. Which attribute(s) of a user record do you want to use to construct a WikiName (used to display them in TWiki, pointing to their homepage)?
  12. What's the name attribute of a group?
  13. Which attribute in a group record defines its members (e.g. member or memberUid)? Note, that if the member attribute of a group is a DN you need to enable "member indirection" (see #Membership).

Collect the answers to these questions either yourself using your favorit LDAP browser, or ask your friendly LDAP admin.

Authentication

To make use of authentication of TWiki users using your LDAP server you you have to register the LdapUser class as the so called PasswordManager. This is done by adding the following lines in the lib/LocalSite.cfg configuration file (or by using the configure tool alternatively):
$TWiki::cfg{PasswordManager} = 'TWiki::Users::LdapUser';

There is a further option to fallback to TWiki's normal authentication mechanism by defining a secondary password manager. This allows you to create native TWiki accounts, e.g. a TWikiAdmin account and authenticate him without LDAP. Use the following setting to fallback to a htpasswd based authentication.

$TWiki::cfg{Ldap}{SecondaryPasswordManager} = 'TWiki::Users::HtPasswdUser';
So whenever authentication against LDAP fails, this second password manager will be used.

User Groups

LDAP group records can be used in TWiki's access control by registering a UserMappingManager implementation. This is done by adding the following to your lib/LocalSite.cfg configuration file (or by using the configure tool alternatively):
$TWiki::cfg{UserMappingManager} = 'TWiki::Users::LdapUserMapping';

In addition you can decide if you want to add the LDAP groups to TWiki or use LDAP groups solely. This is controled by the TWikiGroupsBackoff flag. If switched on then LDAP groups will be added. If there's a name clash LDAP groups take precedence. If switched off TWikiGroups are ignored.

You might decide in not using your LDAP groups in TWiki but still map login names to WikiNames. Both, LDAP user groups and name mapping is done by the UserMappingManager. So to make use of name mapping but not its group feature, register the LdapUserMapping implementation for the UserMappingManager but disable the MapGroups setting.

Membership

LDAP servers follow different schemata to define "membership". They store the information either using a set of unique ids in the group object (posixGroup) or the full DNs of the user objects (groupOfNames). In the latter case the user objects' unique ids have to be fetched separately based on their distinguished name. This mode has to be switched on using the MemberIndirection setting.

Note, that the reverse relation where the user objects store in which group they participate (for example using a memberOf attribute) is maintained by some LDAP servers automatically. Those that encode membership this way only are not supported by the LdapContrib yet.

Furthermore, user objects may have a primary group attribute (posixAccount). This is a simple value (vs. multi-value) and stores the id of a default group that user is member of. This information is not used by the LdapContrib.

In short, the LdapContrib reads membership information as they are stored in the group objects only, and may map the member object indirectly to the login name.

Normalization of login, wiki and group names

LdapContrib reads three kinds of names from your LDAP server and reuses these to identify the related entities in TWiki. These are the login names - used to log in -, the WikiNames - used to display users online -, and the group names - used in access control lists.

The WikiName can be generated by setting the two parameters WikiUserNameAttribute and NormalizeWikiName. WikiUserNameAttribute can be a comma separated list of LDAP attributes that are then assembled to form the WikiName. If the NormalizeWikiName flag is set a couple of extra operations are performed to generate a proper WikiName, i.e. removing illegal characters. Given the setting

$TWiki::cfg{Ldap}{WikiNameAttribute} = 'givenName,sn';
$TWiki::cfg{Ldap}{NormalizeWikiNames} = 1;
The givenName and sn (surname) LDAP attributes will be fetched and concatenated to form a WikiName, so that "givenName=Hans-Peter,sn=Leuth´┐Żuser-Schnarrenberg" will result in the WikiName "HansPeterLeuthaeuserSchnarrenberg". If one of the WikiNameAttributes is 'mail' the @mydomain.com part will be removed all together.

The login name can be normalized by enabling the

$TWiki::cfg{Ldap}{NormalizeLoginNames} = 1;
setting. However the normalized result will not be forced to be a cammel case WikiName.

Similar to the WikiName of a user, group names can be normalized using

$TWiki::cfg{Ldap}{NormalizeGroupNames} = 1;

If a user in your LDAP directory changed his name, e.g. because of a mariage, this use can be mapped to his/her old account using an alias that points back from the old WikiName to the new one. This is done using a setting like this:

$TWiki::cfg{Ldap}{WikiNameAliases} = 'MaryMalone=MaryForrester, ...'
The parameter takes a comma separated list of FromWikiName=ToWikiName. Whenever this account is still used in a TWiki access control list, its rights will be inheritted by the targeted ToWikiName account.

SSO and LdapContrib

First of all, LdapContrib does not provide any SSO solution. Nor does LDAP per se. However, LDAP directories might come with SSO facilities that they provide via kerberos or similar. Unfortunately, nowaday browsers themselves are not kerberized. They depend on talking to the webserver using HTTP means, which then decides which tickets are valid for the remote user by talking to the acutal authority. That is, authentication is implemented using an approriate apache module.

LdapContrib can then be used to complete an LDAP integration of TWiki by providing the mapping to WikiNames as well as email information and group definitions drawn from the LDAP directory directly.

The remaining problem is that, when a new user has been added to your LDAP directory recently, and he/she then dashes off to sign on to TWiki right away, LdapContrib's cache most probably is outdated. This situation is different from one where users were authenticated by TWiki's own TemplateLogin mechanism. The user would then not be able to login until the cache has been refreshed manually or automatically.

So when the new user is authenticated using SSO and then hits TWiki, it might fail to compute the proper WikiName. The solution to this problem is to use the LdapApacheLogin login manager as a drop in replacement to the standard ApacheLogin that would have been used in this situation. The LdapApacheLogin will then take care that the remote user is known to the cache and add this single record if it is missing.

Bottomline: whenever you are using apache to authenticate to TWiki, do use the LdapApacheLogin manager. Or in other words, whenever you configured TWiki to use the standard ApacheLogin manager, and you now install LdapContrib, change it to LdapApacheLogin to assure LdapContrib's cache is up to date.

Simple Example

For the sake of this documentation we assume that users accounts in your database are at leat of the type posixAccount and optionally also of type inetOrgPerson storing email addresses. Moreover users are stored in a subtree ou=people and groups are defined in ou=group. Here are some example LDAP records:
dn: uid=testuser1,ou=people,dc=my,dc=domain,dc=com
objectClass: inetOrgPerson
objectClass: posixAccount
cn: Test User1
uid: testuser1
uidNumber: 1024
gidNumber: 100
homeDirectory: /home/testuser1
loginShell: /bin/bash
mail: testuser1@my.domain.com

dn: uid=testuser2,ou=people,dc=my,dc=domain,dc=com
objectClass: inetOrgPerson
objectClass: posixAccount
cn: Test User2
uid: testuser2
uidNumber: 1024
gidNumber: 100
homeDirectory: /home/testuser2
loginShell: /bin/bash
mail: testuser2@my.domain.com
mail: testuser2@gmx.com

# users, Group, nats.informatik.uni-hamburg.de
dn: cn=users,ou=group,dc=my,dc=domain,dc=com
objectClass: posixGroup
cn: users
gidNumber: 100
memberUid: testuser1
memberUid: testuser2

Please have a look at your LDAP manual on how to set up an LDAP server and populate it with user account records. Have a look at the Quick-Start Guide on how to install OpenLdap.

Use the following settings for the above example:

$TWiki::cfg{Ldap}{Host} = 'ldap.my.domain.com';
$TWiki::cfg{Ldap}{Port} = 389; 
$TWiki::cfg{Ldap}{UserBase} = 'ou=people,dc=my,dc=domain,dc=com'; 
$TWiki::cfg{Ldap}{LoginFilter} = 'objectClass=posixAccount';
$TWiki::cfg{Ldap}{LoginAttribute} = 'uid';
$TWiki::cfg{Ldap}{WikiNameAttribute} = 'cn';
$TWiki::cfg{Ldap}{NormalizeWikiNames} = 1; 
$TWiki::cfg{Ldap}{GroupBase} = 'ou=group,dc=my,dc=domain,dc=com';
$TWiki::cfg{Ldap}{GroupFilter} = 'objectClass=posixGroup';
$TWiki::cfg{Ldap}{GroupAttribute} = 'cn';
$TWiki::cfg{Ldap}{MemberAttribute} = 'memberUid';
$TWiki::cfg{Ldap}{MemberIndirection} = 0;
$TWiki::cfg{Ldap}{MapGroups} = 1;

Configuration

The LdapContrib package is configured using a set of variables that need to be added to the lib/LocalSite.cfg configuration file. Use the configure tool (at least once) after you installed this package. Have a lookg at your lib/LocalSite.cfg file afterwards. You might also make your changes therein directly to accomodate your TWiki installation to your specifc LDAP installation and user accounting.

Connection settings

IP address (or hostname) of the LDAP server:
$TWiki::cfg{Ldap}{Host} = 'ldap.my.domain.com';

Port used when binding to the LDAP server:

$TWiki::cfg{Ldap}{Port} = 389; 

LDAP protocol version to use when querying the server; Possible values are: 2, 3

$TWiki::cfg{Ldap}{Version} = '3'; 

Base DN to use in searches:

$TWiki::cfg{Ldap}{Base} = 'dc=my,dc=domain,dc=com'; 

The DN to use when binding to the LDAP server; if undefined anonymous binding will be used. Example 'cn=proxyuser,dc=my,dc=domain,dc=com'

$TWiki::cfg{Ldap}{BindDN} = 'cn=proxyuser,dc=my,dc=domain,dc=com'; 

The password used when binding to the LDAP server using the BindDN account:

$TWiki::cfg{Ldap}{BindPassword} = 'secret'; 

Use SASL authentication when binding to the server; Note, when using SASL the BindDN and BindPassword setting are used to configure the SASL access.

$TWiki::cfg{Ldap}{UseSASL} = 0; 

List of SASL authentication mechanism to try (defaults to 'PLAIN CRAM-MD5 EXTERNAL ANONYMOUS'):

$TWiki::cfg{Ldap}{SASLMechanism} = 'PLAIN CRAM-MD5 EXTERNAL ANONYMOUS';

User settings

The options below configure how TWiki will extract account records from LDAP.

Define the DN of the users tree (defaults to $TWiki::cfg{Ldap}{Base}):

$TWiki::cfg{Ldap}{UserBase} = 'ou=people,dc=my,dc=domain,dc=com'; 

Filter to be used to find login accounts:

$TWiki::cfg{Ldap}{LoginFilter} = 'objectClass=posixAccount'; 

Define the user login name attribute (must contain a unique value for each user):

$TWiki::cfg{Ldap}{LoginAttribute} = 'uid'; 

Define the WikiUserName attribute(s):

$TWiki::cfg{Ldap}{WikiNameAttribute} = 'cn'; 

Enable/disable normalization of WikiUserNames as they come from LDAP:

$TWiki::cfg{Ldap}{NormalizeWikiNames} = 1; 

Enable/disable normalization of login names as they come from LDAP:

$TWiki::cfg{Ldap}{NormalizeLoginNames} = 1; 

Alias old WikiNames to new account. This is a comma separated list of "OldName=NewName" values.

$TWiki::cfg{Ldap}{WikiNameAliases} = '';

Allow/disallow changing the LDAP password using TWiki's ChangePassword feature

$TWiki::cfg{Ldap}{AllowChangePassword} = 0; 

Define a secondary password manager used to authenticate users that are registered to TWiki natively. Note, that this must not be TWiki::Users::LdapUser again!

$TWiki::cfg{Ldap}{SecondaryPasswordManager} = 'none';

Group settings

The settings below configures the mapping and processing of login names and WikiNames as well as the use of LDAP groups in TWiki.

Define the DN of the groups tree (defaults to $TWiki::cfg{Ldap}{Base})

$TWiki::cfg{Ldap}{GroupBase} = 'ou=group,dc=my,dc=domain,dc=com'; 

Filter to be used to find groups:

$TWiki::cfg{Ldap}{GroupFilter} = 'objectClass=posixGroup'; 

Define the group name:

$TWiki::cfg{Ldap}{GroupAttribute} = 'cn'; 

Define the attribute of a group that defines its members:

$TWiki::cfg{Ldap}{MemberAttribute} = 'memberUid'; 

Flag to indicate wether the member attribute of a group stores a DN:

$TWiki::cfg{Ldap}{MemberIndirection} = 1; 

Enable/disable reusage of groups defined in TWiki natively:

$TWiki::cfg{Ldap}{TWikiGroupsBackoff} = 1; 

Enable/disable normalization of group names as they come from LDAP:

$TWiki::cfg{Ldap}{NormalizeGroupNames} = 1; 

Enable/disable mapping LDAP groups; you might decide to set this to 0 and still use the LdapUserMapping implementation to construct proper WikiNames from login names with its help.

$TWiki::cfg{Ldap}{MapGroups} = 1; 

Performance settings

Maximum time a cache is kept; default is 86400 seconds;
$TWiki::cfg{Ldap}{MaxCacheAge} = 86400; 

Maximum size of the result set that the server can return; set it to 0 for unrestricted results:

$TWiki::cfg{Ldap}{PageSize} = 500; 

Prevent certain names from being looked up in LDAP:

$TWiki::cfg{Ldap}{Exclude} = 'TWikiGuest, TWikiContributor, TWikiRegistrationAgent, TWikiAdminGroup, Trash.MainNobodyGroup1'; 

Updating the LDAP cache using a cronjob

In some environments, updating the internal LDAP cache of the LdapContrib might take considerable time. The intervals the cache data is thought to be "expired" is configured using the MaxCacheAge setting. This setting defaults to updating the cache every 24 hours. The refresh procedure will then be triggered by the first request that hits TWiki when this period expired.

To remove this burden from the "first visitor in the morning", the automatic refresh procedure can be disabled by setting

$TWiki::cfg{Ldap}{MaxCacheAge} = 0; 
This means that the age of the cached data will not be checked automatically anymore. The responsibility that the data is updated is now up to you, that is you have to update the cache explicitly. This can be done by either hitting the red "Refresh Cache" button above, or by setting up an appropriate cronjob on the machine running your TWiki server.

To trigger an explicit update of the cache on 5 past midnight every day use a cronjob similar to:

5 0 * * * cd <twiki-install-path>/bin && ./view refreshldap=on Main/WebHome >/dev/null
This will call TWiki on the commandline and provide the necessary query parameters so that the LdapContrib will force an update of the cache data.

Implementation documentation

%$POD%

Installation Instructions

  • Download the ZIP file from the Plugin web (see below)
  • Unzip LdapContrib.zip in your TWiki installation directory. Content:
    File: Description:
%$MANIFEST%
  • Optionally, run LdapContrib_installer to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
  • Alternatively, manually make sure the dependencies listed in the table below are resolved. %$DEPENDENCIES%
  • Read the the above documentation, i.e. the Configuration section.
  • Use configure to set the LDAP settings.
  • There's a patch for TWiki-4.1.2 that backports the fixes to the %GROUPS% tag to suppress "new topic links" in the produced table. Apply it using
    cd <twiki-root>/lib; patch < ../pub/TWiki/LdapContrib/TWikiDotPm-4.1.2.patch

Contrib Info

Author: TWiki:Main/MichaelDaum
Copyright ©: 2006-2007 Michael Daum http://michaeldaumconsulting.com
This work was partly funded by Spanlink Communications and Trivadis
License: GPL (GNU General Public License)
Version: v2.99.5
Change History:  
25 May 2008: added alias feature, fixed normalization error, fixed cache update issue added login manager for 4.2
05 May 2008: implemented WikiNamesAliases
14 Feb 2008: allow to disable cache aging setting MaxCacheAge to zero
01 Feb 2008: distinguish groups clashing with user names by appending a suffix
30 Jan 2008: first beta towards TWiki-4.2
07 Jan 2008: fixed initializing the cache
21 Dec 2007: added LdapApacheLogin, made updating the cache quasi atomic
22 Nov 2007: fixed recognition of TWikiGroups in a mixed setting
05 Oct 2007: enabled native user registration using the secondary password manager; added support to change a user's LDAP password from within TWiki; added patch for TWiki.pm that backports some of the fixes from TWiki-4.2 to TWiki-4.1.2
05 Sep 2007: added SASL support, added normalization of login and group names, added secondary password manager
31 Aug 2007: rewrite of the cache
08 June 2007: don't use the store object during TWiki's destructore; don't lookup login names of groups
04 June 2007: don't be casesensitive for login names; fixed several utf8 issues; fixed crash when no groups where found; caching mapping privately; added MaxCacheAge; added support for nested LDAP groups
30 Apr 2007: fixed return value on illegal lookup calls
24 Apr 2007: be robust against the lookup-API being called with the wrong parameters; added Debug flag; fixed/improved group loading; deprecating BasePasswd in favor of UserBase; deprecating BaseGroup in favor of GroupBase
04 Apr 2007: fixed group mapping on >4.1.2; renamed BasePasswd config parameter to UserBase; renamed BaseGroup config parameter to GroupBase; working around broken configure in 4.1.x
12 Jan 2007: enhanced normalization of WikiNames so that they are proper WikiWords; WikiNames can be constructed from a list of LDAP attributes now
18 Dec 2006: various performance improvements; fixed usage of limit argument; renamed configuration option "WikiNameRemoveWhiteSpace" to "NormalizeWikiName"; support for large databases using paged LDAP search results; new configuration option "Exclude" to exclude standard TWiki user accounts, e.g. TWikiRegistrationAgent, from being looked up in LDAP; added support for faster API implementing isMemberOf; added Config.spec file to integrate the LadpContrib into Twiki's "configure" tool; added support for WikiNames derived from mail attributes
03 Nov 2006: fixed binding to the server by first searching the full dn instead of assuming a fixed one (issue found by Cederic Weber); added new feature MapGroup to be able to switch off group mapping and have ; login-to-wikiname conversion only
02 Aug 2006: added a user accounts in memory cache
19 July 2006: public release
24 May 2006: api adjustments, improved wikiname generation
28 Apr 2006: Initial version
Home: TWiki:Plugins/LdapContrib
Feedback: TWiki:Plugins/LdapContribDev
Appraisal: TWiki:Plugins/LdapContribAppraisal

-- TWiki:Main/MichaelDaum - 25 May 2008

Topic revision: r2 - 14 Jan 2009 - 17:15:21 - CTSpediaAdmin
 
Copyright &ę by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CTSPedia? Send feedback