LDAPAuth External Authentication Module

The LDAPAuth module is for use with Netwin's DMail and DNews products and an LDAP server. Several of Netwin's products allow the use of a separately compiled authentication module which obey a simple command protocol (see External Authentication). Netwin provides several such authentication modules and you can also build your own. LDAPAUTH is one of the modules Netwin provides and enables you to authenticate against an LDAP server rather than standard NT or Unix password files.

Contents:

  1. Download from Utils Download Page

  2. Use with DMail

  3. Use with DNews

  4. Ldapauth Command Set

  5. Ldapauth INI File settings

  6. Building for other platforms

  7. Downloading a recommended LDAP server

1. Use with DMail

Directory severs contain information about objects. One sort of object is a person and the various bits of information stored in the directory server about that object are called attributes.

The attributes stored will vary from one LDAP server to another. The key one for use with ldapauth is the 'mail' attribute which has the form 'user' or 'user@domain' this is what ldapauth refers to as the username (see the ldap_search_name below to change mail to another attribute). The distinguished name or dn is generally of no interest to ldapauth. The @domain part of the username is optional and will default to a setting in the ini file.

To make DMail use ldapauth you need to edit the dmail.conf configuration file, typically,
c:\winnt\system32\dmail.conf
or
/etc/dmail.conf
and edit the following to settings to read,
authent_method External
authent_process c:\dmail\ldapauth.exe
and then RESTART both DSMTP and DPOP.

More detail is given in,
Installation instructions for use with DMail on NT
Installation instructions for use with DMail on Unix

For more details on running an external authentication module like ldapauth see,
External Authentication.

2. Use with DNews

Same as with dmail, except that the entry in dnews.conf should be:
auth_spawn d:\dnews\ldapauth.exe
instead of the dmail settings
authent_method External
authent_process c:\dmail\ldapauth.exe

See http://netwinsite.com/dnews/access.htm#pass_ldap for the few dnews specific instructions but in general follow the dmail installation instructions.

3. LDAPAUTH Command Set:

The ldapauth  module receives commands on stdin and sends replies on stdout. The command set is given below:

NB: Ldapauth does not take any command line arguments.

NB: LDAPAuth's command set is defined by the Netwin External Authentication Proctocol.

Command Function
lookup username Retrieve drop file location and other information about an already authenticated user
check username password Check the a username and password against LDAP directory
search username Search for matching users
set username password option=" value" Create a new user entry in the LDAP directory
quit close down ldapauth
exit close down ldapauth
verbose Toggle verbose mode. Verbose mode is useful for testing when running ldapauth at the command prompt. It outputs additional information in response to each command
version Print the version number

Replies consist of:

+OK message

-ERR message

+DATA message

Details of the response and additional options within each command are given in the following sections:


3.1 Check Command

Check the a username and password against LDAP directory. The username may be either user@domain or just user. The LDAP directory will be searched for entries with the attribute mail = user@domain. If the supplied username has no @domain section then this will be taken from the ini file setting pop_domain. Once a matching entry is found then ldapauth will try and bind to that entry using the supplied password. The fromip parameter is currently ignored by this module, it is used in other modules to specify different virtual domains. If the bind operation is successful the +OK is returned if not -ERR is returned.

If the bind was successful then the LDAP entry is also checked for drop file, uid and forward attributes. If these are found then they are also returned. If no drop path attribute is found the word config is returned in its place. If no uid attribute is found 0 is returned. Forward addresses, if found, are returned at the end of the +OK line. The attributes to be used for drop_file, uid and forward are specified by the ini settings ldap_drop_file, ldap_mail_uid and ldap_dmail_forward. The default values for these are: drop_file, mail_uid and mailForwardingAddress.

Input:

check username@domain password fromip
check username password fromip

Returns:

+OK username path uid forward
-ERR reason



3.2 Exit Command

Shuts down the ldapauth module.


3.3 Help Command

List the available commands using the format
+DATA information
+DATA information
+OK


3.4 Lookup Command

Retrieves drop file location uid and forward information about an already authenticated user. The format etc. is similar to that used in the check command but no password is required. This is used for example by DPOP when it needs to check the location of a drop file without first authenticating a user.


Input:

lookup user@domain fromip
lookup user fromip

Returns:

+OK username path uid forward
-ERR reason


3.5 Search Command

Search for matching users. The supplied username may be of the form user@domain or just user. The LDAP directory will be searched for entries with the attribute mail matching user*@domain. If the supplied username has no @domain section then this will be taken from the ini file setting pop_domain. To check for users from any domain use: search user@* One line is returned for each matching entry with a +OK or -ERR line at the end.

Input:

search user
search r
search *smith
search Ralph@*

Returns:

+DATA dn=(cn=Test0, o=netwin), mail=test0@161.29.2.44
+DATA dn=(cn=Test1, o=netwin), mail=test1@161.29.2.44, path=/spool/mail
+OK Search Complete

-ERR No matching entries


3.6 Set Command

This command has several uses depending on the format used. It can:

set newuser password add a new user and password to the LDAP server
set olduser newpassword change the password of an existing user
set olduser (NULL) age="45" add new attributes for an existing user
set olduser (NULL) age="46" modify the values of attributes for an existing user

When it is adding a new user it will use the ini setting ldap_objectclass setting to specify what the object to be added is. The default is a person. They will have a dn: newuser as well as an attribute mail: newuser@domain where @domain was either part of the specified username or taken from the ini setting pop_domain.

When adding new attributes they are specified in the form name="value" the quotation characters are required and multiple attribute name="values" can be specified separated by spaces.

NB: You MUST ensure that any attributes that you supply to the set command exist in your objectclass, otherwise you will get an error like,
-ERR ld_set: Cant modify entry for cn=fred: Object class violation

If the password is not to be changed or rewritten to the LDAP directory then the password is specified as the string (NULL)

The modify attribute value has the same format as the add new attribute. Note that the new value replaces any existing values.

Input:

set username password|(NULL) [var="value" ...]
set user password
set user (null) age="45" sex="male"

Response:

+OK Database modified for user (mail=ralph@161.29.2.44)
-ERR ld_set: Cant modify entry for cn=Ralph, o=netwin: Protocol error


3.7 Quit Command


Shutdown ldapauth module. Identical to exit command.


3.8 Verbose Command


Toggles the verbose mode. In verbose mode it is assumed the module is being run at a command prompt and additional information can be printed. For example lookup and check will return the full information of all attributes for the selected entry.

 


4. Ini Settings for LDAPAUTH

Netwin supplies several external authentication modules:

These are all supplied with source so they can easily be tailored to your particular use. The LDAPAUTH module allows you to use an LDAP server to authenticate against in addition to storing such things as the location of the users drop file in the LDAP database. It makes use of an ini file which must be called ldapauth.ini an must be stored with the ldapauth executable. The settings which can be used within the ini file are given below:

Setting Example Default Required Function
ldap_port 3890 389   The TCPIP port to connect to the LDAP server on
log_path c:/logs the location of the ldapauth executable   The directory to store log files in
max_log_size 10000 100000   The size at which log files are rotated. Logs are numbered 1,2,3,4
log_level debug info   Controls the amount of information logged during use. One of error, info, debug
ldap_host whatsit.co.nz localhost required The IP name of the host to connect to
ldap_mail_uid dmail_uid mail_uid   The LDAP attribute which will be used to store the uid DMail should use for accessing the users drop file.
ldap_mgr_dn cn=DMAIL Manager cn=Directory Manager required The LDAP manager distinguished name to bind with.
ldap_mgr_pw secret blank required The password for the ldap_mgr_dn entry
ldap_search_base o=whatsitinc blank required The LDAP search base to use for all interactions with the LDAP server
ldap_search_name uid mail   IMPORTANT: Specifies the attribute used for identifying the user's entry in the database. e.g. when set to the default of mail, lookup bob, makes ldapauth lookup, mail=bob in database. (Prior to version 1.0k this was only used for lookups and not on the set command)
pop_domain whatsit.co.nz blank required The domain which will be appended to any usernames not containing @domain
ldap_drop_file dmail_drop_file drop_file   Name of LDAP attribute which will be used for storing the full name and path of the users drop file. Optional
ldap_objectclass android person   When adding new users with the set command the specified objectclass values will be added to the new entry, NB: you must enter something like,
set username pass a="x" b="y" c="z"
, where the fields a, b and c MUST be in the specified objectclass, otherwise you will get an objectclass violation error message.
ldap_dmail_forward dmail_forward mailForwardingAddress   Name of LDAP attribute which will be used to store DMail  forwarding addresses
log_name ldapauthlog ldapauth   Base of log file name. Note suffix n.log will be appended so default is ldapauth1.log

 


5. NT Installation with DMail:

You need to perform the following steps:


1. Download the distribution set
2. Unpack the distribution set
3. Copy ldapauth.exe and ldapauth.ini to a directory where DMail can use it.
4. Edit ldapauth.ini to meet your requirements.
5. Update dmail.conf to tell dmail to use ldapauth for authentication.
6. Restart DMail.
7. Test it.

These steps are described in detail below:

1.

NB Windows users: With versions 2.8h and above of DMail you will find the ldapauth files in your DMail distribution set (\dmtemp). They should have been copied into your DMail directory by the DMSetup utility, so you should check step 3 below and then jump to step 4.

Download the distribution set
For the latest versions see,
Utilities Download Page
General command line FTP instructions:
    ftp ftp.netwinsite.com
    (log in with username 'anonymous', use your email address as a password)
    cd pub/dmail
    hash
    binary
    get ldp10c.exe

2. Unpack the distribution set
    ldp10a

3. Copy files (ldapauth.exe etc.) in temporary unpack directory /ldtemp to a directory where DMail can use them.

NB: You MUST remember to copy the ldap dll

    cd \ldtemp
    copy * \dmail

You should find the following files,
    ldapauth (binary)
    nsldap32v11.dll (copy this to dmail directory or c:\winnt\system32\)
    ldapauth.ini (sample ini file for you to edit)
    ldap.htm (a copy of this page)
    authprot.htm (outlines our External Authentication Protocol)

4. Edit ldapauth.ini to meet your requirements.
    notepad \dmail\ldapauth.ini
    ! See other sections of this page for configuration information !
    Note ldapauth.ini will normally contain the manager password for your ldap server so it should be suitably protected but ldapauth must be able to read it. LDAPAuth is spawned by DPOP which is spawned by the DWatch service which is normally run as the 'system' account.

5. Update dmail.conf to tell dmail to use ldapauth for authentication.
    notepad \winnt\system32\dmail.conf
add/modify the following lines:
        authent_method External
        authent_process c:\dmail\ldapauth.exe

6. Restart DMail.
    Use dmadmin utility for this. Do a stop all and then a start all.
or see Restart information

7. Test it.
    Try a search or add user from dmadmin or just connecting from an email client with a username/password which exists on the ldap server. If these tests fail it may help to run the ldapauth.exe from the command line then use comands; help and verbose etc. to see what the problem is.


6. Unix Installation with DMail:

You need to perform the following steps

1. Download the distribution set
2. Unpack the distribution set
3. Copy ldapauth.exe and ldapauth.ini to a directory where DMail can use it.
4. Edit ldapauth.ini to meet your requirements.
5. Update dmail.conf to tell dmail to use ldapauth for authentication.
6. Restart DMail.
7. Test it.

These steps are described in detail below:

1.

NB Linux Libc6 users: With versions 2.8h and above of DMail you will find the ldapauth files in your DMail distribution set (/dmtemp). They should have been copied into your DMail directory by the DMSetup utility, so you should check step 3 below and then jump to step 4.

Download the distribution set
For the latest versions see,
Utilities Download Page
General command line FTP instructions:
    ftp ftp.netwinsite.com
    (log in with username 'anonymous', use your email address as a password)
    cd pub/dmail
    binary
    hash
    get ldp10c.exe

2. Unpack the distribution set by entering at the command prompt,
    ldp10c

3. Copy files in temporary unpack directory /ldtemp to a directory where DMail can use them, i.e. to the dsmtp_path.
    cd /ldtemp
    cp * /usr/local/dmail

You should find the following files,
    ldapauth (binary)
    ldapauth.ini (sample ini file for you to edit)
    ldap.htm (a copy of this page)
    authprot.htm (outlines our External Authentication Protocol)

4. Edit ldapauth.ini to meet your requirements.
    vi /usr/local/dmail/ldapauth.ini
   ! See other sections of this page for configuration information !
    Note ldapauth.ini will normally contain the manager password your ldap server so it should be suitably protected but ldapauth must be able to read it. NB: LDAPAuth will normally be able to read a protected file as it runs as root, when spawned by DPOP or DSMTP.


5. Update /etc/dmail.conf to tell dmail to use ldapauth for authentication.
    vi /etc/dmail.conf
add/modify the following lines:
        authent_method External
        authent_process /usr/local/dmail/ldapauth

6. Restart DMail.
    Use dmadmin utility for this or
    tellsmtp shutdown
    tellpop shutdown
    /usr/local/dmail/dm_start.sh
    /usr/local/dmail/dpop_start.sh

7. Test it.
    Try a search or add user from dmadmin or just connecting from an email client with a username/password which exists on the ldap server. If these tests fail it may help to run the ldapauth.exe from the command line then use comands; help and verbose etc. to see what the problem is.


7. Building for other platforms:

It is now our policy to provide a binary form of ldapauth for as many platforms as possible. (For linux and NT you will find ldapauth binaries in the DMail distribution set).So before building LDAPAuth for yourself, you should check that our utilities page does not have a precompiled executable for you. And if it doesn't you can of course email us and we will try to build it for you.

We will still provide the source, downloadable from our utilities page.

Below are instructions for compiling ldapauth yourself.

1. Download the ldapauth source from our utilities page,
http://www.netwinsite.com/dmail/utils.htm#ldapauth
,or directly from our ftp site, login as user 'anonymous',
ftp://ftp.netwinsite.com/pub/dmail/ldp10c_source.tar.Z
(or a similar file name)

2. After downloading the file you would do this:
    uncompress ldp10c_source.tar.Z
    tar -xvf lpd10c_source.tar
    cd buildxx (e.g. build28)
    cp config.PLATFORM config.i
(where PLATFORM is your platform, e.g. solaris)

3. If you don't have the sdk installed...

3.a) You can install the LDAP C libraries sdk from:
http://www.openldap.org/
or (Netscape) http://www.mozilla.org/directory/

and then edit the SPECLIBS line of config.i so that you include the correct libraries for the SDK that you installed, e.g. libldap and liblber, e.g.,
SPECLIBS = -I../ldap/include -L../ldap/libraries -lldap -llber

OR

3.b) Our ldapauth source contains the openldap sdk, so do the following in the buildxx directory,

*** you may need to edit config.i at this point and uncomment SPECLIBS line ***

   uncompress ldapopen-src.tar.Z
   tar -xvf ldapopen-src.tar
   cd ldap
   ./configure
   make depend
   make

(that should make the libraries, see INSTALL for OPENLDAP instructions on installing SDK)

   cd .. (back up to buildxx directory)

4. Now LDAPAuth should build correctly:
    cd dpop
    make ldapauth

If not check that you are including the SDK include directory and providing the location of the two SDK libraries, libldap and liblber, which should be on the SPECLIBS line in the config.i you are using, e.g. something like,
    SPECLIBS = -I../ldap/include - L../ldap/libraries -lldap -llber

(ensure that the line in your config.i is not commented out with a pound or hash, #, symbol).

5. Then use the resulting ldapauth binary with dmail or dnews.

For DMail,
copy ldapauth to your dmail directory,
    cp ldapauth /usr/local/dmail

copy other files to dmail directory,
    cp ../misc/ldap* /usr/local/dmail
    cd /usr/local/dmail

edit ldapauth.ini (see the config settings on this page for details)
    vi ldapauth.ini

6.Test ldapauth at the command line,
    ./ldapauth
    lookup username
    +ok username ...
    quit


8. Downloading a recommended LDAP server

We recommend the OpenLdap server available from,
http://www.openldap.org/

We also test LDAPAuth against Netscape's LDAP server (a number of the defaults relect this) and the University of Michigan server.

SDKs for LDAP are also available from,
http://www.openldap.org/
OR (Netscape) http://www.mozilla.org/directory/


Products Downloads Prices Support Company