NAME

CGI::Session::Auth - Authenticated sessions for CGI scripts

ABSTRACT

CGI::Session::Auth is a Perl class that provides the necessary functions for authentication in CGI scripts. It uses CGI::Session for session management and supports several backends for user and group data storage.

SYNOPSIS

  use CGI;
  use CGI::Session;
  use CGI::Session::Auth;

  # CGI object for headers, cookies, etc.
  my $cgi = new CGI;

  # CGI::Session object for session handling
  my $session = new CGI::Session(undef, $cgi, {Directory=>'/tmp'});

  # CGI::Session::Auth object for authentication
  my $auth = new CGI::Session::Auth({ CGI => $cgi, Session => $session });
  $auth->authenticate();
  
  # check if visitor has already logged in
  if ($auth->loggedIn) {
      showSecretPage;
  }
  else {
      showLoginPage;
  }

DESCRIPTION

CGI::Session::Auth offers an alternative to HTTP authentication. Its goal is to integrate the authentication process into the web application as seamless as possible while keeping the programming interface simple.

Users can authenticate themselves by entering their user name and password into a login form. This is the most common way of authenticating a web site visitor.

Alternatively, a user can automatically be authenticated by his IP address. This is useful when authorized users can't be bothered to log in manually but can be identified by a range of fixed IP addresses.

CGI::Session::Auth manages a profile for every user account, containing his user name, his password and his user id. The user profile may contain additional fields for arbitrary data.

IMPORTANT: The class CGI::Session::Auth itself is only an abstract base class with no real storage backend (only the user 'guest' with password 'guest' may log in). You have to derive a child class that implements its own _login() method where the actual authentication takes place.

METHODS

new(\%parameters)

This is the class constructor. The hash referenced by \%parameters must contain the following key/value pairs:

CGI

A reference to an CGI or CGI::Simple object.

Session

A reference to an CGI::Session object.

Additionally, the following optional parameters are possible:

IPAuth

Try to authenticate the visitor by his IP address. (Default: 0)

LoginVarPrefix

By default, CGI::Session::Auth expects the username and password of the visitor to be passed in the form variables 'log_username' and 'log_password'. To avoid conflicts, the prefix 'log_' can be altered by this parameter.

Log

Set to 1 to enable logging. CGI::Session::Auth expects an initialized Log::Log4perl module and gets its logger object calling Log::Log4perl->get_logger('CGI::Session::Auth').

authenticate()

This method does the actual authentication. It fetches session information to determine the authentication status of the current visitor and further checks if form variables from a proceeding login form have been set and eventually performs a login attempt.

This login attempt is done by calling the method _login() (see below).

If authentication succeeded neither by session data nor login information, and the parameter IPAuth is set to a true value, it tries to authenticate the visitor by his IP address.

_login()

This virtual method performs the actual login attempt by comparing the login form data the visitor sent with some local user database. The _login method of the base class CGI::Session::Auth only knows the user 'guest' with password 'guest'.

To access a real user database, you have to use a subclass that modifies the _login method appropriately. See the modules in the Auth/ subdirectory.

sessionCookie()

For the session to be persistent across page requests, its session ID has to be stored in a cookie. This method returns the correct cookie (as generated by CGI::cookie()), but it remains the duty of the CGI application to send it.

loggedIn()

Returns a boolean value representing the current visitors authentication status.

logout()

Discards the current visitors authentication status.

hasUsername($username)

Checks if a certain user is logged in.

isGroupMember($groupname)

Checks if the current user is a member of a certain user group.

profile($key [, $value])

Returns the user profile field identified by $key. If $value is given, it will be stored in the respective profile field first.

_encpw($password)

Returns a cryptographic hash version of the password argument. If you want to store passwords in encrypted form for security reasons, use this function when you store the password and when you compare the stored password with the input submitted by the user.

SUPPORT

For further information regarding this module, please visit the project website at https://launchpad.net/perl-cgi-session-auth.

BUGS

Please report all bugs via the issue tracking on the project website.

Assistance in the development of this modules is encouraged and greatly appreciated.

SEE ALSO

CGI::Session CGI::Application::Plugin::Session

AUTHOR

Jochen Lillich, <geewiz@cpan.org>

CONTRIBUTORS

These people have helped in the development of this module:

Cees Hek =item Daniel Brunkhorst =item Gregory Ramsperger =item Jess Robinson =item Simon Rees =item Roger Horne =item Oliver Paukstadt =item Jonathon Wyza =item Hugh Esco

COPYRIGHT AND LICENSE

Copyright (c) 2003-2010 by Jochen Lillich

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

cpanm CGI::Session::Auth

perl -MCPAN -e shell
install CGI::Session::Auth