README: myldapklient - an LDAP klient for KDE3.

Although this is beta software, it has been in use by several(>300) people
around the Internet for about a year without any problems reported back to me.
You do need to know some things about LDAP to build your own schemes. However,
you should be able to get started fairly easy. See the section
Quickstartguide below.

Contents
--------

Intro
Requirements
Install
Quickstartguide
General filters and LDAP versioning
Mailer configuration
Authenticated LDAP access
LDAP schemes
Searching
Limitations
The configuration file
  The short story
  The long story
Current KABkey tags
References
Contact
Acknowledgement
Closing words, Armageddon


Intro
-----

This is a simple LDAP klient. It attempts to be a bridge between an LDAP server
(more specifically the Exchangeserver where I work(rather, worked)) and KAB. 
Also, it's an I'm-learning-c++-project, which means that you can scare small 
children with the code.

It is not a plugin to kmail. I wish it were, but that's another project. See
Closing words, Armageddon at the end of this document.

I removed the warning about losing your addressbook. It hasn't happend to me, 
so I don't see why it should to you. But tell me if you have any problem.

In fact, feel free to contact me on sorn73 at yahoo.com with all and any
questions or ideas regarding myldapklient (or any other issue, like offering
me a job...).

Requirements
------------

You need:

+ fairly recent KDE installation. From v0.5.9 KDE3 is required.
+ OpenLDAP 2.0.x. Tested with 2.0.11. If someone can send me a patch to the 
  configurescripts to detect OpenLDAP, I'd appreciate it.

Install
-------

Same old, same old. "./configure ; make; make install" works and 
installs in the standard KDE place, wherever that is (distribution dependant). 
Otherwise, copy the binary to somewhere nice, like /usr/bin or /opt/kde2/bin 
or ~/bin . Note! There have been a report that it won't build with a parallell
build on an SMP machine. This has to do with the things that the project 
templates included in Kdevelop, and I have no clue what to do. I guess one 
should bugreport this to the KDevelop project. For now, don't do a parallell 
build.

Quickstartguide
---------------

So now you compiled and installed this, where do we go from here? To get
started, follow these simple steps:

1. Start myldapklient. If you have never started myldapklient before, it will
   show some messageboxes with useful information.
2. Click on configure in the lower left corner of the main dialog.
3. In the upper right corner there is a textstring with the label "New LDAP 
   server". Write a nice name here. It must not be the actual hostname, 
   it's more of a nice server identifier.
4. Make sure the checkbox "Create with default scheme" is checked and click on
   Add to the left of the previous textstring.
5. In the "LDAP server name/address" field, write the name or IPaddress of 
   the actual LDAP server.
6. Write your LDAP base in the "LDAP base" field. It should look something like
   "o=Sweden" or "o=myCompany,ou=engineering".
7. Click Ok in the lower right corner.

You are now finished with adding an LDAP server. Repeat step 1 through 7 for
all the servers you need.

1. In the main dialog, select a server from the "LDAP Server" selection box.
2. In at least one of the searchfields, select an attribute to search for and
   write a search argument.
3. Click on search, or press enter with the cursor in one of the search fields.
4. When the search is finished, select an entry from the list and click on i
   "Add to KAB" in the lower right corner of the dialog, to import that line
   into the KDE Addressbook.
5. If there are more than one interesting entry in the list, repeat step 4. If
   you want to search for something new in the same server, go back to step 2.
   If you want to search for something in another server, go back to step 1.

General filters and LDAP versioning
-----------------------------------

I got a patch from Mario Strasser which adds two new per-server options,
ldapversion= and ldapfilter= . I'll let Mario explain in his own words:

"Today I had a glance at your KDE myldapklient and
tried to use it in the university LAN. Because our
LDAP server is a Win2k AD server I had to make
some minor modifications which you may be
interested in.
I think they might be useful in other environments, too.

1. Win2k needs LDAP v3 thus I added a new configuration entry
   'version' which can be used to set the protocol version.

2. Due to the size of some LDAP directories it is useful to add
  some general filterrule to all queries. Therefore, I defined the
  configuration entry 'filter' which is added to all queries.
  For example one can set it to
  (&(objectclass=user)(objectCategory=person))
  to only get back user entries from the Win2k server.

Regards,
Mario"

I renamed the options as above when I included the patched, but you get the idea.

Mailer configuration
--------------------

You can now configure which mailer to use when you click on "MailTo...", just
set the "mailer=" key in the Global section in the config-file to the command
you want to start.

Authenticated LDAP access
-------------------------

Myldapklient now has support for authenticated LDAP access, with different
DN/passwords for each server. Add

  dn=<your distinguished name>
  password=<your password for the LDAP server>

keys under each server section in the myldapklientrc file, located in
~/.kde/share/config .

If your distinguished name is

  o=myCompany,ou=engineering,ou=gurus,cn=Joe Guru

the dn-key should be

  dn=o=myCompany,ou=engineering,ou=gurus,cn=Joe Guru

Yes, passwords are in cleartext, as you must send them to the LDAP server
in clear. No, there is no safe way of storing passwords on disk and being able to
retrieve them without user interaction (ie. entering a password-for-the-password).

I have now implemented a slightly better password handling. If you enter a LDAP DN
but leave the LDAP Password field empty for a server, myldapklient will no wask for
a password. It will remember the password until you select another server OR you exit
myldapklient OR an LDAP error occurs while connecting to the server (ie. a "Wrong
Password" error, but also a "Connection timed out" error. If you get the "LDAP
connection failed" message box, it will ask you for your password at next search).
Myldapklient is, however, vulnurable to the "analyze the corefile"-attack.

LDAP schemes
------------

LDAP schemes are not 100% standardized. There is X500 and rfc2256, but they
lack attributes for f.ex. Cellphones (but they do have attributes for Telex),
and doesn't distinguish between workphone and homephone.

By default, when adding an LDAP server, a default scheme is now created, 
with attribute mappings from rfc2256. Uncheck "Create with default scheme"
when adding an LDAP server, if you want to build your own LDAP scheme. This
default scheme currently looks like this:

LDAP attribute            KABtag         Heading
---------------------------------------------------
mail                      emails         Email
cn                        fn             Full Name
sn                        lastname       Last Name
givenName                 firstname      First Name
title                     title          Title
l                         Work/town      Town
st                        Work/state     State
street                    Work/address   Address
telephoneNumber           phone/Fixed    Telephone
facsimileTelephoneNumber  phone/Fax      Fax


Searching
---------

The LDAP filter strings conforms to rfc 2254 (of course, else it wouldn't 
work, but I love to namedrop, or should I say rfcdrop). You can specify three
different search arguments.

Limitations
-----------

LDAP directories can be built like trees. This client doesn't handle that.
Just nice, flat LDAP databases, where it can do simple searches.

LDAP servers can, and will, return multiple data for some attributes. This
client doesn't handle that. It will only present the last recieved data for
that attribute.

I know, I know, the GUI earns a place in Interface hall of shame, please feel
free to help me design a better one. Specifically, it bugs me that I can't get
resizing to work. But the overall widget placement has some problems...

The configuration file
----------------------

The short story
---------------

The following scheme will, hopefully, give you the email address and the full
name of the searchresults. Go ahead, try it. Don't forget to set an LDAP base,
like o=sweden or something. As long as the LDAP base conforms to rfc's, you 
should be able to use any LDAP base.

  LDAPattr  KAB tag  Header
  ---------------------------------------
  mail      emails   Email
  cn        fn       Full name		

The long story
--------------

This is the layout of the configuration file, if you wish to write one from
scratch yourself.

The configuration file is named ~/.kde/share/config/myldapklientrc . Create
it, and make a [Global] group. Make a group [Servers] and then make a key
server0=<server> in that group, where <server> is a fancy name that you
select, it will show up in the combobox. Now make a group [Server<server>]
where <server> is the same as the value on the server0 key. In this, the
Server-group, create a key ldapbase=<your_ldap_base>, where <your_ldap_base>
is something like o=world, depending on your LDAP server. Create a key
ldaphost=<ldap_server_or_ip>, where <ldap_server_or_ip> is the name or
IPaddress of this LDAP server. Go back to the [Global] group and create a
key lastserver=<server>.

Now your myldapklientrc file should look something like this (this is an
example):

[Global]

[Servers]
server0=MyLDAP

[ServerMyLDAP]
ldapbase=o=world
ldaphost=127.0.0.1

Ok, that was easy. Now we're going to create an LDAP-KAB scheme. The scheme
maps LDAP attributes to KAB entry-keys. In the [Server<server>] group we are
now going to create three keys for each LDAP attribute: the LDAP attributename
we want to match, the KAB key tag and a fancy listview header. The keys are
called ldapattrN, kabtagN and headN. N starts at 0 and rises (to max 20). You
must know what LDAP attributes your LDAP server sends you, and you must know
what KAB key you want to map it to, and also what I have named each KAB key.
The KAB key tagnames are later in this file.

Let's review the updated example file:

[Global]

[Servers]
server0=MyLDAP

[ServerMyLDAP]
ldapbase=o=world
ldaphost=127.0.0.1
ldapattr0=mail
ldapattr1=cn
kabtag0=emails
kabtag1=fn
head0=Email address
head1=Full name

(The Kconfig API will sort each group alphabetically.)

There. Now we have a simple, but complete, myldapklientrc. This one will
probably give you an email address from any LDAP server, including MSExchange
ones (at least my did). Just change the ldaphost key and you should be able
to fetch data and import into kab. A list over KABkey tags is below.

You can add more servers by adding another serverN= key (naming it server1,
server2 and so on) in the [Servers] group, and then a new [Server<server>]
group.

The LDAP attribute names are not the same from LDAP server to LDAP server.
Therefore one cannot say what LDAP attributes you can use. Here are some
attributes that my LDAP server send to me, they may or may not work for you:

Attribute name      What is it
==============      ==========
mail                Email address          	
cn                  Full name
Company             Company name (not standard X500/rfc2256)
department          Department (not standard X500/rfc2256)
telephoneNumber     Phone number
co                  Country
l                   City
givenName           First name
sn                  Last name

Fire up some generic LDAP klient and see what attributes your LDAP server sends
you. gq is a nice generic LDAP client.

Current KABkey tags
-------------------

The tag names correspond to keys in an AddressBook::Entry entry. The work and
home prefixed tags provides a way of adding values to an
AddressBook::Entry::Address entry for either a home or work address (or both
if you have the LDAP attributes.). Less than optimal, but it works for me
for now.

Also note, starting with v0.5.9 myldapklient doesn't longer user kab but kabc.
The kabc works a little bit different and doesn't have all the attributes that
the kab had (like "rank" and "delivery label"). I'm emulating the kab by using
the new eminent insertCustom function in kabc. Anyway, this should only affect
very few people, if any.

Tag										
===										

emails
fn
user1
user2
user3
user4
firstname
middlename
lastname
comment
title
rank

phone/Fixed
phone/Mobile
phone/Fax
phone/Modem

Work/org
Home/org
Work/orgUnit
Home/orgUnit
Work/orgSubUnit
Home/orgSubUnit
Work/country
Home/country
Work/town
Home/town
Work/state
Home/state
Work/zip
Home/zip
Work/address
Home/address
Work/position
Home/position
Work/deliveryLabel
Home/deliveryLabel

References
----------

rfc2254 - The String Representation of LDAP Search Filters 
rfc2256 - A Summary of the X.500(96) User Schema for use with LDAPv3

Contact
-------

Hey, I know you are out there, I've seen the counters on apps.kde.com and
sourceforge.net. 8-) Send me an email and tell me what you think about it.
sorn73 at yahoo.com.

Acknowledgement
---------------

This was made with KDevelop v2.0 under KDE 2.2. The integrated QT documentation
was very nice.
The gq LDAP klient (nice gtk LDAP klient) was very nice to learn from, and I
even copied a block or two of it's LDAP handling. Hope that's ok.

I'm using OpenLDAP 2.0.11(or similiar) directly, instead of LDAP_KIO. I get
bad data when using LDAP_KIO in konqueror, and therefore decided to use 
OpenLDAP directly.

As of myldapklient 0.5.9 this project is now ported to KDE 3.0.x.

Icon was drawn by Thomas Hudson, thankyou!
Patch for LDAP version 3 support and extra filters by MArio Strasser, thankyou!

Closing words, Armageddon
-------------------------

Friends, Armageddon is upon us. In the version of mail included in KDE 3.1 (or 3.2)
"they" promise to integrate LDAP access in the KAddressBook, which kind of makes
myldapklient redundant. If you wish to see further development of myldapklient,
voice your opinion. Send me an email, make some nice extension and send me a patch.

/Fredrik
