NAME

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

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

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.

METHODS

new()

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

• dbh - a DBI database handle to the database containing the account information. REQUIRED.

• 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().

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

• 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.

• PASSWORD - the column in the database corresponding to the user's password.

• 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

• TABLE - the name of the table that contains the above three columns.

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

• HTML_HEADER - HTML that will be printed inside a header block for the page. Same default as HTML_TITLE

• HTML_FOOTER - HTML that will be printed inside a footer block for the page. Defaults to Login handled by <a href="http://search.cpan.org/~opiate/">CGI::Authen::Simple</a> version $VERSION

• ext_auth - code reference. The function called by this reference can do anything it has access to do, and is expected to return a username and password to be authenticated. This is useful for example, if you wanted to log people in via SSL certificates or UserAgent settings. For example, you could check their UserAgent in the function, and derive a username and password from it -- or you could find out what client certificate someone has connected using on an SSL-enabled webserver, and derive a username and password from that.

logged_in()

Uses cookies to determine if a user is logged in. Returns true if user is logged in. If a row is retrieved from the DB, then all the columns making up the row for that user in the accounts table will be pulled and stored as the user's profile, which is accessible as a hashref via $auth->{'profile'}.

auth()

Authenticates a user if data was posted containing a username and password pair. If authentication was unsuccessful or they did not pass a username/password pair, they are displayed a login screen. If we retrieve a row (valid username and password), then grab the rest of the columns from that table, and store them internally as the user's profile.

Note: If a login screen is displayed, the value of EXIT_ON_DISPLAY is checked. If EXIT_ON_DISPLAY is true (1), then the function will exit. This is the default behaviour. As far as I am aware, this is highly undesirable in mod_perl applications, so please be sure you've taken that into consideration. If EXIT_ON_DISPLAY is set to false, the function will not exit, and control will be returned to the calling script. In this case, please wrap your code in a surrounding:

 if($auth->logged_in())
 {
     # do stuff here
 }

code block, or else you will be displaying not only the auth screen, but anything that would be displayed by your code.

TODO

 - template / CSS overrides
 - needs to work with any DB software (since it just takes a DBH, maybe use SQL::Abstract to generate a
   cross DB compatible query.

SEE ALSO

CGI::Cookie, CGI, Template

AUTHOR

Shane Allen <opiate@gmail.com>

ACKNOWLEDGEMENTS

• This core functionality of this module was developed during my employ at HRsmart, Inc. http://www.hrsmart.com and its public release was graciously approved.

COPYRIGHT

Copyright 2005, Shane Allen. All rights reserved.

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