Login Authentication plugin for SquirrelMail
============================================
Ver 3.0, 2012/05/29


Copyright (c) 2004-2012 Paul Lesniewski <paul@squirrelmail.org>
Copyright (c) 2001 Tyler Akins



Description
===========

This plugin tells SquirrelMail how to understand when users
have been externally authenticated, in which case the SquirrelMail
login page is unnecessary.  Common uses of this plugin are for
environments that employ HTTP authentication or have implemented
single sign-on systems.  Remember that SquirrelMail still needs
to authenticate against your IMAP server, so SquirrelMail still
needs to know what credentials to use and how to get them.  Assuming
you've coordinated your IMAP authentication with your external
web authentication, this plugin helps with those tasks.

The default behavior of this plugin assumes HTTP authentication
where the web server makes the username and password available to
PHP.  In this kind of environment, all you need to do is ensure
that the user credentials in your HTTP authentication system match
those that your IMAP server uses.

This plugin also supplies modules to handle SAML single sign-on
authenticated users in a couple different ways and allows you to
easily create custom modules for any other system.  See the
configuration file for more details.

By default, if a user is not externally authenticated, the user
is allowed to log in using the standard SquirrelMail login page,
but this plugin can be configured to disallow this, instead
referring the user to your external login page.



Donations
=========

If you or your company make regular use of this software,
please consider supporting Open Source development by
donating to the authors or inquire about hiring them to
consult on other projects.  Donation/wish list links for
the author(s) are as follows:

Paul Lesniewski: https://squirrelmail.org/donate_paul_lesniewski.php



License
=======

This plugin is released under the GNU General Public
License (see the file COPYING for details).



Requirements
============

  * SquirrelMail version 1.4.0 or above, or version 1.4.23
    or above when using the "trusted_saml" SAML module

  * Compatibility plugin version 2.0.7 or above, unless
    using SquirrelMail version 1.4.10+ or 1.5.2+

  * PHP Zlib support (compile with --with-zlib) only if
    you are using the compression feature with the
    "authenticated_saml" module
    See: http://php.net/manual/en/zlib.installation.php



Troubleshooting
===============

  * Unless users authenticating externally have set the
    "Options-->Display Preferences-->Use Javascript" option to
    "Always", JavaScript functionalities will not be enabled
    because the "Autodetect" setting uses an autodetection scheme
    in the SquirrelMail login page, which is skipped by this
    plugin.  If you so choose, you can force all users to "Always"
    by using one of the methods described here:

       http://www.squirrelmail.org/docs/admin/admin-5.html#ss5.6

  * If changes to the configuration file don't seem to be having
    any effect, ensure that there are not two Login Authentication
    configuration files, one in the login_auth directory and
    one in the main SquirrelMail config directory (named
    "config_login_auth.php").  The one in the main SquirrelMail
    config directory will always override the one in the
    login_auth directory.

  * Note that this plugin is not compatible with some plugins
    that run on the login screen, such as the Multilogin plugin

  * When using the "trusted_saml" module, did you set SquirrelMail's
    IMAP authentication mechanism to "plain"?  You can do that in
    the main SquirrelMail configuration file or use the configuration
    tool to do so: config/conf.pl ==> 2. Server Settings ==>
    A. Update IMAP Settings ==> 6. Authentication type

  * When using the "trusted_saml" module, did you set 
    $trusted_saml_username and $trusted_saml_username in the
    configuration file?  This plugin should only be used AFTER
    you have confirmed that you have a working single sign-on
    authentication system in place.  You can find a few tips for
    doing so using a Shibboleth-based system in the
    contrib/README.Shibboleth file, but if you have more detailed
    questions, you need to search for the answers in locations
    specific to Shibboleth, which does NOT include the plugin
    authors or the SquirrelMail mailing lists.

  * When using HTTP authentication, did you correctly configure
    HTTP-based authentication on your web server?  This plugin
    should only be used AFTER you have confirmed that you have a
    working HTTP authentication system in place.  You can find a
    few tips for doing so in the contrib/README.HTTP_authentication
    file, but if you have more detailed questions, you need to
    search for the answers in locations specific to your web
    server software, which does NOT include the plugin authors
    or the SquirrelMail mailing lists.

  * For the "authenticated_saml" module, you should first ensure
    that you have a working single sign-on authentication system
    in place.  You can find a few tips for doing so using a
    crudesaml/mod_auth_mellon-based system in the contrib/README.crudesaml
    file, but if you have more detailed questions, you need to
    search for the answers in locations specific to crudesaml or
    mod_auth_mellon, which does NOT include the plugin authors or
    the SquirrelMail mailing lists.



Help Requests
=============

Before looking for help elsewhere, please try to help yourself:

  * Read the Troubleshooting section herein.

  * Look to see if others have already asked about the same issue.
    There are tips and links for the best places to do this in
    the SquirrelMail mailing list posting guidelines:
    http://squirrelmail.org/wiki/MailingListPostingGuidelines
    You should also try Google or some other search engine.

  * If you cannot find any information about your issue, please
    first mail your help request to the squirrelmail-plugins
    mailing list.  Information about it can be found here:
    http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
    You MUST read the mailing list posting guidelines (see above)
    and include as much information about your issue (and your
    system) as possible.  Including configtest output, any debug
    output, the plugin configuration settings you've made and
    anything else you can think of to make it easier to diagnose
    your problem will get you the most useful responses.  Inquiries
    that do not comply with the posting guidelines are liable to
    be ignored.

  * If you don't get any replies on the mailing list, you are
    welcome to send a help request to the authors' personal
    address(es), but please be patient with the mailing list.



TODO
====

  * Ideas?



Change Log
==========

  3.0  2012/05/29  Paul Lesniewski <paul@squirrelmail.org>
   * Added the ability to use this plugin for other external
     login systems (aside from just HTTP authentication), such
     as some single sign-on systems.
   * Thanks to Emmanuel Dreyfus for help with the "authenticated_saml"
     module and Victoriano Giralt for help with the "trusted_saml" module
   * Added compatibility with the Login Manager plugin
   * Added configuration file that allows administrators to
     fine-tune the behavior of this plugin, particularly if
     using a custom single sign-on system.  Those using HTTP
     authentication do not need to create a configuration file
     of their own - the default behavior will suffice in these
     cases.

  2.1  2008/06/18  Paul Lesniewski <paul@squirrelmail.org>
   * Log out of IMAP connection made during login page hook
   * Update plugin documentation and some minor code updates
     to bring into conformance with newest plugin specifications
   * Added custom signout page that reflects the true nature
     of disposing HTTP authentication credentials

  2.0  2004/10/06  Paul Lesniewski <paul@squirrelmail.org>
   * Rewrote the whole plugin so that it works as a normal 
     plugin (as opposed to a bit of a hack)
   * If username/password pairs don't match, SquirrelMail's login
     page is correctly shown again
   * Conformance with SquirrelMail plugin requirements and 
     other cleanup

  1.1  2001/05/02  Tyler Akins
   * Removed serious security issue -- the password was being
     logged in the web server logs.

  1.0  2001/05/01  Tyler Akins
   * Initial release

