mod_auth_cache - Version 0.1.1 <25-03-2002>
-------------------------------------------
This apache module transparently caches an authentication originally done by
a different module. 
The aim of this module is to speed up complex authentication mechanisms, to
reduce database traffic if authenticating thru a backend database and to
implement some sort of authentication reliability if the database server
fails.
Another aim is to allow single-signon in a domain.
As the caching is completly transparent done by the webserver, you don't
have to change or implement new functions in your existing applications. 
The module only caches a users authentication and not a users access
permissions, which are still be controlled by a different module. 

The caching is realized using session cookies and can be customized by the
following directives
(Place them in <Directory>, <Location> or .htaccess): 

* AuthCache on|off 
  Turns caching on or off; Default: off 
* AuthCacheTimeout seconds 
  Sets timeout in seconds for reauthentication; Default: 0 (= never) 
* AuthCacheSaveAuthorization on|off 
  Save and restore authorization header; Default: off
  !!! ATTENTION !!!
  If activated, the users password is stored in the cookie and it will be
  possible that some applications on your server read out the value! 
* AuthCacheSuppressPort on|off
  Turns the check for the server port 
  on/off. Set it to on for a single-signon. Default: off 
* AuthCacheDomainName name
  Sets a domain name instead of using the apache own name. 
  Allows cross subdomain cookies. Default: nothing = use apaches name 
* AuthCacheSendFullPath 0|1
  Changes the way the cookiepath is calculated.
  Set it to '0'== 'send full path' for cookie; '1'== 'send only root-path'.
  For single-signon set it to 1. Default is 0,
* AuthCacheSendDomain 0|1|2|3
  Changes the way the domain part of the cookie is calculated.
  '0'== dont send a domain part.
  '1'== send the full domain as the cookie domain part.
  '2'== take the full domain, kill the part before the first '.' and 
        than use the rest as the cookie domain part.
  '3'== take the full domain, kill the part before the first&second '.' and 
        than use the rest as the cookie domain part.
  For single-signon use '2' or '3' to make from your servername your domain.
  For single-signon with an AuthCacheDomainName use '1' (all over make no sense!).
  Default is 0,
* AuthCacheExtraDomainName name
  Sets an additional domain name to send a cookie too. You can use this to get 
  a single-signon over two different domains. 
  It is only evaluated if AuthCacheSendDomain > 0 !
  !!! Attention: !!! 
  This is outside the original cookie specs made by netscape.But we found, that 
  a lot of browsers today, can accept cookies cross-domain. 
  !!! Attention: !!! 
  This is an feature only beta tested due to the limitted number of different 
  domains in our intranet!

Example how to make a single-signon:
  * You need minimum 2 (virtual)-servers.<br></LI>
  * Each one must have this module and an other authentificatiuon module (mod_auth, 
    mod_authldap,...) installed. 
    Take care that all servers use the same authentifaction modules (check the versions!)
  * Each server must be a member of Your domain. Our example has two: 
      web1.enbw.net and web2.enbw.net
  * Ensure that the time of all servers is identicall (dont let them run with 
    different times!)
  * Set in all directories You want to protect, the following parameters for this 
    module (example with mod_auth):
      AuthCache on
      AuthCacheSaveAuthorization on
      AuthCacheSuppressPort on
      AuthCacheSendDomain 2
      AuthCacheSendFullPath 1
      AuthName "example"
      AuthType basic
      AuthUserFile /usr/local/apache/htdocs/userfile
      AuthGroupFile /usr/local/apache/htdocs/group
      require valid-user
  * When You adapt this example take care, the AuthName and AuthType must be 
    the same on every directory if You want to allow single-signon.

How does the caching mechanism work?
If a client connects to the webserver the module reads a specific cookies
value and sets the users remote_user property from that value. If the cookie
isn't present or invalid, the module declines the authentication process
that afterwards will be passed to a different module. After that module
authenticates the user, mod_auth_cache will write the username into that
specific cookie.

Be sure to always check your apache configuration that mod_auth_cache is
loaded before the real authentication module (which means you have to place
it AFTER the authentication module in httpd.conf!). If not, the module can't cache
the authentication because the authentication process will always be
finished by the real authentication module and so the caching procedure
won't be executed. 

restrictions
------------
* You cant use this module on a proxy-directory (see mod_proxy). 
  Mod_proxy will not give the Set-Cookie header back to the client !


tested authentication modules
-----------------------------
* mod_auth 


tested platforms
----------------
* Linux-Mandrake i586 8.0 with Apache-AdvancedExtranetServer 1.3.19 
* Suse Linux-7.3 i586 with Apache-Server 1.3.20 
* Solaris 8 (Sparc) with Apache-Server 1.3.20 


roadmap
-------
The following features are on their way into the next release (Version 0.2.0) 
* choice for stronger cookie encryption 
  the current base64 encryption can be manipulated very easy and so you can
  fake your user authentication to become every webuser in your application
  !!! 
* optional stronger security by storing a users authentication on the server
  and not completly in the client cookies 
* testing of more platforms and authentication mechanisms 
* and of course more documentation 


bugs, wishlist & feedback
-------------------------
Please use the tracker at the projects sourceforge page or send an email to
<Email@Heiko-Schwarz.com> 


lastest release & project page at sourceforge
---------------------------------------------
 >> http://sourceforge.net/projects/mod-auth-cache/ 

mod_auth_cache is available free of charge under the GPL License. 

--------------------------------------------------------------------------------
Copyright  2001 Heiko Schwarz <Email@Heiko-Schwarz.com> 
Copyright  2002 M.Kuhn, EnBW Servicegesellschaft <m.kuhn@enbw.com>
Last Update: 25-03-2001 