MMP Feature: Third Party Authentication Server Support
------------------------------------------------------

This directory includes sample code for a third-party authentication
server which can validate and modify authentication information
provided by the Messaging Multiplexor (MMP) component of Sun ONE
Messaging Server.  The MMP provides authentication proxy services for
IMAP and POP.

The protocol documented in the file "authserver.txt" is a fully
supported interface designed to integrate third-party authentication
services with the MMP.  The Messaging Server product team is committed
to fixing bugs in our client implementation of this protocol in the
MMP.

To enable third-party authentication, the MMP's "PreAuth"
configuration option must be enabled.  Then add the following
configuration option to the MMP's ImapProxyAService.cfg and/or
PopProxyAService.cfg file:

default:AuthenticationServer 127.0.0.1:56

For plain text logins, the MMP will first perform a normal user lookup
in LDAP.  Once the user is located, the MMP will connect to the host
(localhost: 127.0.0.1) and port (56) specified in the
AuthenticationServer option to authenticate the user.  You may also
configure the MMP to look up additional LDAP attributes and pass them
to the authuthentication server with the option:

default:AuthenticationLdapAttributes "attr1" "attr2" ...

Note that the authentication server should be running on the same
server as the MMP and on a restricted port.  The protocol used to
communicate between the MMP and the third-party authentication server
is not presently secured.

The MMP can be told to advertise additional SASL mechanisms (such as
GSSAPI for Kerberos) and use the authentication server to implement
them.  This is done by setting the MMP option:

default:ExtraSASLMechanisms GSSAPI NTLM ...

This option has no effect unless the AuthenticationServer and PreAuth
options are also set.  If this option is not set, it is presumed the
authentication server only supports the PLAIN mechanism.  A
mechanism name can be prefixed with a "*" to indicate that mechanism
requires data from the client before any processing is possible.
This hint will eliminate a round-trip between the MMP and the
authentication server in the event the client doesn't provide
initial client data (as IMAP clients do and POP clients may).

The programmer who wrote the sample code in this directory put some
effort into making it largely suitable for a production environment
(it uses a thread-pool model to handle a high volume of connections).
However, the Messaging Server product team will not provide support or
bugfixes for this sample code.  The sample code is designed for use on
a system which provides the standard Posix Threads API such as Solaris
or Linux.  The Makefile.sample is for use on Solaris.

MANIFEST
--------
README.txt           This file

authserver.txt       Third-Party Authentication Protocol Specification

Makefile.sample      Use "make -f Makefile.sample" to build the sample code
authserv.c           The core thread-pool protocol server implementation
authserv.h           The API called by authserv.c to authenticate users
sample.c             A very simple sample third-party authentication
                     module using plain-text passwords.  Third-parties
		     may edit or replace this module to provide
		     authentication services.
sample2.c            A simple CRAM-MD5 example demonstrating use of
                     this interface for non-plain-text mechanisms.
