LDAP Plugin

<--
   Contributions to this TWiki plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/LdapPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/LdapPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Introduction

This plugin was written by TWiki:Main.GerardHickey to allow data to be pulled out of an LDAP directory and displayed in a TWiki topic. See TWiki:Plugins.LdapNgPlugin for an alternative plugin.

Syntax Rules

LDAP directory search

Write the tag %LDAP{ parameters }% anywhere in a TWiki topic to define an LDAP directory search. Use the format="..." parameter to define the output format of the search result. Valid parameters are

Name	Description	Example
host	LDAP host to query	host="ldap://ldap.example.org:389"
starttls	Perform StartTLS extended operation	starttls="yes"
base	LDAP search base	base="ou=People,o=example"
filter	LDAP search filter	filter="(fullName=Gerald Skerbitz)"
header	Optional format of the header for the result table	header="| *Name* | *Phone* |"
format	Format of the data returned by the search. Use $attribute for the fields. Use the word FIELDLIST if you want a list of the valid attributes in the LDAP directory for the data.	format="| $sn, $givenName | $telephoneNumber |"
mvformat	Separator for multi-value attributes	mvformat="<br />"
order	Sort order	order="sn,givenName"
reverse	Reverse the order of the result set	reverse="yes"
skip	Offset into the result set	skip="75"
limit	Limit the number of rows returned	limit="25"
jpegphoto	LDAP attribute to extract a JPEG photo. The field name, e.g. $jpegPhoto, will be replaced with a URL to an image.	jpegphoto="jpegPhoto"
jpegdefaultphoto	URL of a default photo for an LDAP entry without a photo	jpegdefaultphoto="/photos/default.jpg"
notfounderror	Error message you want to get in case LdapPlugin found nothing. Useful to define Javascript vars (see TWiki:Codev.TWikiLdapRegistration)	notfounderror="No contacts found"

More examples

Search for a specific entry and return the value of the attribute telephoneNumber:

%LDAP{host="ldap.example.org" base="ou=purchasing,o=example" filter="(employeenumber=00009707)" format="$telephoneNumber"}%

Search for all entries where fullName begins with Johnson and output the result in a table:

%LDAP{host="ldap.example.org" base="ou=finance,o=example" filter="(fullName=Johnson*)" format="| $ou | $telephoneNumber |" header="| *OU* | *Phone* |"}%

Embed JPEG photos in the result:

%LDAP{format="Name: *$cn* <img src=\"$jpegPhoto\" width=\"100\" />" jpegphoto="jpegPhoto"}%

The CGI parameter ldapfilter can be used to define the filter for the LDAP search. Put the following on a wiki page:

<form action="%SCRIPTURL%/view%SCRIPTSUFFIX%/%MAINWEB%/LdapPeople">
Filter: <input type="text" name="ldapfilter" size="25" />
<input type="submit" value="LDAP Search" />
</form>

...and the LdapPeople page will be called up with your input as the filter.

LdapPlugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %LDAPPLUGIN_SHORTDESCRIPTION%

• One line description, shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Retrieve data from an LDAP directory to show in TWiki topics.

• LDAP host to connect to access the directory:
  • Set HOST = ldap://ldap.example.org:389

• Perform StartTLS extended operation:
  • Set STARTTLS = 0

• Base DN to use for searching the LDAP directory:
  • Set BASE = ou=whatever,dc=example,dc=org

• Default filter: (The string TOPIC will be replaced in the default filter with the topic of the page on which the LDAP tag is located. That way you can use the Wiki username extracted from current topic name to automatically display LDAP user information from any Wiki Home page.)
  • Set DEFAULTFILTER =

• Default values:
  • Set HEADER =
  • Set FORMAT =
  • Set MVFORMAT =
  • Set ORDER =
  • Set REVERSE =
  • Set SKIP =
  • Set LIMIT =
  • Set JPEGPHOTO =
  • Set JPEGDEFAULTPHOTO =

• Message displayed when a search returned no entries:
  • Set NOTFOUNDERROR =

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

• Run configure for automated install, or do a manual install:
• Install the Net::LDAP module from CPAN or other source.
• Download the ZIP file from the Plugin web (see below). Contents:

  File:	Description:
  data/TWiki/LdapPlugin.txt	Plugin topic
  lib/TWiki/Plugins/LdapPlugin.pm	Plugin Perl module

• Unzip LdapPlugin.zip in your twiki installation directory.
• Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

Plugin Info

Plugin Author:	TWiki:Main.GerardHickey
Copyright:	© 2002-2004 TWiki:Main.GerardHickey © 2006-2007 TWiki:Main.AndreasVoegele © 2007-2011 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2011-01-14
Change History:	<-- versions below in reverse order -->
2011-01-14:	TWikibug:Item6530: Doc improvements; changing TWIKIWEB to SYSTEMWEB -- TWiki:Main.PeterThoeny
11 Jul 2007:	Add reverse, skip, and limit settings. TWiki:Main.AndreasVoegele
02 Oct 2006:	Bug fix release. The search filter is converted to UTF-8. TWiki:Main.AndreasVoegele
13 May 2006:	Bug fix release. Requires Perl 5.8. TWiki:Main.AndreasVoegele
04 Mar 2006:	Fixes for Cairo and Dakar. TWiki:Main.AndreasVoegele
05 Apr 2004:	Added sort Order. TWiki:Main.GeraldSkerbitz
04 Feb 2004:	Accomodate multiple values per attribute. TWiki:Main.GeraldSkerbitz, TWiki:Main.PatrickNomblot
02 Feb 2004:	Code and doc cleanups. basedn changed to base everywhere. TWiki:Main.GeraldSkerbitz
14 Jan 2004:	CGI now allowed and Default filter set on Preferences page. TWiki:Main.GeraldSkerbitz, TWiki:Main.PatrickNomblot
13 Jan 2004:	Added utf processing - another dependency! TWiki:Main.GeraldSkerbitz
09 Dec 2003:	Changed Photo processing code to NOT include the IMG tag. This will break things for people doing photos!!!! TWiki:Main.GeraldSkerbitz
27 Mar 2003:	added LDAP photo extract/display. added default FILTER definition (assigned on current TOPIC name translated into username). added possibilty to define error message in case no record is found. intended to work (also) well with TWiki Ldap Registration. TWiki:Main.PatrickNomblot
24 Apr 2002:	Modified to remove reference to show. Fields are now extracted from format. TWiki:Main.GeraldSkerbitz
23 Apr 2002:	Modified to return multiple attributes and rows with formatting. TWiki:Main.GeraldSkerbitz
22 Apr 2002:	Modified to use quoted strings in params. TWiki:Main.GeraldSkerbitz
11 Jan 2002:	Initial version
CPAN Dependencies:	Net::LDAP
Other Dependencies:	none
Perl Version:	5.8
Plugin Home:	TWiki:Plugins.LdapPlugin
Feedback:	TWiki:Plugins.LdapPluginDev

Related Topics: TWikiPreferences, TWikiPlugins