LdapGuiPlugin

Requirements

Required

• 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

{ 
    '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

#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

LdapGuiGlue

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 )

  '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

• 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

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

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

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

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

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