LdapPlugin < TWiki

---+!! 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.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ 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 =%<nop>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 <nop>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="&#124; <nop>*Name* &#124; <nop>*Phone* &#124;" |
| =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="&#124; $sn, $givenName &#124; $telephoneNumber &#124;" |
| =mvformat= | Separator for multi-value attributes | mvformat="&lt;br /&gt;" |
| =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 <nop>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=:

=%<nop>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:

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

Embed JPEG photos in the result:

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

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

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

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

---++ <nop>%TOPIC% Settings

Plugin settings are stored as preferences variables.  To reference
a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>LDAPPLUGIN_SHORTDESCRIPTION%==

   * One line description, shown in the %SYSTEMWEB%.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 <nop>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/%TOPIC%.txt== | Plugin topic |
   | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
   * Unzip ==%TOPIC%.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: | &copy; 2002-2004 TWiki:Main.GerardHickey <br /> &copy; 2006-2007 TWiki:Main.AndreasVoegele <br /> &copy; 2007-2011 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2011-01-14 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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.<br />added default FILTER definition (assigned on current TOPIC name translated into username).<br />added possibilty to define error message in case no record is found.<br />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.%TOPIC% |
|  Feedback: | TWiki:Plugins.%TOPIC%Dev |

__Related Topics:__ %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
This topic: TWiki > LdapPlugin
Topic revision: r1 - 15 Jan 2011 - TWikiContributor
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.LdapPlugin.