NAME
CGI::Session::Auth - Authenticated sessions for CGI scripts
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 });
# check if visitor has already logged in
if ($auth->loggedIn) {
showSecretPage;
}
else {
showLoginPage;
}DESCRIPTION
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 flat file and DBI database backends.
CGI::Session::Auth offers an alternative approach 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.
WARNING
This software is still in alpha status. It's meant only to show its basic functionality. Features and interface are subject to change. If you want to use CGI::Session::Auth in a production environment, please wait for version 1.0.
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 object.
- Session
-
A reference to an CGI::Session object.
Additionally, the following optional parameters are possible:
- DoIPAuth
-
Try to authenticate the visitor by his IP address. (Default: 0)
- LoginVarPrefix
-
A string the names of the login form fields begin with. (Default. 'log_')
init()
This method initializes the object and has to be called after object creation. It fetches session information to determine the authentication status of the current visitor. init further checks if form variables from a proceeding login form have been set and eventually performs a login attempt. If authentication succeeded neither by session data nor login information, and the parameter DoIPAuth is set to a true value, init tries to authenticate the visitor by his IP address.
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()
This method returns a boolean value representing the current visitors authentication status.
logout()
This method discards the current visitors authentication status.
checkUsername($username)
By this method can be checked if a certain user is logged in.
checkGroup($groupname)
By this method can be checked if the current user is a member of a certain user group.
profile($key [, $value])
This accessor method returns the user profile field identified by $key. If $value is given, it will be stored in the respective profile field first.
SEE ALSO
For further information (mailing lists, FAQ, etc.), see the module web site: http://geewiz.teamlinux.de/projects/perl/cgi-session-auth
AUTHOR
Jochen Lillich, <jl@teamlinux.de>
COPYRIGHT AND LICENSE
Copyright (c) 2003 by Jochen Lillich
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.