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.
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.
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.
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:
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
Shuts down the ldapauth module.
List the available commands using the format
+DATA information
+DATA information
+OK
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
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
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
Shutdown ldapauth module. Identical to exit 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.
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 | 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. | ||
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 |
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.
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.
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
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 |
---|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
|