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!
For single-signon set it to on (all over make no sense!).

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'== donīt 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!

You need minimum 2 (virtual)-servers.

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 (donīt 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.

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 canīt 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.