DESCRIPTION

This class is responsible for creating user objects (see Apache2::SiteControl::User) and managing the interfacing of those objects with a persistent session store. The default implementation uses Apache::Session::File to store the various attributes of the user to disk.

If you want to do your own user management, then you should leave the User class alone, and subclass only this factory. The following methods are required:

makeUser($$)

This method is called with the Apache Request object, username, password, and all other credential_# fields from the login form. It must create and return an instance of Apache2::SiteControl::User (using new...See User), and store that information (along with the session key stored in cookie format in the request) in some sort of permanent storage. This method is called in response to a login, so it should invalidate any existing session for the given user name (so that a user can be logged in only once). This method must return the key to use as the browser session key, or undef if it could not create the user.

findUser($$)

This method is passed the apache request and the session key (which you defined in makeUser). This method is called every time a ``logged in'' user makes a request. In other words the user objects are not persistent in memory (each request gets a new ``copy'' of the state). This method uses the session key (which was stored in a browser cookie) to figure out what user to restore. The implementation is required to look up the user by the session key, recreate a Apache2::SiteControl::User object and return it. It must restore all user attributes that have been saved via saveAttribute (below).

invalidate($$)

This method is passed the apache request object and a previously created user object. It should delete the user object from permanent store so that future request to find that user fails unless makeUser has been called to recreate it. The session ID (which you made up in makeUser) is available from $user->{sessionid}.

saveAttribute($$$)

This method is automatically called whenever a user has a new attribute value. The incoming arguments are the apache request, the user object, and the name of the attribute to save (you can read it with $user->getAttribute($name)). This method must save the attribute in a such a way that later calls to findUser will be able to restore the attribute to the user object that is created. The session id you created for this user (in makeUser) is available in $user->{sessionid}.

Apache Config Directives

The following is a list of configuration variables that can be set with apache's PerlSetVar to configure the behavior of this class:

SiteControlDebug (default 0):

Debug mode

SiteControlLocks (default /tmp):

Where the locks are stored

SiteControlSessions (default /tmp):

Where the session data is stored

SiteControlUsermap (default none):

Where the usernames are mapped to session files. Required if you want multiple session detection. If unset a single userid can be used to log in multiple times simultaneously.

SiteControlUserFactory (default: Apache2::SiteControl::UserFactory)

An implementation like this module.

UserObjectSaveOtherCredentials (default: 0)

Indicates that other form data from the login screen (credential_2, credential_3, etc.) should be saved in the session data. The keys will be credential_2, etc. name of the user factory to use when making user objects. These are useful if your web application has other login choices (i.e. service, database, etc.) that you need to know about at login.

UserObjectSavePassword (default 0)

Indicates that the password should be saved in the local session data, so that it is available to other parts of the web app (and not just the auth system). This might be necessary if you are logging the user in and out of services on the back end (like in webmail and database apps).

UserObjectPasswordCipher (default CAST5)

The CBC cipher used for encrypting the user passwords in the session files (See Crypt::CBC for info on allowed ciphers...this value is passed directly to Crypt::CBC->new). If you are saving user passwords, they will be encrypted when stored in the apache session files. This gives a little bit of added security, and makes the apache config the only sensitive file (since that is where you configure the key itself) instead of every random session file that is laying around on disk.

There is a global variable in this package called $encryption_key, which will be used if this variable is not set. The suggested method is to set the encryption key during server startup using a random value (i.e. from /dev/random), so that all server forks will inherit the value.

UserObjectPasswordKey

The key to use for encryption of the passwords in the session files. See UserObjectPasswordCipher above.

AUTHOR

This module was written by Tony Kay, <[email protected]>.

COPYRIGHT AND LICENSE

Apache2::SiteControl is covered by the GPL.