pam_mapi - PAM module for authentication via MAPI against a Zarafa server

[Robert Scheck]

Good evening,

I'm very proud to present you my first PAM module which maybe makes the
life of some Zarafa administrators more easy; it's called "pam_mapi".

I also would like to thank hereby Tomas Mraz (Red Hat Czech), Tom Callaway
(Red Hat USA) and Kushal Das (Red Hat India) for their time, patience and
support! Especially Tomas did an awesome job by reviewing my source code.

pam_mapi is a module for PAM (Pluggable Authentication Modules). PAM is a
library that provides an interface for authentication services for Linux/
Unix systems and therefore allows to connect various system services with
one central authentication database. Administrators can ensure for example,
that all services are using a centrally stored password - and finally
prevent separate password databases. The PAM module "pam_mapi" takes care
of the authentication with a Zarafa server as a password database.

Applications such as Zarafa WebAccess, the Zarafa WebApp or Microsoft
Outlook (with the Zarafa Windows Client) connect directly via MAPI to SOAP
to the Zarafa Collaboration Platform and also handle the authentication via
that protocol when sending e-mails. If Zarafa is configured to use the
database plugin, all user information are stored in a MySQL database. Once
IMAP/POP3 is used via the Zarafa Gateway, often SMTP gets involved for
outbound e-mails, too. Usually this requires SMTP authentication (also
called "SMTP auth") in order to avoid socalled open relays but the user
information in the MySQL database is unfortunately not accessible for
established SASL daemons.

Although the password is generally hashed with MD5, is also salted with
a non-standard method. That surely improves security, but Cyrus SASL for
example expects a plaintext password expected in the database, if the
plugin "SQL auxprop" is used. The socalled "frost patches"
unfortunately
do not help here as well - given that they are not included in leading
Linux distributions which are being used in Enterprise environments. And
pam_mysql supports MD5 or SHA1 hashed passwords (aside from plaintext
passwords), but only without salts.

This gap is filled by pam_mapi which provides MAPI-based authentication,
that can be used by a SASL daemon for the SMTP service. Typically, Sendmail
or Postfix uses "saslauthd" (from Cyrus SASL), then takes care via pam_mapi
for the verification of the user information from the SMTP dialogue.
Finally, pam_mapi establishs a connection to the configured Zarafa server
and performs a login - and the result is returned accordingly to the SMTP
service which permits or rejects the outbound e-mail connection.

pam_mapi is licensed under the new BSD license (no advertising, three
clause). Alternatively, pam_mapi may be distributed under the terms of the
GNU General Public License (GPL), in which case the provisions of the GNU
GPL are required instead of the restrictions of the BSD license. This
clause is necessary due to a potential conflict between the GNU GPL and the
restrictions contained in a BSD-style copyright.

As pam_mapi is a generic PAM module, it could be used for any other PAM
related authentication, e.g. at the Apache Webserver. If it is stacked with
pam_unix it could allow authentication against Linux system and Zarafa
users, where a user only needs to exist in one of the two user databases.
However pam_mapi provides a limited PAM account functionality, because the
existence of an account can be only assured after succeeded authentication.

Although pam_mapi was primarily developed for use with Zarafa and the
database plugin, it is not limited to that. However, if the LDAP or Unix
plugins of Zarafa are used, the usage of pam_unix or pam_ldap should be
evaluated. At the moment, Zarafa is the only MAPI service provider of
MAPI4Linux (which is used by pam_mapi), but pam_mapi theoretically supports
various MAPI-based server services (e.g. Microsoft Exchange). 

The installation of pam_mapi on Fedora or Red Hat Enterprise Linux can be
simply performed via "yum". Note, that for Red Hat Enterprise Linux and
derivates like CentOS, the repository Extra Packages for Enterprise Linux
(EPEL) has to be enabled: http://fedoraproject.org/wiki/EPEL/FAQ#howtouse

  yum install -y pam_mapi

If the package is not yet available in the repositories, you can download
it manually from https://admin.fedoraproject.org/updates/search/pam_mapi.

After the installation, the configuration is required. A very common setup
will be to only authenticate against Zarafa, thus only Zarafa users. Please
put the following into the PAM configuration file for SMTP, usually it is
named "/etc/pam.d/smtp":

  #%PAM-1.0
  auth       required     pam_mapi.so try_first_pass
  account    required     pam_mapi.so

Alternatively, if the authentication shall happen against system and Zarafa
users, put the following into the "/etc/pam.d/smtp" file:

  #%PAM-1.0
  auth       sufficient   pam_mapi.so try_first_pass quiet
  auth       include      password-auth
  account    sufficient   pam_mapi.so
  account    include      password-auth

Configuration of "saslauthd" for usage of PAM as authentication mechanism
is possible in "/etc/sysconfig/saslauthd". Of course the MTA (Mail Transfer
Agent), so Sendmail or Postfix for example, must be configured for the use
with "saslauthd". If you use Sendmail, edit "/etc/mail/sendmail.mc"
and add
for example the following (in a simple setup):

  TRUST_AUTH_MECH(`LOGIN PLAIN')dnl
  define(`confAUTH_MECHANISMS', `LOGIN PLAIN')dnl

Instead, if you are using Postfix, edit "/etc/postfix/main.cf" and add the
following at the proper places or to existing configuration directives:

  smtpd_sasl_auth_enable = yes
  smtpd_recipient_restrictions = permit_mynetworks,
                                 permit_sasl_authenticated,
                                 reject_unauth_destination

Additionally, Sendmail users need to fill "/etc/sasl2/Sendmail.conf" or
"/usr/lib(64)/sasl2/Sendmail.conf" and Postfix users need to fill the file
"/etc/sasl2/smtpd.conf" or "/usr/lib(64)/sasl2/smtp.conf" with
following:

  pwcheck_method: saslauthd
  mech_list: plain login

Finally, restart the affected service, so for Sendmail:

  service sendmail restart

And if you are a Postfix user, execute this command:

  service postfix restart

Independent of Sendmail or Postfix, the "saslauthd" needs to be restarted:

  service saslauthd restart

For more information for configuring and possible options can be found in
the man page:

  man pam_mapi

In case you need help, you could write an e-mail to the Zarafa mailing list
at the Fedora Project on http://lists.fedoraproject.org or you could join
the IRC network Freenode on channel #zarafa.

And if you should find bugs or issues, please fill a bug report in Red Hat
Bugzilla as described here:

  http://fedoraproject.org/wiki/Zarafa#Bugs

Your feedback is very much appreciated.


Greetings,
  Robert