Authentication Modules - a guide

SurgeMail supports external authentication modules which are simple command line based programs that understand a small set of commands to add, remove and look up user details in your user database.

We provide modules for most common databases, including:

  • NTAuth - Windows user database - in surgemail distribution (Windows)
  • UnixAuth - Unix password files - in surgemail distribution (UNIX)
  • NWAuth - NetWin's own user database - in SurgeMail distribution
  • ODBCauth - ODBC data sources, i.e. Microsoft SQL databases
  • MySQLAuth - MySQL UNIX based SQL databases
  • LDAPAuth - LDAP database
  • RadiusAuth - Radius database
  • OracleAuth - Oracle database
  • PAMAuth - Linux PAM

We also have a few utilities for running the above modules in different ways, including:

All of these modules can be found here along with instructions on how each can be configured.

Of course, you can also write your own here is the protocol definition.

Authent modules should always be tested at the command line to see if they are working. Here is an example using NWAuth, the standard NetWin module:

c:> nwauth
set bob@test.com bob
+OK bob@test.com added to database
lookup bob@test.com
+OK bob@test.com config 0
check bob@test.com xxx
-ERR bob@test.com password wrong or not a valid user
search bo*@test.com
+DATA bob@test.com
+DATA bobcat@test.com
+OK Search Complete 2 items found out of 1510
set bob@test.com bob quota="200" fwd="fred@test.com"
+OK bob@test.com added to database
lookup bob@test.com
+OK bob@test.com config 0 quota="200" fwd="fred@test.com"

Choosing an Authent Module.

The web admin GUI will list available authent modules and guide you to the config pages for each authent module. Most authent modules have an ini file that needs to be configured, eg: odbcauth.ini or ldapauth.ini and a related binary.

When you download an authent module all files should be placed in the SurgeMail directory.

Again, test the authent module at the command line before telling SurgeMail to use it!!

Configuring the Authent Module.

Normally you configure the authent module through the admin interface, but if you find yourself editing the surgemail.ini by hand ensure you pass the -path command line parameter to the authent module, this is to tell it where to find its config file and any other files it might use, for example:

g_authent_process "c:\surgemail\nwauth.exe -path c:\surgemail"

The above tells NWAuth to look in c:\surgemail for it's files nwauth.add, nwauth.txt, etc.
The same is true for any module that has an .ini file.

If you're authent module is not working this is the most likely cause.

Extended info fields recognized by SurgeMail

SurgeMail uses the g_authent_info settings to define what fields it displays and where. Most fields have a 'hard-coded' use but others are simply there as examples of the kind of optional information you can collect about your users. The default settings are as follows:

g_authent_info name="Creation Stamp" field="created" access="none" default="" type=""
g_authent_info name="Forwarding" field="fwd" access="none" default="" type=""
g_authent_info name="SPF Block" field="spf_block" access="none" default="" type=""
g_authent_info name="Disk Quota (bytes)" field="quota" access="domadmin" default="" type=""
g_authent_info name="Full Name" field="full_name" access="user" default="" type=""
g_authent_info name="Phone" field="phone" access="user" default="" type=""
g_authent_info name="Password Retrieval Question" field="pass_question" access="createonly" default="" type=""
g_authent_info name="Password Retrieval Answer" field="pass_answer" access="createonly" default="" type=""
g_authent_info name="Access type" field="mailaccess" access="domadmin" default="" type=""
g_authent_info name="Account Status" field="mailstatus" access="domadmin" default="" type=""
g_authent_info name="Sms Number" field="smsto" access="domadmin" default="" type=""
g_authent_info name="Disabled" field="disabled" access="none" default="" type=""
g_authent_info name="User alias quota" field="alias_quota" access="domadmin" default="" type=""
g_authent_info name="User list quota" field="list_quota" access="domadmin" default="" type=""
g_authent_info name="User access settings" field="user_access" access="domadmin" default="" type=""
g_authent_info name="Msg limit per 30min" field="send_limit" access="none" default="" type=""
g_authent_info name="To host(g_proxy)" field="tohost" access="none" default="" type=""
g_authent_info name="Is an alias of" field="realuser" access="none" default="" type=""
g_authent_info name="Allowed to" field="allow" access="none" default="" type=""
g_authent_info name="Friends Enabled" field="friends" access="none" default="" type=""
g_authent_info name="Email Notification Address" field="enotify" access="none" default="" type=""
g_authent_info name="SpamPrivate private prefix" field="ddpriv" access="none" default="" type=""
g_authent_info name="SpamPrivate from prefix" field="ddfrom" access="none" default="" type=""
g_authent_info name="Card Name" field="ccname" access="user" default="" type=""
g_authent_info name="Card Number" field="ccnumber" access="user" default="" type="encrypt"
g_authent_info name="Card Expiry" field="ccexpires" access="user" default="" type=""
g_authent_info name="Card Security Code" field="ccciv" access="user" default="" type=""
g_authent_info name="Card Type" field="cctype" access="user" default="" type=""

Each field is used for a different purpose:

allow Services the user can access eg. SMTP,POP,IMAP.
created Record of creation time, stored on creation time.
ddfrom Private email 'from' suffix.
ddpriv Private email 'private' suffix.
enotify The email address to send email notifications to.
friends 'true' if the user has a friends mode configured.
full_name Example information about user (not required, example).
fwd Forwarding rules for the user, configured via users "Forwarding" page.
mailstatus Status of the account, see (account status)
pass_question Only used at creation time, collects password retrieval question (not stored in database).
pass_answer Only used at creation time, collects password retrieval answer (not stored in database).
phone Example information about user (not required, example).
quota Users disk quota, configured via the admininstrative interface.
spf_block 'true' if the user wants to block non spf compliant email.

For example:

+OK bob@test.com config 0 fwd="fred@test.com"
+OK bob@test.com config 0 quota="200000" fwd="joe@xx.com"

Advanced settings :

alias_quota Number of aliases this user can create
admin_access Features this domain admin can access
ccname Credit card holders name.
ccnumber Credit card number.
ccexpires Credit card expiry date mm/yy.
ccciv Credit card security code.
cctype Credit card type eg. Visa, Amex
disabled Used by email based account creation code (may also be used to disable existing accounts)
list_quota Quota of mailing lists the user can create.
mailaccess Used in conjunction with g_access_group and g_user_access to specify access to features.
realuser Real account to which this account is aliased - allows aliases to be specified in authent database
send_limit Number of outgoing messages this user can send per 30 minutes. You must also define the global limits g_tarpit_max, and g_tarpit_max_remote. And you may want to set g_tarpit_drop "true"
smsto SMS phone number to send SMS nontifications to users "SMS" page.
tohost The host which to connect to when using proxy mode (g_proxy)
user_access Features this user can access

Legacy settings :

accountstatus Numeric equivalent of mailaccess
droppath The user's drop path, this is no longer supported and will not work with all SurgeMail functionality.
groups Example setting used to be installed for default SurgeMail installs

Mixed case usernames and domains

SurgeMail will lowercase domains in all cases, and for usernames and passwords entered in mixed case it will attempt a lookup 'as is' and then a second one using lowercase, this helps avoid problems with users accidentally mixing case. 

In all cases drop paths etc are created using lowercase as this avoids the terrible mess on UNIX that can occur.  This does mean it is impossible to have two different users who are only distinguished by case.  This is of course an intentional feature and not a bug. We think anyone who actually wants multiple users with the same name is a little crazy :-)

Example configuration of firstname and lastname for LDAPAuth

This is an example of how to configure LDAPAuth for SurgeMail such that the user must enter a first and last name upon creation. This is how you might configure it for use with the Thunderbird LDAP client.

First, in ldapauth.ini add/change:

info_fields full_name cn

info_fields firstname givenName
info_fields lastname sn

and remove:

must_set_fields sn name
must_set_fields cn name

Next, in surgemail.ini configure:

g_authent_info name="First Name" field="firstname" access="user"
g_authent_info name="Last Name" field="lastname" access="user"

and for each domain configure:

create_reqd "firstname,lastname"

Then stop and restart the surgemail process. Users will now see two fields additional on the self creation page "First Name" and "Last Name" the data entered here will be stored in the LDAP fields specified "givenName" and "sn" and Thunderbird will use these values.

Example config used with ActiveDirectory (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