LdapGuiPlugin

This plugin enables you to build a self defined LDAP GUI to ease administration by distributing certain tasks to your users over a web interface. At the moment the interface is implemented by REST handlers which can be called on submit to modify or add LDAP entries by a self designed graphical user interface (GUI) consisting of forms.

The problems intended to be solved by this plugin are recurring, easy modifications to LDAP data which could be done by users, because they have the knowledge about the data. An example is that someone wants to change his email adress or data changed because the user moved to another office. That often happens over intern solutions or over an administrator because you can not expect them to know what LDAP does. So this plugin tries to provide the tools to make such things invisible and put everything together into a web based GUI. And because it is a Foswiki plugin the GUI can be designed and described flexibly.

The following chapters will explain the specification you need to satisfy and give some examples to give you a feeling how to use it.

Requirements

This plugin is currently developed for Linux and OpenLDAP. Hopefully the interface will grow much more abstract to provide functionality on different platforms. The behavior on other systems is not tested yet.

Required

Perl modules you will need:

• CGI
• Crypt::PasswdMD5
• Digest::MD5
• Digest::SHA
• Encode
• Fcntl
• MIME::Base64
• Net::LDAP
• URI::Escape

Recommended Foswiki extentions

• FormPlugin: The FormPlugin enables you to build HTML forms with extra features and has a implementation of the foswiki REST interface. Read its description for more Information.
• LdapContrib: It allows you to populate your foswiki userbase and groups by data which stored in a LDAP server. Read its description for more information.

Configuration in configure

Overview

Before the detailed explanation, here is an overview of the configuration in configure.

{ 
    'people' => 'ou=people,dc=my,dc=domain,dc=com'
};

{ 
    '100' => 'cn=groupname,ou=group,dc=my,dc=domain,dc=com'
}

{
   'cn' => {
      'attributes' => [
          'LdapFirstName',
          'sn'
          ],
   'delimiter'  => ' '
      }
}

{ 
    'uidNumber' => { 
        min => 1000,
        max => 65535
       }
}

{
   'add' => {
      'loginName' => 'LdapLoginAttributeName',
      'loginPWD' => 'LdapLoginPasswordAttributeName'
      },
   'modify' => {
      'loginName' => 'uid',
      'loginPWD' => 'LdapLoginPasswordAttributeName'
      }
}

Connection settings

1. The servers hostname or IP adress. Defaults to 127.0.0.1 (localhost)
2. The port your server is listening to. Defaults to 389.
3. Should your server use SASL for authenticate connections? (strongly recommended)
4. Should your server use TLS for LDAPS?
5. Do you want to use proxy users? If you do not use it, the user of the formular must connect over an own LDAP login with his/her own credentials. Of course every user needs the correct access, because the LDAP ACL will decide who is able to write in the end. These options would allow to bypass the ACL configuration for the server at least for user proxies.
   
   • A proxy user which has access to the userbase and can modify or add entries. This will be the bind dn in place of the actual user to add or modify entries. (Don't use this - it was basically a debug feature to test functionality)
   • A proxy user which is able to modify groups. With this a user could add someone to a group without the need to grant him/her write access to group entries. This proxy user is slightly more safe because the interface only connects to him after an entry was successfully inserted. This means the user who added the entry to the database had the correct access rights and the entry can safely be added to a group. So because no one can bind to this user explicitly no one should be able to blindly add people to groups without permission. Also the bindn and password for this proxy is not published.

Example

(# charaters define commentary begin)

#LDAP
{Plugins}{LdapGuiPlugin}{LdapGuiServerHost} = 127.0.0.1
{Plugins}{LdapGuiPlugin}{LdapGuiPort} = 389
{Plugins}{LdapGuiPlugin}{LdapGuiServerVersion} = 3

#SASL
{Plugins}{LdapGuiPlugin}{LdapGuiUseSASL} = false
{Plugins}{LdapGuiPlugin}{LdapGuiSASLMechanism} = PLAIN CRAM-MD5 EXTERNAL ANONYMOUS
#TLS
{Plugins}{LdapGuiPlugin}{LdapGuiUseTLS} = false
{Plugins}{LdapGuiPlugin}{LdapGuiTLSSSLVersion} = tlsv1
{Plugins}{LdapGuiPlugin}{LdapGuiTLSVerify} = require
{Plugins}{LdapGuiPlugin}{LdapGuiTLSCAPath} = 
{Plugins}{LdapGuiPlugin}{LdapGuiTLSCAFile} =
{Plugins}{LdapGuiPlugin}{LdapGuiTLSClientCert} =
{Plugins}{LdapGuiPlugin}{LdapGuiTLSClientKey} =

# user proxy
{Plugins}{LdapGuiPlugin}{LdapGuiAllowProxyBind} = false
# group proxy 
{Plugins}{LdapGuiPlugin}{LdapGuiAllowProxyUser} = true
# group proxy dn
{Plugins}{LdapGuiPlugin}{LdapGuiBindDN} = cn=proxyuser,dc=my,dc=domain,dc=com
# group prody password
{Plugins}{LdapGuiPlugin}{LdapGuiBindPassword} = secret

GUI functionality

1. The base dn of your LDAP. Defaults to dc=your,dc=domain,dc=com which will most likely not work for you. This is the root of your DIT where the plugin should operate.
2. The user base/bases of your LDAP. This defaults to [ ou=people,dc=your,dc=domain,dc=com ] (This is a list!)
3. The group base/bases of your LDAP. This defaults to [ ou=group,dc=your,dc=domain,dc=com ] (This is a list!)
4. The login attribute of your LDAP. Defaults to uid.
5. The group attribute of your LDAP. Defaults to gidNumber.
6. The group member attribute of your LDAP. Defaults to memberUid.
7. How the login schema should be organized for add and modify data. This option is crucial to be able to connect to the LDAP because the plugin will search for these formfield names to get the credentials to bind to the server. (make sure to choose names which are not LDAP attributes! But you can use the loginattribute to associate a modify operation directly with the logged in user.) example:

    {
     'add' => {
                'loginName' => 'LdapLoginAttributeName',
                'loginPWD' => 'LdapLoginPasswordAttributeName'
              },
     'modify' => {
                   'loginName' => 'uid',
                   'loginPWD' => 'LdapLoginPasswordAttributeName'
                 }
   } 

   this means for the LdapGuiPlugin /addData handler, that the plugin searches for the fields LdapLoginAttributeName and LdapLoginPasswordAttributeName to bind against. For /modifyData it means, it is always searched for the uid and bind against that value.
8. You can set positive, numerical attributes automatically for new entries by a simple increment function. This can be used to autoset the uidNumber for a new user for example. This happens globally by an option in configure, so there is no option for a form to deactivate it.

Extended LDAP GUI functionality

These configurations are not necessary but can be useful to you. These settings have no effect until you actually use the corresponding option inside your forms, but they define what will be possible.

LdapGuiGlue

This is the configuration for the option called '!LdapGuiGlue'. You can use this option later to construct ('glue together') LDAP attributes out of form data, static strings and/or a format. (e.g.: cn = givenName + sn where givenName and sn are inside the form → cn will be "glued together" automatically) To do so you need to configure some rules how these attributes should be 'glued together'. Gluerules are specified to be a hash containing 2 - 4 parameter keys. Note that this specification will most likely change because it has great potential to be both: extended and simplified.

Necessary parameters

• delimiter

• attributes

Optional parameters

• asString

• formatfunctions

1. lowercase
2. uppercase

Example

• homeDirectory
  1. The first part of the result is a string "/home"
  2. The second part is the uid which gets constructed
  3. We want an empty delimiter.
  4. homeDirectory = '/home/' + + uid
• cn
  1. There have to be two fields named 'LdapFirstName' and 'sn' on the form.
  2. The delimiter should be a space
  3. cn = LdapFirstName + ' ' + sn
• uid
  1. There have to be a fiel named sn on the form.
  2. It should be lowercased
  3. uid = lowercase ( sn )

For this you need the following configuration for {Plugins}{LdapGuiPlugin}{LdapGuiGlue}:

  'homeDirectory' => {
                       'delimiter' => '',
                       'asString' => [
                                       1,
                                       0
                                     ],
                       'attributes' => [
                                         '/home/',
                                         'uid'
                                       ]
                     },
  'cn' => {
            'delimiter' => ' ',
            'attributes' => [
                              'LdapFirstName',
                              'sn'
                            ]
          },
  'uid' => {
             'formatFunctions' => [
                                    'lowercase'
                                  ],
             'delimiter' => '',
             'attributes' => [
                               'sn'
                             ]
           }

• the order in which you give the definition of the 'glue rules' for the LDAP attributes is not important.
• You should not construct cyclic rules (e.g.: A = B+C, B = A+C, C='oh oh' ).
• The attribute which gets constructed will get ignored even if you have a form field with the same name (e.g. there is no form field 'uid' needed and it would be ignored)
• 'asString' is a bitmask.
• The feature is not flexible enough to contruct multiple values for one attribute automatically.

• <input type="hidden" name="LdapGuiGlue" value="uid"/>

  for simple html or

• %FORMELEMENT{
     name="LdapGuiGlue"
     type="hidden"
     value="uid"
  }%

  for the FormPlugin

Usage / building a GUI

Form

The goal of the plugin is to perform LDAP actions preferably by a form submit. It is also possible to invoke an action by a request URL, but this approach may be too troublesome. Therefore you must know how the form should look like and what content it represents.

• Your form has a type which indicates the action the plugin will perform by the defined formdata(add, modify, …). This means the plugin needs to know some of the semantics of your form to process the data correctly. Therefore use what you need by calling one of the currently available REST handlers:
  • LdapGuiPlugin /addData when your form adds a new entry
  • LdapGuiPlugin /modifyData when your form modifies and existing entry
• The REST handler must be called on submit with the formfield data as parameters
• Use the POST method

Deleting entries is not yet implemented and may not be handled by the plugin in the first place.

Form fields

• A formfield which represents a LDAP attribute must have the same name as the LDAP attribute. (LDAP attribute: sn => form field name = sn) Otherwise the plugin will not recognize it.
• Also the attribute you wish to use needs to be defined by the LDAP schema.
• There are special GUI based options defined by the plugin. These are names which are known by the plugin to trigger functionality. (do not confuse with configure options)
• Any other attribute, which is not an option or not known by the LDAP schema, gets ignored.
• LDAP attribute names are case insensitive and so are form field names.
• There are no explicit checks if the attribute is able to have multiple values at the moment. If one does not pay attention to that fact the plugin may fails. For example if your form tries to submit multiple values for the attribute 'gidNumber' which is defined single valued.

<input name="sn" type="text" "">
<input name="HOmEdIReCtoRY" type="text" "">
<input name="givenName" type="text" "">

<input name="HASHME" type="hidden" value="userPassword=ssha">
<input name="ldapguiglue" type="hidden" "uid,cn">

Option fields

For all form types available

LdapGuiGlue

• <input type="hidden" name="LdapGuiGlue" value="uid"/>

  for simple html

• %FORMELEMENT{
     name="LdapGuiGlue"
     type="hidden"
     value="uid"
  }%

Hashme

• SHA
• SSHA
• Crypt
• MD5
• SMD5

%FORMELEMENT{
   name="HASHME"
   type="hidden"
   value="userPassword=sha,ssha,smd5,md5,crypt"
}%

If for example a user of your form types in the value 'abcd12AB' as a password the stored values could be:

userPassword: {SHA}2Ky05bDZLtah6bEXwMtPd1ZeUD0=
userPassword: {SSHA}UJvDy13UQpqPedUIXdPP8whJF8vFbTa6
userPassword: {SMD5}S5Ze1/Ort25FiqSGyBaUemFiY2Q=
userPassword: {MD5}+fcj3ntVthYOpNtHyyu8IQ==
userPassword: {CRYPT}nw37xSELAvmTI

If you want to store hashed values with forms other than that, you need some perl knowledge. The supported methods for hashing are implemented inside the Hash.pm. Feel free to improve this class or contribute new hash methods to it.

Examples

Example of an add form using FormPlugin

---+ New user

---++ Name

%STARTFORM{
   name="AddFormTest"
   action="rest"
   method="post"
   validate="on"
   strictverification="off"
   restaction="LdapGuiPlugin/addData"
  }%
%FORMELEMENT{
   name="LdapFirstName"
   title="the users first name"
   hint="<br/>Example: John"
   type="text"
   value=""
   mandatory="on"
   validate="required"
}%
%FORMELEMENT{
   name="sn"
   title="the users last name"
   hint="</br>Example: Doe"
   type="text"
   value=""
   mandatory="on"
   validate="required"
}%

---++ Location

%FORMELEMENT{
   name="roomNr"
   title="room number"
   hint="<br/>Please set the room number for the new user."
   type="text"
   value=""
   validate="required" 
}%

---+++ User password

%FORMELEMENT{
   name="userPassword"
   title="The userpassword"
   type="password"
   value=""
   mandatory="on"
   hint="<br/>The new users password"
   validate="required" 
}%

---+++ LDAP Login

Please use your LDAP data to verify your identity to submit your entered data.
----

%FORMELEMENT{
   name="LdapLoginAttributeName"
   title="Your Login Name"
   type="text"
   value=""
   mandatory="on"
   validate="required"
}%
%FORMELEMENT{
   name="LdapLoginPasswordAttributeName"
   title="Your Password"
   type="password"
   mandatory="on"
   validate="required"
   value=""
}%

%FORMELEMENT{
   name="Submit"
   type="submit"
}%
<!--
We set objectClasses invisible
-->
%FORMELEMENT{
   name="objectClasses"
   type="hidden"
   value="posixAccount, inetOrgPerson, person"
}%
<!--
Also the standard group (100 is an alias for gidNumber defined in {LdapGuiPlugin}{LdapGuiGroupIdentifier})
-->
%FORMELEMENT{
   name="gidNumber"
   type="hidden"
   value="100"
}%
<!--
We define the new user gets inserted in 'ou=people,dc=my,dc=domain,dc=com'
The alias 'people' is defined in {LdapGuiPlugin}{LdapGuiUserBaseAliases}
-->
%FORMELEMENT{
   name="ldapguiaddtouserbase"
   type="hidden"
   value="people"
}%
<!--
The attributes cn, mail, homedirectory and uid get constructed by the rules defined in {LdapGuiPlugin}{LdapGuiGlue} for the new user.
-->
%FORMELEMENT{
   name="ldapguiglue"
   type="hidden"
   value="cn,mail, homedirectory, uid"
}%
<!--
The values for the userPassword attribute should get saved as hashes. (SHA, SSHA, SMD5, MD5)
-->
%FORMELEMENT{
   name="ldapguitohash"
   type="hidden"
   value="userPassword = sha, ssha, smd5, md5"
}%

%ENDFORM%

Example of an modify form using FormPlugin

---+ I moved to another office/building
%STARTFORM{
   name="Employeeform"
   action="rest"
   method="post"
   validate="on"
   restaction="LdapGuiPlugin/modifyData"
   strictverification="off"
}%
<!--
Note: myPrinter is not a standard LDAP attribute
if it is defined by the LDAP schema, the plugin will modify it.
-->
%FORMELEMENT{
   name="myPrinter"
   title="your preferred printer:"
   type="select"
   value="%LDAPGETATTRIBUTE{attribute="myPrinter"}%"
   size="5"
   mandatory="off"
   options=",printera2 , printerb2, printerc2"
   labels="No Change, Printer 2nd floor building A, Printer 2nd floor building B, Printer 2nd floor building C"
   hint="<br/>Here you can change your preferred printer. If you moved to another building for example you surely want to print your stuff there."
}%
%FORMELEMENT{
   name="roomNr"
   title="room number:"
   type="text"
   value="%LDAPGETATTRIBUTE{attribute="raum"}%"
   validate="required"
   hint="<br/>You moved from one room to another? Please change the room number to your current one."
}%
%FORMELEMENT{
   name="telephone"
   title="telephone:"
   type="text"
   value="%LDAPGETATTRIBUTE{attribute="telephone"}%"
   mandatory="off"
   validate="required"
   hint="</br>Change your internal telephone number here."
}%
----
---+++ Ldap Login

Please use your LDAP login name and password to verify your identity. Verify your changes by clicking submit.<br />
<!--
value="%LDAPGETATTRIBUTE{attribute="uid"}%" refers to the default value of {LdapGuiPlugin}{LdapGuiLoginSchema}.
That way a modification is bound to the currently logged in user. (if uid is your login attribute)

This can be changed but if uid is your login attribut the plugin will deny it to be modified.
If you want to change a foreign entry, you need to provide a full dn to that entry like that:
      %FORMELEMENT{
         name="dn"
         type="text"
         value="uid=otherGuy;dc=my;dc=domain;dc=com"
      }%
-->
%FORMELEMENT{
   name="uid"
   title="Your ldap login name"
   type="text"
   value="%LDAPGETATTRIBUTE{attribute="uid"}%"
   validate="required"
}%

%FORMELEMENT{
   name="LdapLoginPasswordAttributeName"
   title="Your ldap password"
   type="password"
   validate="required"
   value=""
}%
%FORMELEMENT{
   name="action"
   type="submit"
   buttonlabel="Submit"
}%
%ENDFORM%

...
%FORMELEMENT{
   name="mail"
   title="mail:"
   type="text"
   value=""
   validate="email"
   hint="<br/>Your mail."
}%
<input name="ldapguimodifyadd" type="hidden" value="email">
...

If no value is provided in mail it will add nothing and leave the mail attribute for this entry untouched.

...
%FORMELEMENT{
   name="mail"
   title="mail:"
   type="text"
   value="example@domain.com"
   validate="email"
   hint="<br/>Your mail."
}%
<input name="ldapguimodifydel" type="hidden" value="email">
...

If the plugin finds a value 'example@domain.com' for the current mail attribute, it will delete it. Without a value, the attribute mail would be deleted.

Trigger API

• Use a suitable LDAP backend. For slapd there are backends like slapd-sock, slapd-perl or slapd-shell which can be used.
• If you do not need an instant trigger you could use a cron-job solution with searches.
• Insert flags into the DIT which indicate that a script needs to get started. Another program (cronjob or something else) could consume the information and trigger events.
• You use a daemon which communicates directly with LdapGuiPlugin.

LdapGuiPlugin defined Macros

LdapGetAttribute

%LDAPGETATTRIBUTE{attribute="cn"}%

%LDAPGETATTRIBUTE{attribute="email" max="5"}%

email1@domain.com,email2@domain.com,email3@domain.com,email4@domain.com,email5@domain.com

• Set SHORTDESCRIPTION = Interface for building a form based LDAP GUI over Foswiki

Recommendations

• Organize your GUI in a own web. This way you can protect them by the configure option "trusted webs", so that requests from other webs won't work. After all it is a plugin, and anyone could use the handlers.
• Use the access controls of Foswiki to map to your LDAP ACLs.
• Play around in the Testmode until everything looks fine.
• Report bugs
• Propose new/missing features

Plugin Info