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:

• Windows user database - documentation - in surgemail distribution (Windows)
• Unix password files - documentation - in surgemail distribution (UNIX)
• NetWin's own user database (NWAuth) - documentation - in SurgeMail distribution
• ODBCauth Microsoft SQL databases - documentation - download
• MySQL UNIX based SQL databases - documentation - download
• LDAP database - documentation - download
• Radius database - documentation - download
• Oracle database - documentation - download
• Linux PAM - documentation - download

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

• Multiple modules simultaneously - documentation - download
• TCP network connect - documentation - download

And of course you can write your own. Here is the protocol definition:

Valid commands:

• lookup username@domain.name
• check username@domain.name password [ip.address]
• search *user*@domain.name
• del username@domain.name
• set username@domain password [info]

(Only lookup and check are essential for the mail server, set and search and del are needed for the admin features to work)

Valid responses are:

• +OK username@domain.name drop_path uid [info]
• -ERR username@domain.name does not exist
• +DATA username@domain info...(response to search)
• -DEAD database offline, panic now

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, e.g. 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 it's 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 a 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

The following information can also be returned by an authent module:

quota=NNNN
fwd="user@domain"

For example:

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

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 :-)