view release on metacpan or  search on metacpan

lib/CGI/Authen/Simple.pm  view on Meta::CPAN

package CGI::Authen::Simple;

use strict;
use CGI;
use CGI::Cookie;
use Template;

=head1 NAME

CGI::Authen::Simple - Simple cookie-driven unsessioned form-based authentication

=head1 SYNOPSIS

 use CGI::Authen::Simple;

 my $auth = CGI::Authen::Simple->new();
 $auth->logged_in() || $auth->auth();

 # do stuff here

 # if you need it, you can access the user's credentials like so:
 my $username = $auth->{'profile'}->{'username'};

 # assume your account table had other attributes, like full_name char(64)
 my $fullname = $auth->{'profile'}->{'full_name'};

 # their password is never returned in plain text
 print $auth->{'profile'}->{'password'};
 # prints the MySQL hash of their password

=head1 DESCRIPTION

This module provides extremely simple forms-based authentication for web
applications. It has reasonable defaults set, and if your database conforms
to those defaults, you can instantiate a new object with no parameters, and
it will handle all the authentication and cookie settings for you.

=head1 METHODS

=cut

our $VERSION = '1.0';

=over

=item B<new()>

Returns a new CGI::Authen::Simple object. Accepts a single hashref as a parameter. The hashref contains config information:

=over

=item *
dbh - a DBI database handle to the database containing the account information. REQUIRED.

=item *
EXIT_ON_DISPLAY - if auth() is required to draw a page, should it exit()? Defaults to true.
If you are running mod_perl, I recommend you set this to 0, and wrap your auth-protected code
in a logged_in() check. See the documentation for auth().

=item *
USERID - the database column containing a unique account ID. The ID can be anything, however I
recommend a unique integer ID.

=item *
USERNAME - the column corresponding to their username. Usernames do not have to be unique, however
username/password pairs must be unique or you will get potentially unexpected results.

=item *
PASSWORD - the column in the database corresponding to the user's password.

=item *
HASH_FUNC - one of ('none','old_password','password','md5','sha','sha1').
These correspond to their named hashing functions in mysql. If your passwords are stored as
plaintext in the database, use none. Encrypted passwords are not currently supported.
Default: none

=item *
TABLE - the name of the table that contains the above three columns.

=item *
HTML_TITLE - the title for the page. Defaults to lc($ENV{'HTTP_HOST'}) . ' : please log in';