LDAPweb is a web based tool that can be used to manage entries in an LDAP version 3 compliant directory. The view one sees as a User is highly dependant on how LDAPweb has been implemented. This guide will explain the features for an implementation of LDAPweb whereby all features have been enabled.

Directories such as Sun One, Apache DS, Active Directory and Openldap are typical LDAP compliant directories. There are many more than the handful named here and it is highly likely that any type of directory your Enterprise is running is going to be LDAP compliant.

Getting Started

As stated in the Introduction, what one sees is highly dependant on how LDAPweb has been implemented. All screen shots shown are based on a standard all features implementation. If LDAPweb has been setup to do only searching then it’s highly likely the implementer will hide things like “Server”, “Port”, “Session” and “Directory” and default the settings.

The LDAPweb home page optionally lets one define the host where the directory server is running, the TCP/IP port number that the LDAP service is running on (normally 389), the type of session (No encryption is initially recommended unless you know that one of the encryption methods has been setup and is working on the LDAP server), the directory type and the feature one wishes to execute.

LDAPweb start page

Server: An IP address or Hostname of where an LDAPv3 compliant Directory Service is running.
Port: TCP port number on which the Directory Service listens on
Session: One can encrypt all communications between the web server and the Directory Server if the Directory server has been setup for encrypted/secure communication
Directory: If you know what type of Directory Server is in the background then please select the correct value. This setting is basically only used for password changing as different Directory Servers have different methods of password changing.

Feature: What you want to do (e.g. “Search” Search for something within your Directory).

Clicking on the “Go” button always takes you to the starting point of a feature. There are plenty of features that have successive screens so please note that “Go” will not take you to the next screen but to the start of the chosen feature.

The Features

If you are just starting then it’s recommendable to start with either “GetRoot DSE” or “Get Naming Context”. These are 2 features that definitely don’t require a username/password combination and gives an immediate result.

GetRoot DSE

Provides you with information about your directory server.

Get Naming Context

This show you the DNs (Distinguished Names) at the top of your directory tree structure. The best feature to use to find out the Base DNs for your directory. You’ll most likely be requiring the Base DN for most of the LDAPweb features.

Naming Contexts

In this example there are 2 naming contexts. All the way through this guide I will often be using the naming context “dc=local, dc=net” as the Base DN. Any reference to “Base DN” actually means the start point for any action within you directory, for example searching for entries in your directory from the start point “dc=local, dc=net”.

Search

Many of the other feature will require you to search first so it’s important to understand searching. Following is a search screenshot with some complex search logic and the results from that screenshot.

Search

In the above example the start point of the search is “dc=local, dc=net” (BaseDN). With a lot of directories anonymous searching is fine but in this example authentication details have been provided (AdminDN/Password). The search criteria has been set to “Tree” meaning that the search will go to all lower levels of your directory to try and find a match, for example on this particular test directory it will perform a search under “dc=local, dc=net”. Under “dc=local, dc=net” there are entries “ou=other, dc=local, dc=net” and “ou=persons, dc=local, dc=net” and searches will also be made under this structure. If One-level were to have been selected then only entries under “dc=local, dc=net” will be searched. If Base were to have been selected one shouldn’t put any search values as with a value of Base one is basically wanting to look at the entry “dc=local, dc=net”.

So what the above example search is doing is searching through the directory starting at “dc=local, dc=net” for someone who has the Surname of “rigby” or someone who has a Christian name that is, or close to, a Christian name of “jorg” (The “approx” - approximate - feature is dependant on whether your particular Directory server supports approximation searches. Most directory servers support wildcard searches).

Click the “Next >>>” button to execute the search.

There are other features on the main search page not shown above and here is a brief explanation of what they are for.

Other Attribute: If an attribute you want to search on is not shown on the main search page you can type manually provide an attribute type and its value
Filter: If you know LDAP search functionality well you can ignore the attribute type fields (e.g Surname, Christian Name, Common Name, User ID etc.) and type in your own search filter.
SizeLimit: The maximum number of entries to return when making a search
TimeLinit: The maximum amount of time to wait for a reply from the Directory Server

Dereference Aliases: Alias to another DN

Server Controls: You should refer to your particular Directory Server documentation if you are going to use this feature.

Typical Search result screen

The DNs which gave a match with your search query are displayed. Now you can select the DN of the object you wish to view in full. In our example we are going to take a look at “Eleanor Rigby” by selecting the DN and clicking on one of the “Next>>>” buttons.

The “LDIF export” feature is explained later.

Details of selected object

Add an Entry

The first steps are the same as those described in the “Search” section. Adding an Entry is done by cloning an existing entry so first find an object that matches the object you want to use. In this example we’ll clone the user Eleanor Rigby, the user we used as an example when describing the “Search” function.

Typical Add an Entry

Typically one should now overwrite “Eleanor Rigby” with the name of your choice and also update the cn, sn and off-screenshot description values and click on one of the “Next>>>” buttons. The NOTE mentioned in the screenshot can be ignored - it is erroneous.

If you have done everything successfully you will get a confirmation screen, otherwise the LDAP error will be displayed explaining why your Directory Server rejected the addition attempt.

Delete an Entry

Read Search as the process is exactly the same except there is one extra step and that is to click “Next>>>” to delete.

Modify an Entry

Read Add an Entry as the process is the same. It is recommended to clear all fields that one is not modifying.

Reset a User Password

Read Search as the process is exactly the same except there are two extra steps. Once you have the object results click the “Next>>>” button to bring up a screen that asks you to enter a new password and then click “Next>>>” to make the password change.

Note that the “Directory” value is important when changing a password as different directory servers have different requirements for password changing.

Change my Password

This feature is available so that a User can change his/her password. The User would have to now their own DN for this feature to work. If necessary, a User can find their DN by first searching for themselves.

The following screen using the example User “Eleanor Rigby” should be self explanatory

Change my Password Screen

Add an Entry - Generic

If you know all the necessary attribute types and values you can go try adding an object. It’s probably only worth using this feature if you have a simple addition to make or if you do not have any other option. The following screenshot shows a relatively simple example, but also shows one how cumbersome this feature is.

“Add an Entry - Generic” screenshot

Delete an Entry - Generic

The “Delete an Entry” feature although requiring more steps is most probably preferable than this feature. There IS a second screen shown the details of the object you are about to delete meaning one can safely press the “Next>>>” button on the following screen.

Generic delete screenshot

Add a text Attribute

This feature is used to add a viewable attribute to an object. As with most other features you first have to search for the object where you want to add the attribute, so please read the Search section. Once you have found the object you can click on “Next>>>” and will be presented with a screen asking you to enter the attribute name and its value. In the following screenshot example we are giving our example User, Eleanor Rigby a mail address of eleanor@nowhere.net

Add a text Attribute screenshot

Clicking on “Next>>>” will give you the result of whether the addition was successful or not.

Add a binary Attribute

The process is exactly the same as for adding a text attribute except the attribute value will be uploaded from a file. You could even add readable (text) attributes using this method but the intention of this feature is to add attributes like “jpegphoto” where the value is not displayable as text.

Add a binary Attribute screenshot

Delete Attribute Values

This feature is used to delete attributes and their value from an object. As with most other features you first have to search for the object where you want to delete attributes and their values, so please read the Search section. Once you have found the object check the boxes of the attributes and the values you want to delete and then click on “Next>>>”.

Delete Attribute Values screenshot

Expand the Directory

This feature shows all the entries one level above your chosen BaseDN. You can repeatedly expand but it is most probably recommendable to put a limit on the number of entries returned by using the Size Limit field. The following screenshots show you how one can repeatedly expand.

Expand Directory start page

Expand Directory intial results page

Expanding further (all entries under ou=persons)

Modify or Move a DN

This feature would most probably be used when you want to change an organizational unit (ou). For example, maybe it is decided not to group your employees under “ou=persons”, but instead under “ou=employees”. Before you jump into making a change you should have a good idea where the “ou” lies within the Directory tree. In the example Directory it is under “dc=local, dc=net”, therefore it makes sense to either give the full DN “ou=persons, dc=local, dc=net” as BaseDN and select a Scope of Base search, or to select “dc=local, dc=net” as BaseDN and select a scope of one-level. The following example shows you how to look at all the DN’s under “dc=local, net” (note that scope is one-level), select “ou=persons” and the change the organizational unit to “ou=employees”.

Modify or Move a DN start page

Modify or Move a DN search result and ou=persons selected

Modify or Move a DN result after selection of ou=persons

Now simply change “New Relative Distinguished Name” from “ou=persons” to “ou=employees” and click on “Next>>>”. Assuming you directory server allows this functionality all entries that were under “ou=persons, dc=local, dc=net”, now appear under “ou=employees, dc=local, dc=net”.

The LDIF Tools

Provided with LDAPweb is an LDIF toolkit. The LDIF import and export features are designed to be RFC2849 compliant. The LDIF generate feature is a powerful feature that can be used to build LDIF formatted text documents and is extremely useful when making mass additions/updates/modifications/deletions. If you do not have an understanding of LDIF please read the appropriate RFC’s or a good book on this topic.

LDIF Import

Enter your administrative permission details, if required, enter the name of a text file containing LDIF commands, and if you want importing to continue on finding an error, check the ignore errors check-box. On submission a separate window will be opened displaying which entries were successfully or unsuccessfully imported.

What you need to be aware of:

Tags are ignored (e.g. sn;lang-ja:: 5bCP56yg5Y6f). Everything between the first “;” and the next “:” will be discarded before the line is evaluated.

Controls are currently not supported and are ignored.

File entries (e.g. jpegphoto :< file:///usr/local/photo.jpg) is not supported and is treated like a normal attribute/attribute value pair (e.g. attribute jpegphoto has the value file:///usr/local/photo.jpg).

The charset tag is ignored.

The version tag is ignored.

LDIF import example

LDIF Export

To perform an export, enter the starting point of the export (BaseDN), your administrative permission details, if required, and the scope of the export. If the scope is “base”, then just the entry specified in BaseDN will be exported. If the scope is “one-level” then all entries one-level lower than BaseDN will be exported, and if the scope is tree then all entries under BaseDN will be exported.

You can optionally control what is exported by creating a filter. An example of a simple filter could be “sn=se*” which would extract all entries within the scope which have an “sn” attribute value that starts with “se” (e.g. people with surnames like Sewell, Sedgeley, Segal etc. would be exported). You can define more complex filter like “(&(sn=gu*)(givenname=wurzel))” which would find all people whose first name is Wurzel and whose surname starts with “Gu”. If you want to know more about filters please read RFC2254.

Another option is to control what attributes are exported. Specifying no attributes will cause all attributes and their values to be exported, otherwise only the attributes and their values of those specified will be returned.

A small feature that is unique to LDAPweb is the feature of adding a changetype tag on export. The default is not to add one, but nevertheless you might find this feature useful, especially if you are using a different LDIF import tool, or exporting and importing between 2 different directories. Specifying a changetype will add a changetype line after the “dn” line (the first line) of every entry. For example, if “modify” is selected, a line “changetype: modify” will be added after the “dn” line.

Once you have specified your export requirements submit the form.

LDIF Export example

Clicking “Next>>>” will display the results of the export. To save the results you have to use the features of your browser. A method that should work for all browsers is to “Select All” and “Copy”, create a new Ascii text file and paste the copied contents into the text file.

A useful trick to delete a lot of entries is to select a “changetype” of “delete” and to enter a nonsense attribute like “zzzzz” to export.

LDIF Generate

This is a powerful feature although it has its restrictions. If you have a good knowledge of LDIF you will find this tool extremely useful for mass additions/deletions/modifications. LDIF generate is the only feature that does not require access to an LDAP server to function.

LDIF generate requires a comma-separate text file and an LDIF template file to be able to create an LDIF file for import. The best way to describe how LDIF generate works is to show a working example.

The results screen handling is exactly the same as described in the LDIF export section (e.g. use the features of your browser – “select all/copy” and then copy to a file. The file should be a typical Ascii file to).

The restrictions:

All entries in your comma-separate input file are treated as text string values. If your comma-separated file has a format to represent binary data (e.g. x’097518….’) it will not be decoded but treated as a text string as seen.

If your comma-separated file has multiple values for one field it will be treated as a single value.

How it works:

The first line of the comma-separate file is a list of strings that will be substituted in the LDIF template file. You are free to format this line however you like but it is probably a good idea to stick to the format shown in the examples. A comma-seperated first line should typically look something like this “##cn##,##sn##,##description##” (the scripts just pick up what is between the commas show one could even have a nonsense header). In this example all the values that occur under the ##cn##, ##sn## and ##description## columns in the comma-seperated file represent the values to be substitute where one sees a corresponding value in the LDIF template file. For every subsequent line in the comma-separated file an LDIF entry will be generated using the LDIF template.