NAME

       Apache2::SiteControl::UserFactory - User factory/persistence

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.

SEE ALSO

       Apache2::SiteControl::User, Apache::SiteControl::PermissionManager,
       Apache2::SiteControl::Rule, Apache::SiteControl

AUTHOR

       This module was written by Tony Kay, <tkay@uoregon.edu>.

COPYRIGHT AND LICENSE

       Apache2::SiteControl is covered by the GPL.