LdapNgPlugin

Introduction

This plugin provides an interface to query an LDAP directory and display the results in a TWiki topic. It can also be used to turn WikiNames from the LdapContrib database dynamic, presenting a LDAP-generated summary when hovering over them.

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"
}%

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

%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.

Also, see the following configuration flags for the dynamic WikiNames feature:

• $TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Enabled}
  Enable the dynamic WikiNames feature, for a LDAP-generated summary when hovering over a WikiName
• $TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{RequireLoggedIn}
  Require that the user is authenticated to use the dynamic WikiName feature
• $TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Filter}
  What classifies a user? Give a LDAP filter here, like objectClass=posixAccount
• $TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Format}
  How should the dynamic WikiNames box be formatted? Example: |Name|$givenName $sn|$n|Mail|$mail|

See example on dynamic WikiNames further down.

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.

Dynamic WikiNames

Given that the following facts are true:

• JQueryPlugin is enabled in your Wiki.
• You're logged in.
• LoginName jdoe with WikiName JohnDoe is present in the LdapContrib database.
• LoginName jdoe is present in your LDAP server.
• The LDAP entry for LoginName jdoe includes the following fields:

...
objectClass=user
cn: jdoe
name: John Robert Doe
mail: john.doe@example.com
...

• You have entered the following setting in /lib/LocalSite.cfg:

$TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Enabled} = 1;
$TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{RequireLoggedIn} = 1;
$TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Filter} = 'objectClass=user';
$TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Format} = '<a href="https://phonebook.mycompany.com/?user$cn">Go to phonebook &raquo;</a>$n|Name|$name|$n|Mail|$mail|';

This should yield the following result (note: the mouse cursor is hidden in the picture):

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/Config.spec
  lib/TWiki/Plugins/LdapNgPlugin.pm
  pub/TWiki/LdapNgPlugin/DynamicWikiNames.css
  pub/TWiki/LdapNgPlugin/DynamicWikiNameExample.png
  pub/TWiki/LdapNgPlugin/DynamicWikiNames.js
  pub/TWiki/LdapNgPlugin/spinner.gif

• 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
  TWiki::Plugins::JQueryPlugin	>=1.0	Required for the dynamic WikiNames option

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-05-19:	TWikibug:Item7496: Added option to make WikiNames dynamic by presenting a LDAP-generated summary when hovering over them.
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