Authent Module Ldapauth

  1. Home
  2. Knowledge Base
  3. Accounts
  4. Authent Module Ldapauth

Installing and Setup

Some applications already come with this verison already built. If you have not got a build and/or require the lastest code it can be downloaded from the one of the links below:

Source:auth_src_2.4c.zip
Windowsldapauth_25j.zip
Linux 32bitldapauth_25j_linux.tar.gz
Linux 64bitldapauth_25j_linux64.tar.gz
Old Versions:
Windowsldapauth_2.5a_windows.zip
Linux (Libc6)ldapauth_2.5b_linux.tar.gz

Building From Source:

If you are building LDAPAuth from the source you will need to have a C compiler either cc or
gcc and make. To build the command line prompt would be:

make -f Makefile.ldap

Setting up with OpenLDAP:

If your ldap server is OpenLDAP you will need to enable ‘bind_v2’ so that LDAPAuth will correctly bind to OpenLDAP. LDAPAuth currently only supports simple binding. You need to add the following line to openldap file ‘slapd.conf’:

allow bind_v2

The default schema ‘person’ should be used. This schema does not support the most of the surgemail default fields, and you will need to update the schema to include the fields that you wish to store.

Setting up with SurgeLDAP:

SurgeLDAP has been setup to use the ‘netwinperson’ schema instead of the deafult ‘person’ schema. In your ldapauth.ini file you should add the setting:

ldap_objectclass netwinperson

This schema has already been setup to support all the surgemail and surgeftp fields to make it easy to just include the fields that you wish to support.

Configuration Options:

LDAPAuth comes requires an ldapauth.ini to configurate it’s options. This file is located in the same directory as the LDAPAuth binary OR in a directory specified by the -path command line option.

You should consult the ldapauth.ini that comes with the LDAPAuth download this will display all the default and common settings that you will need. Here is an example of what this file should look like:

# Welcome to Auth ini File.
# Leading # makes line a comment
# Main LDAP connection Information
ldap_host ldap.host
ldap_port 389ldap_mgr_dn cn=manager,dc=example,dc=com
ldap_mgr_pw mpass
# pop_domain host.com# LDAP Main Fields
ldap_search_base dc=example,dc=com
ldap_scope LDAP_SCOPE_ONELEVEL
# ldap_scope LDAP_SCOPE_SUBTREE# ****** SurgeLDAP v1.0j+ use ‘netwinperson’ ****
# ldap_objectclass person
# ldap_objectclass netwinperson
# ldap_search_name mail
# ldap_extend_search (AnyAttribute==AnyValue)
# ldap_extend_lookup (AnyAttribute==AnyValue)
# field_password UserPassword# LDAP Optional Fields
# ——————–
# ldap_extend_search (usertype=student)# SurgeMail/DMail and NetAuth Settings
# ————————————
# layout: info_fields surgemail_field ldap_field
# info_fields created created
info_fields fwd fwd
info_fields quota quota
# SurgeMail Only Settings
# ————————————
# If surgemail is setup as a proxy you need this setting
# info_fields tohost tohost
# info_fields allow allow# info_fields mailaccess mailaccess
# info_fields mailstatus mailstatus
# info_fields full_name givenName
# info_fields phone homePhone
# info_fields smsto smsto
# info_fields user_access user_access# info_fields alias_quota alias_quota
# info_fields list_quota list_quota
# info_fields user_access user_access
# info_fields send_limit send_limit# info_fields spf_block spf_block
# info_fields disabled disabled# info_fields realuser realuser
# info_fields friends friends
# info_fields enotify enotify
# info_fields ddpriv ddpriv
# info_fields ddfrom ddfrom

# SurgeMail and NetAuth Settings
# ——————————
# info_fields pass_question pass_question
# info_fields pass_answer pass_answer# SurgeMail/DMail and DNews Settings
# ———————————-
# info_fields groups groups# SurgeFTP Settings
# —————–
# info_fields ftphome ftphome
# info_fields ftpquota ftpquota
# info_fields ftpfromip ftpfromip
# info_fields ftpgid ftpgid
# info_fields ftpuid ftpuid
# info_fields accountstatus accountstatus# LDAP MUST HAVE fields
must_set_fields sn name
must_set_fields cn name# NWAuth Password Method (defaults to plain text)
# unix_password true
# use_crypt_on_set true
# plain_password true
# sha_hash true
# ssha_hash true

Config settings

info_fields

Use setting to inform LDAPAuth of pairs of database field names. It takes a list of up to 20 comma separated pairs of field names, where each pair is two words separated by a space. In each pair the first name is the name that LDAPAuth should lookup in your LDAP database and the second is the name it should display in the output.

Syntax: info_fields db_name1 field_name1,[…]
Example: info_fields groups usergroups,diskquota ftpquota
Default: none
Required Setting: no

ldap_group_base

(Version 1.1a, DMail 3.0) These four settings are used to pass the group membership through to DNews for access control. It is much better to use the info_fields when possible (it is much more efficient). ldap_group_base defines where in the LDAP database group information is found. See below this table for more info on using this.

Example: ldap_group_base dc=netwin,dc=co,dc=nz
Default: none
Required Setting: no

A search that will find the LDAP objects that contain usergroup information, it’s best to make this as specific as possible.

Example: ldap_group_search cn=group*
Default: none
Required Setting: no

ldap_group_field

Specify the field that contains the users email address in usergroup objects.

Example: ldap_group_field cn
Default: cn
Required Setting: no

ldap_group_attrib

Specify the attribute in a user group object that contains the information about each user.

Example: ldap_group_attrib uniquemember
Default: uniquemember
Required Setting: no

ldap_port

The TCPIP port to connect to the LDAP server on.

Example: ldap_port 3890
Default: 389
Required Setting: no

log_path

The file to store log files in

Example: log_path c:\logs\auth.log
Default: the location of the LDAPAuth executable ldapauth.log (older versions wrote to auth.log by default)
Required Setting: no

max_log_size

The size at which log files are rotated. Logs are numbered 1,2,3,4

Example: max_log_size 10000
Default: 100000
Required Setting: no

log_level

Controls the amount of information logged during use. One of error, info, debug.

Example: log_level debug
Default: info
Required Setting: no

ldap_host

The IP address or domain of the host to connect to, ie: the machine where the LDAP server is listening.

Example: ldap_host apples.com
Default: localhost
Required Setting: no

ldap_mgr_dn

The LDAP manager distinguished name to bind with. NB: add this field and the ldap_mgr_pw field with blank entries for anonymous login.

Example: ldap_mgr_dn cn=SurgeMail Manager
Default: cn=Directory Manager
Required Setting: yes

ldap_mgr_pw

The password for the ldap_mgr_dn entry.NB: add this field and the ldap_mgr_dn field with blank entries for anonymous login.

Example: ldap_mgr_pw secret
Default: none
Required Setting: yes

ldap_search_base

The LDAP search base to use for all interactions with the LDAP server

Example: ldap_search_base dc=apples,dc=com
(or, ldap_search_base o=apples)
Default: none
Required Setting: yes

ldap_search_name

 IMPORTANT: Specifies the attribute used for identifying the users entry in the database. eg: 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)

Example: ldap_search_name uid
Default: mail
Required Setting: no

pop_domain

The domain which will be appended to any usernames not containing @domain

NB: if set then you must use the setting,
authent_domain true
in surgemail.ini (and in netauth.ini if using NetAuth);

Example: pop_domain apples.com
Default: none
Required Setting: no, but recommended

ldap_objectclass

When adding new users LDAPAuth will add the new user to this ObjectClass.

Notes:

  • When using the set command, you must specify attributes (fields) and values for any attributes ‘required’ by the object class that you specify with this setting. You may not specify any attributes that are ‘not allowed’ in the objectclass.You must enter something like,
    set username pass a=”x” b=”y” c=”z”
    , where the fields a, b and c MUST be allowed in the specified objectclass, otherwise you will get an ‘objectclass violation’ error message. If you get that message then generally you need to alter the fields you are trying to set. Yes we wish there was a more informative error message also! Version 1.0k of LDAPAuth (and above) at least logs exactly which attributes and their values it is trying to set.
  • Often people forget to set cn=”xxx” and ‘violate the objectclass’, so remember to place it on the end of the set command (or make NetAuth put it there if using NetAuth).
  • Some older versions of LDAPAuth have the incorrect setting name,
    ldapobjectclass
    as an example in the example ldapauth.ini file.

Example: ldap_objectclass umichPerson
(umichPerson has the mail attribute that Person often does not);
Default: Person
Required Setting: no if using LDAPAuth for read-only, yes if using set command.

ldap_surgemail_forward

Name of LDAP attribute in database which will be used to store SurgeMail forwarding addresses. It can be set blank. If a value for this attribute is found when doing a lookup or check command then LDAPAuth responds with the info field,
fwd=”value”
e.g.,
fwd=”bob@another_domain.com”
causing mail redirection to that address.

See the SurgeMail Manual section,
Ext. Auth Fwd Field for further details.

Example: ldap_surgemail_forward alias
Default: mailForwardingAddress
Required Setting: yes, because you probably don’t want that bad default!

log_name

Base of log file name. Note suffix n.log will be appended so default is ldapauth1.log

Example: log_name c:\mylogdir\
(umichPerson has the mail attribute that Person often does not);
Default: LDAPAuth
Required Setting: no

sha_hash

On set command only, take password given and use the SHA to hash it. NB: this setting is really obsoleted by SSHA, which is done by default. If you really want SHA then you need to set the two settings as per the example below.

Example (If you really do want SHA not SSHA or plaintext):
sha_hash true
ssha_hash_dont true
Default: false (ssha instead)
Required Setting: no

ssha_hash_dont

Unless this setting is set to true, on the set command only, LDAPAuth will hash the given password using SSHA and prepend the string, {ssha} to the start of it before sending to the database. That way the database knows to SSHA the password sent by the LDAPAuth check command before comparing it with that user’s password in the database. Starting with version 1.0L LDAPAuth will SSHA all passwords when setting (adding) a user in the database. This setting is for turning that behaviour off.

To make LDAPAuth add users with plain text passwords as it used to, use the setting as per the example below and check that the sha_hash setting is false or not in the ini file.

Example: #sha_hash true (commented out, for plain text passwords)
ssha_hash_dont true
Default: false (ssha done automatically)
Required Setting: no

ldap_access_wild

A list of IP addresses from which POP logins are accepted if ‘pop’ is found in the users ldap_access_field field, this allows you to disable direct pop access and only allow POP access from your WebMail interface.

Example: ldap_access_wild 10.0.0.23,11.*,!11.1.1.2

ldap_access_field LDAP field in which to search for ‘pop’ if found then apply ldap_access_wild to POP logins dir_hash Makes LDAPAuth return a path for drop/bin processing, eg:

dir_hash 2 2 /var/mail

Would return /var/mail/ch/ri/chrisp instead of ‘config’ as the path.

ldap_search_name_alt

For example: ldap_search_name mail_alias

Would lookup the ‘mail_alias’ field for this user, if found, the ldap_uid field is then used to construct the drop path for this user, so this allows you to define aliases for a user. (very similar to forwarding) 

The feature is not intended for general use, avoid it if possible, it is intended for backward compatibility with pre existing LDAP databases.

ldap_uid uid Sets the UID field to use to construct a path for a user, see above setting. ldap_mailhost If a user cannot be found the normal way, LDAPAuth will try the user part of the address as a ldap_uid search, and then see if the ldap_mailhost matches it, if so it then delivers to that uid. Again this setting is not for general use it is only for backward compatibility with existing LDAP databases. strip_domain true Removes the domain name from all lookups (can be useful with active directory or other ldap databases where the domain is not in the database) ldap_map_domain

This setting is used to map a ‘domain.com’ setting to a seperate ‘search_base_dn’. This allows you to seperate each domain into a seperate part of the LDAP tree.
When you do this you should NOT map any sub domains.

ldap_map_domain domain.com dc=domain,dc=com
ldap_map_domain netwin.co.nz dc=netwin,dc=co,dc=nz

If not map for a domain is located it will default to the ‘ldap_search_base’ location.

Example: ldap_group_search cn=group*
Default: none
Required Setting: no

ldap_group_field

Specify the field that contains the users email address in usergroup objects.

Example: ldap_group_field cn
Default: cn
Required Setting: no

ldap_group_attrib

Specify the attribute in a user group object that contains the information about each user.

Example: ldap_group_attrib uniquemember
Default: uniquemember
Required Setting: no

ldap_port

The TCPIP port to connect to the LDAP server on.

Example: ldap_port 3890
Default: 389
Required Setting: no

log_path

The file to store log files in

Example: log_path c:\logs\auth.log
Default: the location of the LDAPAuth executable ldapauth.log (older versions wrote to auth.log by default)
Required Setting: no

Notes on using ldap_group* settings with DNews.

Command Line Options:

-pathTells LDAPAuth where to create it’s logfile and where to find it’s config file.
-debugSets the logging level to debug.
-logTurns on logging to nwauth.log.
-versionThis display the LDAPAuth version information
-filtername,str1,str2The username on a set,del,lookup,check command is check for ‘str1’ and replaced with ‘str2’
-convert_nwauth nwauth_pathThis will create a ‘nw_convert.bat’ file from the nwauth.add and nwauth.txt files that when run will run LDAPAuth with various commands to make the LDAP database match NWAuth setup.

Supported Commands

The commands below are the list of commands that this module supports. For a full description about the command see Authentication Protocol

CommandParameters
check<user> <pass>
lookup<user>
set<user> <pass>|(NULL) [label=”value”]
del<user>
search<string> [-from n] [-max m]
version
verbose
help
quit
exit

How do I upgrade NWAuth to LDAPAuth

To upgrade to LDAPAuth you need to following the following steps.

Step 1:Create your LDAP schema and setup LDAPAuth seperatly.
Ensure that your LDAPAuth uses the following ini setting:
unix_password true
The reason for this is that since NWAuth used 1 way encoding password you need to make LDAPAuth to use the same password encoding method.
Step 2:Test and get it working before nwauth user converted over.
You will need version 2.2u of LDAPAuth to preform this migration.
You should be able to create, delete, lookup and check users.
ie. ./ldapauth
set lynden pass
search lyn*
lookup lynden
check lynden pass
del lynden
Step 3:Once LDAPAuth works correctly the next step is to migrate the nwauth information to the LDAP server.
The 2 NetAuth files are ‘nwauth.add’ and ‘nwauth.new’, these are the 2 that need to be converted. keeping in mine that that ones that are deleted should not be added.

The Lastest LDAPAuth (v2.2u) as built in code to take these files and convert then into a .bat or .sh file that you can run which will populate LDAPAuth database.

To do this you run like this:
./ldapauth -convert_nwauth /usr/local/surgemail
or ./ldapauth -convert_nwauth c:\surgemail

This creates a file called: ‘nw_convert.sh’ or ‘nw_convert.bat’

Before you run the batch file you first need to setup ldapauth to accept the passwords as plain text otherwise they will be encoded twice. To do this you need to remove/comment out the ini setting ‘unix_password’ and add this ldapauth.ini setting:
plain_password true
This will make sure that the password is added in as is. Once you have run the batch file you then will need to remove the ‘plain_password’ and place back the ‘unix_password’.
Step 4:Test LDAPAuth.
You should be able to search, lookup and check the users you have just added.
ie. ./ldapauth
search lyn*
lookup lynden
check lynden pass

Example used with Active Directory (windows)

ldap_host 10.1.1.1
ldap_port 389
ldap_mgr_dn cn=ftpadmin1,ou=mgt_info_sys,ou=CTL,ou=region_sales,dc=example,dc=com
ldap_mgr_pw secret_password
ldap_search_base OU=region_sales,dc=example,dc=com
ldap_scope LDAP_SCOPE_subtree
ldap_search_name ExampleAccountName
ldap_group_base OU=region_sales,dc=example,dc=com
ldap_group_search CN=&*
ldap_group_field CN
ldap_group_attrib member

OpenLDAP server, available at:
http://www.openldap.org/

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

SDKs for LDAP are also available,
http://www.openldap.org/

.

Was this article helpful?

Related Articles