Various Authentication Modules

### External Authentication Modules

> There are various external authentication modules available. Below are the ones that are explained on this page.

> > - LDAPAuth External
> > - MySQLAuth External
> > - RadiusAuth External
> > - Check Install
> > - Auth.ini settings

### LDAPAuth External

> LDAPAuth is the external module that talks to the LDAP back end database. LDAP can be downloaded from the following URL:

> > http://www.openldap.org/

Installing LDAPAuth

When you download LDAPAuth you should get two files:

UNIX | NT
ldapauth ldapauth.ini | ldaplauth.exe ldaplauth.ini

Place these files into your DMail directory and update dmail.conf to point to this external module.

> > e.g.
> > On UNIX:
> > authent_method external
> > authent_process /usr/local/dmail/ldapauth

> > On Windows:
> > authent_method external
> > authent_process c:\dmail\ldapauth.exe

Edit the ldapauth.ini settings

Then restart the DMail Servers.

The old LDAPAuth page is mostly about out of date settings, but it does have good information on setting up an LDAP server.

### MySQLAuth External

> MySQLAuth is the external module that talks to the back end data base called MySQL. MySQL can be downloaded from the following URL:

> > http://www.mysql.com/

Installing MySQLAuth

> When you download MySQLAuth you should get two files:

> UNIX | NT
> mysqlauth mysqlauth.ini | mysqlauth.exe mysqlauth.ini

> Place these files into your DMail directory and update dmail.conf to point to this external module.

> > > e.g.
> > > On UNIX:
> > > authent_method external
> > > authent_process /usr/local/dmail/mysqlauth

> > > On Windows:
> > > authent_method external
> > > authent_process c:\dmail\mysqlauth.exe

> Edit the mysqlauth.ini settings

> Then restart the DMail Servers.

> MySQLAuth requires a MySQL database to be setup and working. The database that is setup must have a username and a password that is encrypted using the mysql command PASSWORD(). You can either create a new database/table for MySQLAuth or use a current database that has usernames and passwords.

> New DataBase:

> Below are instructions on how to setup a brand new database and table to work with MySQLAuth, with all of the features that MySQLAuth provides.

> > > CREATE DATABASE maildb

> > > USE maildb;
> > > CREATE TABLE maildb (
> > > username CHAR(128) binary DEFAULT '' NOT NULL,
> > > passwd CHAR(128) DEFAULT '*' NOT NULL,
> > > forward CHAR(255) DEFAULT '',
> > > quota CHAR(20) DEFAULT '',
> > > mailmask CHAR(18) DEFAULT '0.0.0.0' NOT NULL,
> > > maildrop CHAR(255),
> > > PRIMARY KEY (username)
> > > );

> To insert a brand new account into this account using your mysql client use the command:

> > > INSERT INTO maildb VALUES
> > > ('test@test.org', PASSWORD('test'), '', '100k',
> > > '0.0.0.0','/usr/spool/mail/test');

> > > This will create a user called test@test.org with the username of test.

> To manually remove a user the command is:

> > > DELETE FROM maildb WHERE username='test@test.org'

> Note: The inserting and deleting of users is taken care of by MySQLAuth, the above is to show how you would manually do this.

> The ini settings for the above would look like the following:

> > > > > mysql_server your.mysql.server
> > > > > mysql_login login
> > > > > mysql_password password

> > > > > domain your.default.domain

> > > > > mysql_mail_user_db maildb
> > > > > mysql_mail_user_table maildb

> > > > > field_username username
> > > > > field_password passwd
> > > > > field_forward forward
> > > > > field_quota quota
> > > > > field_mailmask mailmask
> > > > > field_maildrop maildrop

> Using Current DataBase:

> If you already have an existing database that you wish to use then as long as the usernames are unique and the password field is encrypted using the PASSWORD() mysql command, then you should be able to just change the ini settings to point to this database, table and field label names.

> > > e.g. If you have a database called 'accounts' and a table called 'mail_users' that stores all sorts of information but has the username field names 'name' and the password field called 'pwd' then the ini settings that you required are:

> > > > > mysql_server your.sql.server
> > > > > mysql_login login
> > > > > mysql_password password

> > > > > domain your.default.domain

> > > > > mysql_mail_user_db accounts
> > > > > mysql_mail_user_table mail_users

> > > > > field_username name
> > > > > field_password pwd

> If you have the ability to also store the mail quota or forwarding then you can add these ini settings as well.

> > > > i.e. field_forward forward
> > > > field_quota quota

The old MySQLAuth page is mostly about out of date settings, but it does have good information on setting up a MySQL server.

### RadiusAuth External

> RadiusAuth is the external module that talks to the back end data base called Radius. Radius can be downloaded from the following URL:

> > > http://www.freeradius.org/

Installing RadiusAuth

When you download RadiusAuth you should get two files:

UNIX | NT
radiusauth radiusauth.ini | radiusauth.exe radiusauth.ini

Place these files into your DMail directory and update dmail.conf to point to this external module.

> > e.g.
> > On UNIX:
> > authent_method external
> > authent_process /usr/local/dmail/radiusauth

> > On Windows:
> > authent_method external
> > authent_process c:\dmail\radiusauth.exe

Edit the radiusauth.ini settings

Then restart the DMail Servers.

RadiusAuth requires a radius database that is setup and working. You will need to have already setup an encryption key for the host or IP of the machine that is running DMail. It goes in the radius clients file, normally located at:

> > /etc/raddb/clients

You will need to add a line like:

> > mail.ip.host encryption_key

You will also need to setup the radiusauth.ini file to point correctly at your radius server the ini settings are:

> > radius_host your.radius.server
> > radius_secret encryption_key

Check Install

Once the auth module is installed, it is best to then check that it is working correctly. You will need to run it from the command line,

e.g. On UNIX

> > cd /usr/local/dmail
> > /mysqlauth

On Windows

> > cd \dmail
> > mysqlauth

and try the following.

NOTE: C: - Client, S: - Server

> > C: set test_account password
> > S: +OK 'test_account@test.org' has been added to database

> > C: set test_fwd password fwd="test_account@domain1"
> > S: +OK 'test_account@test.org' has been added to database

> > C: set test_quota password quota="100k"
> > S: +OK 'test_account@test.org' has been added to database

> > C: set test password fwd="test_account@domain1" quota="100k"
> > S: +OK 'test_account@test.org' has been added to database

> > C: search *
> > S: +DATA test_quota@test.org config 0 quota="100k"
> > S: +DATA test_fwd@test.org config 0 fwd="test_account@domain1"
> > S: +DATA test_account@test.org config
> > S: +DATA test@test.org config 0 fwd="test_account@domain1" quota="100k"
> > S: +OK Search Completed 4 items found

> > C: lookup test_quota
> > S: +OK test_quota@test.org config 0 quota="100k"

> > C: lookup test
> > S: +DATA test@test.org config 0 fwd="test_account@domain1" quota="100k"

> > C: check test password
> > S: +OK test@test.org config 0 fwd="test_account@domain1" quota="100k"

> > C: check test incorrect
> > S: -ERR test@test.org password wrong or not a valid user

> > C: del test
> > S: +OK 'test@test.org' has been deleted

> > C: del test_account
> > S: +OK 'test_account@test.org' has been deleted

> > C: del test_quota
> > S: +OK 'test_quota@test.org' has been deleted

> > C: del test_fwd
> > S: +OK 'test_fwd@test.org' has been deleted

The actual response to quota and fwd might vary if the mysql database does not have quotas or fwd setup. To display the complete list MySQLAuth supports enter the command:

> > help

Information about the protocol being used can be seen at the link:

> > http://netwinsite.com/dmail/authprot.htm

### Standard Auth.ini settings

These settings may be used in the ini file of any of the auth modules on this page.

Label | Example | Default | Explanation
log | true | false | Enables verbose debug output.
unix_password | true | false | Only designed to be used on UNIX machines. Tells the auth program to use the UNIX password system for storing passwords.
plain_password | true | false | Tells the auth program to save the passwords as clear text.
domain | your.default.domain | (none) | This is the domain that is attached when users are created in the database. e.g. lynden becomes: lynden@your.default.domain
lowercase_username | true | false | This will convert all usernames to lowercase when comparing names.
lowercase_username_set | true | false | This will convert all names to lowercase before adding them to the database.
search_min | 3 | 0 | This is the minimum number of characters that any search routine must have before a search is performed.

LDAPAuth Settings

Label | Example | Default | Explanation
ldap_host | your.ldap.server | localhost | This is the LDAP server that ldapauth will use.
ldap_port | 1111 | 389 | This is the port on which the LDAP server listens.
ldap_mgr_pw | password | (none) | This is the managers password
ldap_mgr_dn | cn=Manager,dc=your,dc=domain,dc=com | (none) | This is the managers DN.
ldap_search_base | dc=your,dc=domain,dc=com | (none) | This is the base location from which to start database searches.
ldap_search_name ldap_search_name_alt ldap_search_name_alt2 | mail | (none) | These are the alternative fields that the email address information could be stored.
ldap_uid | UID_field | (none) | The name of the field that stores the UID vairable which the mail server uses. NB: if not found or not set then ldapauth returns the special UID 0 which is sufficient in most cases.
ldap_objectclass | yourperson | person | The name of the ObjectClass defined in your LDAP data base.
ssha_hash_dont sha_hash | true | false | These are used to determine the encoding method of the password inside the LDAP database.(Default is SSHA, not SHA)
ldap_scope_base | True | False | Determines the LDAP search scope for the system. If set true, LDAPAuth will search on the selected object.
ldap_scope_onelevel | True | False | Determines the LDAP search scope for the system. If set true, LDAPAuth will search only this level.
ldap_scope_subtree | True | False | Determines the LDAP search scope for the system. If set true, LDAPAuth will search this and any sub level.
ldap_dnshort |  | (none) | Set this if the LDAP database is setup to use a shortdn domain name instead of the full name.
ldap_group_base | dc=your,dc=domain,dc=com | (none) | The base location in your LDAP structure from which to start searching for your user data.
ldap_group_search | cn=group* | (none) | Where group access information is stored.
ldap_group_attrib | cn | cn | The attribute name of where the username will be stored.
ldap_group_field | uniquemember | (none) | The Unique Member number
ldap_dmail_forward | fwd | (none) | The name of the forward field stored in the 'person' structure.
ldap_mailmask | mail | (none) | The name of the 'mailmask' field in your database.
ldap_dmail_uid | uid | (none) | The name of the 'Unique ID' field in your database.
ldap_drop_path | dpath | (none) | The name of the 'Drop Path' field in your database.
ldap_mailhost | domain | (none) | The name of the 'mailhost' field in your database.
ldap_maildeliveryoption | forwardcc | (none) | Takes a field name for forwarding addresses. If specified and if ldap finds an address in the field to use, ldap will automatically ensure that the original username is also carbon copied the message, i.e. it returns fwd="$user,<address>" (to make it compatible with Netscape's LDAP system)
info_fields | usergroups groups mail test description des | (none) | This field is used to match LDAP field entries with external program field names that are also delivered to and from the database.
must_set_fields | cn name,cn "LDAPAuth v1.1a",sn name | (none) | These are fields that MUST also be specified when adding or updating any data in the LDAP server. NOTE: The following keywords can be used. 'name' is replaced with the username (user). 'email' is replaced with the email address (user@domain). 'dn' is replaced with the dn entry: (cn=lynden@domain,dc....).
field_alias field_aliasuser |  | (none) | These fields are used to alias usernames in the database.
field_username | username | (none) | This is the name of the field that stores the username.
field_password | passwd | (none) | This is the name of the field that stores the password.
pop_domain | your.domain.com | (none) | (Obsolete)

MySQLAuth Settings

Label | Example | Default | Explanation
mysql_server mysql_server2 | your.sql.server | localhost | This is the IP number/name to the sql server that you are using. If the connection to the main server goes down the second server is used.
mysql_login mysql_password | username password | (none) | This is the username and password to get access to the SQL server.
mysql_mail_user_db | maildb | (none) | Specifies the name of the database to lookup users in.
mysql_mail_user_table | maildb | (none) | Specifies the name of the table within the database to lookup users in.
maildb_mail_alias_db | alias | (none) | Specifies an alternative database, which contains aliases for real usernames. If set, mysqlauth will lookup the user in this database to resolve the real username behind the alias and use the result to lookup the main database.
maildb_mail_alias_table | alias | (none) | Specifies the table to use in the alternative (aliases) database.
mysql_mail_uid | 0 | (none) | This is the unique user id number that if found is returned by the auth module.
field_alias field_aliasuser | alias | (none) | The name of the fields that store the aliases.
field_username field_password | username password | (none) | The name of the fields that store the username and passwords.
field_forward field_quota field_mailmask field_maildrop | fwd qouta mailmask dmail | (none) | Specify the database field name for the DMail field with the matching name.
info_fields | usergroups groups mail test description des | (none) | This field is used to match MySQL field entries with external program field names. The values for these fields are set and retrieved from the database.
sqlsuffix_lookup_where sqlsuffix_check_where sqlsuffix_set | and this='that' | (none) | These settings specify a suffix to append to the command that is sent to the SQL server.
domain_split | domainfield | (none) | If set mysqlauth will split up the full username received into separate user and domain fields, e.g. bob@domain1.com becomes user=bob and domain=domain1.com. The setting value specifes the name of the field to store/lookup the domain name.

RadiusAuth Settings

Label | Example | Default | Explanation
radius_host | your.radius.server | localhost | This is the IP address or Name of the radius server.
radius_port | 2812 | 1812 | This is the TCPIP port of the radius server (Normally 1812)
radius_secret | encryption_key | (none) | This is the encryption_key that is setup on the radius server that the Mail server needs to use.
radius_attribute | 26 | (none) | This is the radius attribute that is used that stores the fwd and quota settings. (string)
field_username | user | username | The label of the username field in your table.
field_password | password | passwd | The label of the password field in your table.
field_forward | fwd | forward | The label of the forward field in your table. This is the forwarding information that DMail uses to determine what it forwards the EMail to.
field_quota | quota | (none) | The label of the quota field in your table. This is the disk quota the user has. e.g. 100k, 10M
field_mailmask | mailmask | (none) | The label of the mailmask field in your table. This is the IP mask that SQLAuth checks against the "from IP" of the user. This forces the user to use only the specified IP.
field_maildrop | maildrop | (none) | The label of the maildrop field in your table. This is the location where dmail will drop the user mail files.
radius_user_file | radius.dat | (required) | This is the file where usernames/passwords are stored so that lookups without passwords can be done, i.e. mysqlauth stores the passwords itself as it adds the users.