NAME
    WWW::Authen::Simple - Cookie based session and authentication module
    using database backend. Also provides group based authorization.

SYNOPSIS
     use WWW::Authen::Simple;

     my $simple = WWW::Authen::Simple->new(
                    db => $DBI_handle,
                    cookie_domain => 'cookie_domain'
     );
     # Alternitively, any of the methods to set variables may also be
     # used directly in the constructor
     $simple->logout() if $cgi->param('logout');
     $simple->login( $cgi->param('login'), $cgi->param('pass') );
     if ($simple->logged_in()) {
        if ($simple->in_group('Admin','rw')) {
           &do_admin_page();
        } else {
           &do_something();
        }
     } else {
        print redirect('/login.pl');
     }

ABSTRACT
    WWW::Authen::Simple provides another way to do cookie based sessions and
    authentication. It's goal is to provide a very simple API to handle
    sessions and authentication.

    The database layout has been abstracted, so you should be able to fit
    this into whatever database layout you currently use, or use the
    provided default to base your application.

    NOTE: the database abstraction is configured by a hash. If changes to
    it's structure are needed, you currently have to rebuild the entire
    hash, and pass it in (ie. there is no API to make it easy to change
    yet).

REQUIRES
     DBI and an appropriate DBD driver for your database
     Digest::MD5 (standard perl module)
     CGI

    In most common situations, you'll also want to have:

     A web server (untested on windows, but it should work)
     cgi-bin or mod-perl access
     Perl: Perl 5.00503 or later must be installed on the web server.

INSTALLATION
    The module can be installed using the standard Perl procedure:

        perl Makefile.PL
        make
        make test
        make install    # you need to be root

    Windows users without a working "make" can get nmake from:

        ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe

METHODS
    "$simple = WWW::Authen::Simple->new();"
        This creates a new Simple object. Optionally, you can pass in a hash
        with configuration information. See the method descriptions for more
        detail on what they mean.

             cookie_domain => 'www.somedomain.com', # required
             db => $DBI_handle, # required
             expire_seconds => 3600, # optional. default 3600
             cleanup_seconds =>  43200, # optional. default 43200 
             debug => 0, # optional. default 0
             conf => $config_hash_ref, # optional. defaults hardcoded.

    "$simple->db( $DBIx_PDlib_object );"
        Required. Database Handle from DBIx::PDlib;

    "$simple->cookie_domain( 'www.some_domain.com' );"
        Required. The Domain your authenticating into. Needed to store the
        cookie info.

    "$simple->login( $login, $password );"
        If $login and $password are undef (not set / not passed in), it
        checks the users cookies for a valid ticket. Otherwise, checks the
        username/password against the database.

        Returns:

           (0,$login) : inactive account, user doesn't exist,
                        password doesn't match, or invalid ticket
           (1,$login,$uid) : login successful
           (-1,$login) : login expired
           (0,0) : no user/pass sent, no cookies exist.

    "$simple->logout();"
        Logs the current user out by nulling out their session ticket in the
        database.

    "$simple->logged_in();"
        Returns 1 if the user is logged in. Returns undef is login() was
        called, but the user failed authentication. Returns 0 (zero) if the
        login() hasn't been called yet.

    "$simple->uid();"
        Get the current session user id.

    "$simple->username();"
        Get the current session username.

    "$simple->groups();"
        Returns an array of all groups names and group id's the user belongs
        to.

    "$simple->in_group($group,$rw);"
        $group can be the group name, or the group id.

        $rw (optional) can be:

           1  : Read access for the group.
           2  : Write access for the group.
           3  : Both read and write access for the group.
           r  : Read access for the group.
           w  : Write access for the group.
           rw : Both read and write access for the group.

        If called without the $rw option, it returns the raw access bits
        (will be true if the user is in the group and has any level of
        access: read, write, or both).

        If called with the $rw option, returns true if the user is in the
        group, and has that level of access. Returns false otherwise.

    "$simple->debug( [0|1|2] );"
        Optional. Sets the debugging bit. 1 turns it on, 0 turns it off. 2
        will print out verbose messages to STDERR.

    "$simple->cleanup();"
        Cleans out the old sessions from the session database. Should be
        called once in a while from a cron script. The frequency of calls to
        this is up to you, and it's need depends on how heavy your usage is.
        If you never call cleanup(), it won't be the end of the world...
        things will keep working just fine.

    "$simple->cleanup_seconds($integer_seconds);"
        How old a session entry should be before it get's cleaned out.
        Defaults to 43200 seconds (12 hours).

    "$simple->conf($conf);"
        $conf is optional. Set's the config hash if it's passed in.

        Returns the config hash.

        Config hash is structured like so:

          $conf = {
            session_table   => {
                _table  => 'sessions',  # table name
                login   => 'username',  # username field
                address => 'address',   # remote address field
                ticket  => 'ticket',    # session ticket field
                point   => 'point',     # timestamp point field
                },
            user_table  => {
                _table  => 'Users',     # table name
                uid     => 'uid',       # user unique id field
                login   => 'login',     # username field
                passwd  => 'passwd',    # password field
                status  => 'disabled',  # status field
                # sub ref to determine if status value is active
                _active_status  => sub { return 1 if ($_[0] != 1); },
                # sub ref to determine if status value is disabled
                _disabled_status    => sub { return 1 if ($_[0] == 1); },
                },
            # group statement is used to get the groups. It should
            # fetch a groupname, groupid, and an accessbit.
            # If you don't want to use the accessbit field, just stick
            # the groupid field there as well.
            # %uid% will be replaced with a quoted uid value for the user.
            # here's an alternate statement, to give you some ideas:
            #   SELECT groupname, gid, gid FROM Users WHERE uid = %uid%
            group_statement => 'SELECT g.Name, ug.gid, ug.accessbit
                                FROM Groups g, UserGroups ug
                                WHERE ug.uid = %uid%',
            # subroutine ref used to encrypt password for db storage
            'crypt' => sub { return Digest::MD5::md5_base64($_[0]); }
            };

SEE ALSO
    "examples" subdirectory of this distribution.

    Averist.pm: http://www.nongnu.org/averist/ : A more flexable
    session/auth module.

    CGI::Session: http://search.cpan.org/dist/CGI-Session

    Apache::Session: http://search.cpan.org/dist/Apache-Session

    CGI::Session::Auth: http://search.cpan.org/dist/CGI-Session-Auth

TODO
    Tests need written.

    Session storage abstraction.

    Authentication method abstraction.

AUTHORS
    Josh I. Miller, <jmiller@purifieddata.net>

    Seth T. Jackson, <sjackson@purifieddata.net>

COPYRIGHT AND LICENSE
    Copyright 2003 by Seth Jackson

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.