LdapNgPlugin

Introduction

This plugin provides an interface to query an LDAP directory and display the results in a TWiki topic. It is a complete rewrite of the TWiki:Plugins.LdapPlugin by TWiki:Main.GerardHickey to provide greater flexibility and performance based on the TWiki:Plugins.LdapContrib package.

Tags provided by the plug-in

%LDAP{...}% and %LDAPUSERS{...}% are provided by this plug-in

Examples

%LDAP{"(objectClass=posixAccount)" 
  base="(ou=people)"
  limit="10" 
  header="| *Nr* | *Name* | *Mail* | *Photo* |$n" 
  format="| $index | $cn | $mail | <img src=\"$jpegPhoto\" alt=\"$cn\" title=\"$cn\" width=\"100px\"> |" 
  footer="$n<br/><font color='red'>$count users</font>" 
  sort="cn"
  clear="$mail,$jpegPhoto"
}%

%LDAP{"(objectClass=posixGroup)" 
  base="(ou=group)" 
  limit="10" 
  header="| *Nr* | *Group* | *Members* |$n" 
  format="| $index | $cn | $memberUid |" 
  sort="cn"
  clear="$mail,$jpegPhoto"
}%

%LDAPUSERS{limit="10"}%

Plugin Settings

The LdapNgPlugin will use the default configuration of the LdapContrib in your LocalSite.cfg file, that is

• $TWiki::cfg{Ldap}{Host} (overridable per query)
• $TWiki::cfg{Ldap}{Port} (overridable per query)
• $TWiki::cfg{Ldap}{Base} (overridable per query)
• $TWiki::cfg{Ldap}{Version} (overridable per query)
• $TWiki::cfg{Ldap}{SSL} (overridable per query)
• $TWiki::cfg{Ldap}{BindDN}
• $TWiki::cfg{Ldap}{BindPasswd}

In addition, the following configuration items are there. All are optional and have no problem not setting.

• $TWiki::cfg{Plugins}{LdapNgPlugin}{UseDefaultServer}
  You may have only one LDAP server and there is no point in sepcifying a server in %LDAP{...}%. Besides, LdapContrib might be used elsewhere. If both conditions are met, you should consider setting this preference true. If so, this plug-in always ignore host, port, version, ssl parameters and connects to the LDAP server specified by the LdapContrib configuration. The goal is to share an LDAP connection with other TWiki features using it. Please be noted the LDAP connection shared with others is not automatically destroyed. You need to make sure it's destroyed when a TWiki session is destroyed. Otherwise, if this plug-in is used in Fasc CGI or mod_perl, LDAP connections may accumulate.
• $TWiki::cfg{Plugins}{LdapNgPlugin}{DisableLDAPUSERS}
  If you have thousands of users and uses LDAP, you need to disable %LDAPUSER{...} because it would yield a large amount of data otherwise.
• $TWiki::cfg{Plugins}{LdapNgPlugin}{Helper}
  The class of helper functions. Please see #Helper_Class.
• $TWiki::cfg{Plugins}{LdapNgPlugin}{CacheBlob}
  If true, attributes whose name contain jpegPhoto are cached. This is introduced on 2012-10-15. Before that, jpegPhoto data was always cached. As such, to keep the old behavior, you need to set this true.
• $TWiki::cfg{Plugins}{LdapNgPlugin}{AutoClear}
  In the format, header, and footer parameters, $attribute which is not defined in a record ends up being literal $attribute in output. You need to put it in the clear parameter (e.g. clear="$telephonenumber,$mobile") to suppress literal $attribute from showing up.
  Setting {Plugins}{LdapNgPlugin}{AutoClear} true makes the clear parameter unnecessary. However, this causes slight incompatibility in some cases. You may put %LDAP{...}% inside a tag and put $something for the outer tag. if {Plugins}{LdapNgPlugin}{AutoClear} is true, you need to put it as $dollarsomething.

Helper Class

%LDAP{...}% basically does a single LDAP query as specified. For practical use, that may be insufficient in two aspects.

• There might be a user who doesn't care enough and issues an inappropriate query posing too much load to the server.
• Some typical operations such as getting the list of the members of a group may be too cumbersome. For that, you need to nest two %LDAP{...}%s - the outer one gets the list of members while the inner one retrieves each member's attributes. It would be user friendly to do it by e.g. %LDAP{"group=GROUP_NAME" ...}%.

To cope with these issues, you can have your LdapNgPlugin helper class by having the following line on lib/LocalSite.cfg.

$TWiki::cfg{Plugins}{LdapNgPlugin}{Helper} = 'TWiki::Contrib::MyLdapNgPluginHelper';

package TWiki::Contrib::MyLdapNgPluginHelper;

sub lookupHelper {
    my ($class, $ldap, $filter, $params) = @_;
...

Arguments of lookupHelper()

$class gets the name of the class - "TWiki::Contrib::MyLdapNgPluginHelper" in this example.

$filter gets the filter parameter of %LDAP{...}%.

$params is a hash reference having values of the following parameters of %LDAP{...}%.

Return value of lookupHelper()

It's supposed to return a string or an array reference depending on situation.

An error

When an error occurred (e.g. the filter is not appropriate), an error message starting with = is returned.

A filter string

it may return $filter as is or after transforming it.

Array reference

it may return a referenct to an array of an LDAP query result. The result of a group=xxx filter would be in this type.

Plugin Installation Instructions

• Run configure for automated install, or do a manual install:
• Download the ZIP file from the Plugin web (see below)
• Unzip LdapNgPlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/LdapNgPlugin.txt
  data/TWiki/VarLDAP.txt
  data/TWiki/VarLDAPUSERS.txt
  lib/TWiki/Plugins/LdapNgPlugin/Core.pm
  lib/TWiki/Plugins/LdapNgPlugin.pm

• Optionally, run LdapNgPlugin_installer.pl 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.
• Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.
• Dependencies:

  Name	Version	Description
  TWiki::Plugins	>=1.1	TWiki Dakar release.
  TWiki::Contrib::LdapContrib	>=2.0	Required
  Unicode::MapUTF8	>=1.11	Required for Perl prior to 5.8. Download from CPAN:Unicode::MapUTF8 if needed

Plugin Info

This work was partly funded by Spanlink Communications.

Plugin Author:	TWiki:Main.MichaelDaum
Copyright:	© 2006-2007 Michael Daum http://wikiring.de © 2006-2014 TWiki:Main.TWikiContributors
License:	GPL (GNU General Public License)
Plugin Version:	2013-03-25

Show Change History Hide Change History

2014-03-25:	TWikibug:Item7469: LdapNgPlugin topic to have a site specific description at the top
2013-02-01:	TWikibug:Item7134: LdapNgPlugin doesn't insert separator after header and before footer.
2012-12-28:	TWikibug:Item7108: {Plugins}{LdapNgPlugin}{AutoClear} introduced to make the clear parameter unnecessary. Documentation update - VarLDAP and VarLDAPUSERS are introduced
2012-10-17:	TWikibug:Item6986: the ifnull parameter has been renamed to default
2012-10-15:	TWikibug:Item6986: Enhancements and code clean-up
2011-01-14:	TWikibug:Item6530: Doc improvements
2010-04-25:	TWikibug:Item6433: Doc improvements
13 Nov 2007:	fixed $nop
01 Oct 2007:	added LDAPUSERS, lined up to changes in LdapContrib-2.0
04 June 2007:	don't convert from/to utf8 if the site charset is already utf8
18 Dec 2006:	added support for addresses as specified in RFC4517
04 Dec 2006:	map utf8 strings from LDAP to the site's encoding and vice versa
30 Nov 2006:	replaced commonTagsHandler with a properly registered LDAP tag
31 Aug 2006:	added NO_PREFS_IN_TOPIC
19 Jul 2006:	public release
25 April 2006:	Initial (internal) version

Perl Version:	5.8
TWiki:Plugins/Benchmark:	GoodStyle nn%, FormattedSearch nn%, LdapNgPlugin nn%
Plugin Home:	TWiki:Plugins/LdapNgPlugin
Feedback:	TWiki:Plugins/LdapNgPluginDev

Related Topics: TWikiPreferences, TWikiPlugins, LdapContrib