User Guide

LDAP ADDRESS BOOK - USER GUIDE

Introduction

This program allows you to view and edit entries in a global address book which has been implemented as an LDAP directory. On its own this program cannot be used as an address book; it must be used in conjunction with an LDAP directory server (e.g. OpenLdap). Together these will enable you to maintain a single common address book for your organisation, which can which can be accessed by all members of your organisation. This address book could also be accessed by other LDAP compatible programs, including popular email clients such as Outlook and Thunderbird.

This User Guide describes everyday use of the program. It does not require any significant knowledge of LDAP. A separate Configuration Guide describes how to configure the program to work with particular directory setups; this is aimed at administrators with extensive knowledge of LDAP. The program is supplied with a default configuration designed to work with Thunderbird; the rest of this guide assumes that the program is used with this default configuration.

The program is distributed as an executable Java archive, which will run on any computer that has the Java Runtime installed. It has been tested with Java 6 Update 14, so it is recommended that this or a later version is used. The JAR file can be saved in any convenient directory, and a short cut can be set up (e.g. in the Windows Start menu) to invoke it.

The program is also available as a native Windows executable bundled with the Java runtime. This will run on any Windows computer even if Java is not installed.

Setting the Password

When the program is run for the first time it will prompt you to enter and confirm a password. This is NOT the password associated with your LDAP directory. It is a password that will be used to control access to the program and to encrypt this other password which it needs to store in a configuration file. If you leave the password field blank or click the Cancel button no password will be set. If a password is set then you will have to enter it each time you start the program.

If you choose not to set a password then a default password hard coded into the program is used to encrypt the other password. This is less secure because if someone was able to access the configuration file and reverse engineer the program to obtain the default password then they could potentially obtain the password for your LDAP directory. The configuration file (config.xml) is stored in a directory called .LdapAddressBook created in the user's 'home' directory (e.g. in Windows this is normally "C:\Documents and Settings\user\.LdapAddressBook"). Normally only the user and administrators should be able to access this directory.

Configuring the Directory

Before you can use the program to look up entries you must configure the details of your LDAP directory, by selecting "Directory" from the "Configure" menu. You should be able to obtain these from the administrator of the directory; if you already access the directory from an email client such as Outlook or Thunderbird then use the same details.

Host Name is the name of the server hosting the directory (e.g. ldap.myserver.com).

Port Number 389 is commonly used for unsecured connections, 636 for SSL connections. 10389 or 10636 are sometimes used.

Tick the Use SSL box if the directory requires a secure connection (note if the server uses a self signed SSL certificate then you will have to import the certificate into the Java keystore, see "Servers with self signed certificates" below.)

Select the type of Authentication used by the directory; normally this would be "simple" if a username and password have to be provided to log in, or "none" if the directory does not require logging in.

Bind DN is the "username" required to log in to the directory; it is normally in the form of a "distinguished name", e.g. uid=my-userid,ou=my-organisational-unit.

Password is the password required to log in to the directory.

Base DN is a distinguished name specifying where in the directory's structure to begin searching for 'phone numbers.

Query and Keep Alive Interval can be left at their default values; see the Configuration Guide for information about these parameters.

Once you have entered all the required details click OK. If all is well after a short delay the form will disappear and the message "connected to server-name" will appear at the bottom of the main window.

If there is a problem one of the following error messages may be displayed:

"The host server-name could not be found" - Check that you have entered the name of the server hosting the directory correctly.

"Unable to connect to host server-name" - Check you are connected to the Internet. The server may be temporarily unavailable.

"SSL certificate for LDAP server is not signed by trusted provider" - You need to create a local copy of the Java trust store containing the server's SSL certificate, see "Servers with self signed certificates" below.

"The username (bind name) and/or password are not valid" - Check you have entered the username and password correctly.

"The authentication method is not supported" - Check you are using correct authentication method for server.

Configuring for Dialling

This program can be set up to dial 'phone numbers if you use a compatible IP telephony service. This facility is known to work with Gradwell VoIP services and with AstLinux systems. It may work with other providers, if they provide an API that enables calls to be set up by a POST request.

First you need to configure the details of the service you wish to use by configuring a provider. The program is pre-configured with Gradwell & AstLinux providers. You will need to edit the AstLinux provider to enter the URL of your AstLinux server.

If you want to use a different provider then select "Providers" from the "Configuration" menu. This will display a list of currently configured providers (initially this will be Gradwell & AstLinux). Click on the "write" icon to edit an existing provider and click the "dustbin" icon to delete it. To create a new provider click the "Add" button.

Enter a name to identify the provider and the URL for the POST request. The "OK Response" field is a regular expression which the first line of the response from the server must match if the call has been set up successfully. The Gradwell server returns a line that starts "OK:", which is matched by the pattern "OK:.*"; AstLinux servers return the string "Success". You can leave this field blank, in which case no checking is performed on the response returned by the server.

You then need to enter the names of the 4 parameters to the POST request which specify the username, password, extension number from which the call is being made and the number which is being called. Note these are the "labels" that appear on the left hand sides of the = in the parameter string, not the actual values. The username and password parameter names can be left blank if they are not required in the POST request (as is the case with AstLinux).

You can also enter any additional parameters required as a parameter string of form "param=value". If more than one additional parameter is required separate them with &, but don't enter an initial &, e.g. "param1=value1&param2=value2".

You need to tick the "Sanitise" box if your provider requires the number being called to be supplied as just digits, with all punctuation and space characters stripped out (as is the case for Gradwell). If the box is not ticked the number is sent to the server exactly as stored in the directory (as required by AstLinux).

Click OK to save the provider definition.

You then need to configure one or more extensions from which you will be making calls. Select "Extensions" from the "Configuration" menu to display a list of currently configured extensions (initially empty). Click on the "write" icon to edit an existing extension and click the "dustbin" icon to delete it. To create a new extension click the "Add" button.

Enter a name to identify the extension and the extension number (normally a 7 digit SIP id, but for AstLinux it is an alpha id which the server translates into the actual extension number). Select the provider for the extension. Enter the username and password for the extension if required (not for AstLinux).

For Gradwell extensions you first need to configure a security token for the extension. Log in to your VoIP control panel and select "Call API" from the "System Integration" options. Scroll down to the table at the bottom of the page. Select the extension and tick the "create new" box. If you will always being using the program from a fixed IP for added security you can enter this as the "Allowed IP". Click "Save" to create the token which will then be displayed in the table. The token should then be entered as the password and the 7 digit extension number as the username.

Click OK to save the extension definition.

Searching for entries

Type the start of the name required in the "Name" box. A list of matching entries from the directory is displayed in the box underneath. The number of matches found is displayed at the bottom of the window. A maximum of 50 matches are displayed; if the ">50 matches" message is displayed you will need to refine your search by typing extra characters to be sure of finding the required entry.

Select the entry you require, and the details of that entry are displayed in the panel below the list, on a series of tabs. Click on the tab headings to display the different sections.

Updating Entries

Make the required changes to the entry. If you change the First Name or Last name fields the Display Name field will automatically change in step. However you can manually set the Display Name to any text you choose.

Image fields have 3 buttons to the right. Use the "Load" button to select an image to be displayed and then saved with the entry. Use the "Clear" button to remove the displayed image. Use the "Save" button to save a local copy of the displayed image. Note that the image will only be saved to or removed from the server when the entry is saved.

A warning message will be displayed if the text you type into a field is not the required format. Phone numbers must be either in international format (a + prefix followed by groups of digits separated by spaces, e.g. +44 1234 56789) or national format (groups of digits separated by spaces or hyphens with optional groups enclosed in parentheses, e.g. (0) 1234-56789). Email addresses must be in the 'normal' form: name@domain. Some fields cannot be left blank; a warning message will be displayed if you attempt to save an entry with a blank Last Name or Display Name.

Click the Save button to update the entry in the directory. If the save is successful a message will be displayed briefly at the bottom of the window.

Each entry in the directory must have a unique Display Name. If you attempt to create an new entry with the same Display Name as an existing entry then a warning message is displayed. You should then change the Display Name so it is distinguished from the other entry (e.g. Smith, John - Bristol).

Click the Undo button to reverse all changes made since the last successful save.

Creating New Entries

Click the New button to display a new blank entry. Enter all the details into the fields, and save the entry by clicking the Save button.

Click the Copy button to create a copy of an existing entry (e.g. for a person in the same family or organisation). The Display Name field will have "(Copy)" or "(Copy n)" appended; all other fields will be the same as in the original entry. This copy can now be edited and saved without affecting the original entry.

Deleting Entries

To delete the currently displayed entry from the directory click the Delete button. You will be prompted to confirm the deletion.

Dialling 'Phone Numbers

Dial buttons are displayed next to fields that contain 'phone numbers; they are only enabled if you have configured one or more extensions (see above). If you have configured multiple extensions use the extension selector to select the extension you wish to make the call from. Click the dial button and the selected extension will ring. When you answer the called number will start ringing, and the call will proceed as normal.

If something goes wrong during the call set up one of the following error messages may be displayed:

"The host server-name could not be found" - Check that you have entered the host name part of the POST URL correctly, and you are connected to the Internet.

"The URL url could not be found" - Check that you have entered the POST URL correctly.

"Unable to connect to host server-name" - Check you are connected to the Internet. The server may be temporarily unavailable.

"SSL certificate for host server-name is not signed by trusted provider" - You need to create a local copy of the Java trust store containing the host's SSL certificate, see "Servers with self signed certificates" below.

If the call is not connected and no error message is displayed then check the parameters have been defined correctly for the provider, and all the details are correct for the extension.

Troubleshooting

If an error occurs the log file may contain information which may help you, or the directory administrator, diagnose and fix the problem. The log files are in the same directory as the configuration file, and are called LdapAddressBookn.log, where n is 0 for the latest run, and progressively higher numbers for previous runs. As well as error information the log files contain a record of updates, additions and deletions made to the directory. The time, the number called and the extension the call was made from are also recorded for each call that the program attempts to set up. It does not record whether the call was successful or how long it lasted, and cannot be used as proof that a call was made.

Servers With Self Signed Certificates

If the server hosting your LDAP directory or IP 'phone service uses an SSL certificate that has been self signed, or the certificate has been signed by a Certification Authority that is not recognised as trusted by Java, then you will need to create a local copy of the Java trust store containing the certificate(s) for your server(s). The following instructions apply to Windows with Java 7 installed; the procedure for other platforms and versions is likely to be similar.

First you need to obtain a copy of the server certificate or the CA certificate used to sign the server certificate (e.g. from the server's administrator), or if you have access to the server's keystore you can export a copy using the Java keytool utility. Save the certificate in same directory as the configuration file ("C:\Documents and Settings\user\.LdapAddressBook").

Now open a Command Prompt window and set the default directory to this directory by typing the following command:

cd "C:\Documents and Settings\user\.LdapAddressBook"

Then copy the Java trust store (cacerts) file to this directory:

copy "C:\Program Files\Java\jre7\lib\security\cacerts" .

Finally use the keytool utility to import the certificate by typing the following command:

."C:\Program Files\Java\jre7\bin\keytool" -import -file myserver.cer -keystore cacerts -storepass changeit

Where myserver.cer is the name of the file containing the server's certificate. Note if you have changed the password for the keystore from the default then you should replace "changeit" with the new password you have set.

The details of the certificate will be displayed, and you should type Y to confirm the import of the certificate.

Unlike the global cacerts file, this local copy will not be replaced every time a Java update occurs.

Note if you create a local copy of the cacerts file it must contain the certificates for all your servers, even if some of them are also in the global cacerts file, which will not be accessed.

Upgrading from version 1.0

Simply replace the JAR file with the new version. Your existing configuration file is compatible with the new version. However if you wish to make use of the new functionality (multi-line fields, dialling) you will need to edit your configuration file. For example if you wish to display and edit the description attribute add the following immediately after the last <tab>...</tab> section:

  <tab title="Other">
    <field id="Description">
      <label>Description</label>
      <ldapattribute>description</ldapattribute>
      <numlines>16</numlines>
      <required>0</required>
    </field>
  </tab>

If you wish to display and select JPEG photos stored in the jpegPhoto attribute add the following immediately after the last <tab>...</tab> section:

  <tab title="Photo">
    <field id="Photo">
      <label>Photo</label>
      <ldapattribute>jpegPhoto</ldapattribute>
      <imagefield>1</imagefield>
      <imagewidth>256</imagewidth>
      <imageheight>256</imageheight>
      <required>0</required>
    </field>
  </tab>

If you wish to use dialling you need to add the following line to the definition of each field that holds a 'phone number:

<phonenumberfield>1</phonenumberfield>

Add the following to the configuration file to make the default providers available:

  <provider name="AstLinux">
    <okresponse>Success</okresponse>
    <postextensionnumberparameter>ext</postextensionnumberparameter>
    <postnumbertocallparameter>num</postnumbertocallparameter>
    <sanitise>0</sanitise>
  </provider>
  <provider name="Gradwell">
    <posturl>https://call-api.gradwell.com/0.9.3/call</posturl>
    <okresponse>OK:.*</okresponse>
    <postusernameparameter>extension</postusernameparameter>
    <postpasswordparameter>auth</postpasswordparameter>
    <postextensionnumberparameter>source</postextensionnumberparameter>
    <postnumbertocallparameter>destination</postnumbertocallparameter>
    <sanitise>1</sanitise>
  </provider>

Distribution and Use

This program may be freely distributed by any medium, provided:

• It is distributed in its original form as a Java archive;

• No attempt is made to charge for it or place any restrictions on its use;

• No attempt is made to pass it off as anyone else's work, or to claim ownership or any other rights.

I have developed this program to meet my own needs and and the needs of an organisation I am involved with. Other people are welcome to use this this program if they find it useful, but entirely at their own risk. I will accept no responsibility for any loss or injury caused by use of this program or the inability to use this program. While great care has been taken in writing this program I offer no guarantee that it will function as described.

Feedback and Support

I welcome feedback about this program, in particular any experiences of using it on platforms other than Windows. I will endeavour to correct any bugs that are reported, but I cannot guarantee to respond to individual requests for support etc. I can be contacted by email:

john@tvpctherapy.co.uk

Acknowledgements

This program incorporates JDOM V2.0.5 (jdom.org) and images from the Java Look and Feel Graphics Repository 1.0.

Launch4j by Grzegorz Kowal was used to produce the Windows native executable. Code incorporated in this version is covered by the MIT license.

Thanks to Alexander Stein, Michael Keuter & Lonnie Abelbeck for encouragement and ideas for new features.