LdapNgPlugin < TWiki

---+!! <nop>%TOPIC%
<!--
    Contributions to this plugin are appreciated. Please update the plugin page
    at http://twiki.org/cgi-bin/view/Plugins/LdapNgPlugin or provide feedback
    at http://twiki.org/cgi-bin/view/Plugins/LdapNgPluginDev.
    If you are a TWiki contributor please update the plugin in the SVN repository.
-->
%VAR{"LDAP_NG_PLUGIN_TOP" default="<nop>" ignorenull="on"}%
<sticky>
<div class="twikiTocFloat">
%TOC{title="Page contents"}%
</div>
</sticky>
%SHORTDESCRIPTION%

---++ 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

[[VarLDAP][%<nop>LDAP{...}%]] and [[VarLDAPUSERS][%<nop>LDAPUSERS{...}%]] are provided by this plug-in
 
---++ Examples
<pre>
%<nop>LDAP{"(objectClass=posixAccount)" 
  base="(ou=people)"
  limit="10" 
  header="| *Nr* | *Name* | *Mail* | *Photo* |$n" 
  format="| $index | $cn | $mail | &lt;img src=\"$jpegPhoto\" alt=\"$cn\" title=\"$cn\" width=\"100px\"&gt; |" 
  footer="$n&lt;br/&gt;&lt;font color='red'&gt;$count users&lt;/font&gt;" 
  sort="cn"
%IF{"{Plugins}{LdapNgPlugin}{AutoClear}" else="  clear=\"$mail,$jpegPhoto\"
"}%}%

%<nop>LDAP{"(objectClass=posixGroup)" 
  base="(ou=group)" 
  limit="10" 
  header="| *Nr* | *Group* | *Members* |$n" 
  format="| $index | $cn | $memberUid |" 
  sort="cn"
%IF{"{Plugins}{LdapNgPlugin}{AutoClear}" else="  clear=\"$mail,$jpegPhoto\"
"}%}%

%<nop>LDAPUSERS{limit="10"}%
</pre>

---++ Plugin Settings

<!-- provided for compatibility only
   * Set SHORTDESCRIPTION = Query and display data from an LDAP directory
-->
The %TOPIC% 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}= %BR%
     You may have only one LDAP server and there is no point in sepcifying a server in %<nop>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}= %BR%
     If you have thousands of users and uses LDAP, you need to disable %<nop>LDAPUSER{...} because it would yield a large amount of data otherwise.
   * =$TWiki::cfg{Plugins}{LdapNgPlugin}{Helper}= %BR%
     The class of helper functions. Please see #Helper_Class.
   * =$TWiki::cfg{Plugins}{LdapNgPlugin}{CacheBlob}= %BR%
     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}= %BR%
     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. %BR%
     Setting ={Plugins}{LdapNgPlugin}{AutoClear}= true makes the =clear= parameter unnecessary.
     However, this causes slight incompatibility in some cases.
     You may put =%<nop>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}= %BR%
     Enable the dynamic WikiNames feature, for a LDAP-generated summary when hovering over a WikiName
   * =$TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{RequireLoggedIn}= %BR%
     Require that the user is authenticated to use the dynamic WikiName feature
   * =$TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Filter}= %BR%
     What classifies a user? Give a LDAP filter here, like =objectClass=posixAccount=
   * =$TWiki::cfg{Plugins}{LdapNgPlugin}{DynamicWikiNames}{Format}= %BR%
     How should the dynamic WikiNames box be formatted? Example: =|Name|$givenName $sn|$n|Mail|$mail|=

See example on dynamic WikiNames further down.

---++ Helper Class

%<nop>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 %<nop>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. %<nop>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.
<verbatim>
$TWiki::cfg{Plugins}{LdapNgPlugin}{Helper} = 'TWiki::Contrib::MyLdapNgPluginHelper';
</verbatim>
A helper class would be defined as follows:
<verbatim>
package TWiki::Contrib::MyLdapNgPluginHelper;

sub lookupHelper {
    my ($class, $ldap, $filter, $params) = @_;
...
</verbatim>
Currently =lookupHelper= is the only function expected in a !LdapNgPlugin helper class.

---+++ Arguments of lookupHelper()

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

$filter gets the =filter= parameter of %<nop>LDAP{...}%.

$params is a hash reference having values of the following parameters of %<nop>LDAP{...}%.
| *Name* | *Type* | *Default* |
| =base= | string | following !LdapContrib configuration |
| =scope= | string | =sub= |
| =skip= | number | 0 |
| =limit= | number | 0 |
| =sort= | array reference | =[]= |
| =reverse= | boolean | false |

---+++ 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:
<verbatim>
...
objectClass=user
cn: jdoe
name: John Robert Doe
mail: john.doe@example.com
...
</verbatim>
   * You have entered the following setting in =/lib/LocalSite.cfg=:
<verbatim>
$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|';
</verbatim>

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

%ATTACHURL%/DynamicWikiNameExample.png

---++ Plugin Installation Instructions

   * Run configure for automated install, or do a manual install:
   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.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 ==%TOPIC%_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:
  <table border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">TWiki::Plugins</td><td align="left">&gt;=1.1</td><td align="left">TWiki Dakar release.</td></tr><tr><td align="left">TWiki::Contrib::LdapContrib</td><td align="left">&gt;=2.0</td><td align="left">Required</td></tr><tr><td align="left">Unicode::MapUTF8</td><td align="left">&gt;=1.11</td><td align="left">Required for Perl prior to 5.8. Download from CPAN:Unicode::MapUTF8 if needed</td></tr><tr><td align="left">TWiki::Plugins::JQueryPlugin</td><td align="left">&gt;=1.0</td><td align="left">Required for the dynamic WikiNames option</td></tr></table>

---++ Plugin Info

This work was partly funded by Spanlink Communications.

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.MichaelDaum |
|  Copyright: | &copy; 2006-2007 Michael Daum http://wikiring.de <br /> &copy; 2006-2016 TWiki:Main.TWikiContributors |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2016-05-28 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2016-05-28: | TWikibug:Item7743: LdapNgPlugin's lookupHelper() to get base parameter |
|  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 <nop>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 |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Perl Version: | 5.8 |
|  TWiki:Plugins/Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |

__Related Topics:__ %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins, LdapContrib
This topic: TWiki > LdapNgPlugin
Topic revision: r2 - 28 May 2016 - tanderse
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.LdapNgPlugin.