Login: HTTP Authentication plugin for SquirrelMail
==================================================
Ver 2.1, 2008/06/18


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



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

If you keep SquirrelMail behind a password-protected directory
on your web server and if PHP has access to the username and
password used by the web server, this plugin will bypass the
login screen and use that username/password pair.  

Note that this means that you must keep your usernames and
passwords in synch between your web server's authentication
file (typically .htpasswd for Apache) and your IMAP server!
If both username/password stores do not contain the same
information, your users will not be able to log in without
entering the two different sets of usernames and passwords.

If you have not password-protected your SquirrelMail directory,
this plugin will turn itself off, and logins will work as they
normally do using the SquirrelMail login page.



License
=======

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



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://sourceforge.net/donate/index.php?user_id=508228



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

  * SquirrelMail version 1.4.0 or above

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



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

  * 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.  Here are a few tips for doing so, 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.

  * In an Apache environemnt, you need to first set up a password
    file.  Try typing "man htpasswd" in a terminal window in
    *nix-based machines, or search the web for "htpasswd".  That
    command helps you set up usernames and passwords.  Remember
    that the usernames you use must match your IMAP usernames
    EXACTLY!  That means that if your IMAP logins are in the form
    of full email addresses, you have to use those here too.

  * You also need to tell your web server to protect your
    SquirrelMail directory with a .htaccess file therein or in
    a <Directory> directive (both assuming an Apache environemnt).
    Here is a sample of the latter (for use in .htaccess files,
    just remove the <Directory> lines):

       <Directory "/var/www/html/squirrelmail/">
         AuthType Basic
         AuthName "SquirrelMail"
         AuthUserFile /var/lib/squirrelmail/htaccess_passwords
         require user mary pablo jona
       </Directory>

  * Unless users logging in using HTTP authentication credentials
    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

  * Note that when PHP is in safe mode ("safe_mode = On" in php.ini),
    the password and/or username from the HTTP authentication won't
    be available and this plugin won't have any effect (will appear
    to be disabled).  Always check your PHP safe_mode setting before
    asking for support.



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
==========

  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

