NAME
CGI::Auth - Simple session-based password authentication for CGI applications
SYNOPSIS
require CGI::Auth;
my $auth = new CGI::Auth({
-authdir => 'auth',
-formaction => "myscript.pl",
-authfields => [
{id => 'user', display => 'User Name', hidden => 0, required => 1},
{id => 'pw', display => 'Password', hidden => 1, required => 1},
],
});
$auth->check;
DESCRIPTION
CGI::Auth
provides password authentication for web-based applications. It uses server-based session files which are referred to by a parameter in all links and forms inside the scripts guarded by CGI::Auth
.
At the beginning of each script, a CGI::Auth
object should be created and its check
method called. When this happens, check
checks for a 'session_file' CGI parameter. If that parameter exists and has a matching session file in the session directory, check
returns, and the rest of the script can execute.
If the session file parameter or the file itself doesn't exist, check
presents the user with a login form and exits the script. The login form will then be submitted to the same script (specified in -formaction
). When check
is called this time, it verifies the user's login information in the userfile, creates a session file and provides the session file parameter to the rest of the script.
CREATING AND CONFIGURING
Before anything can be done with CGI::Auth
, an object must be created:
my $auth = new CGI::Auth( \%options );
The new
method creates and configures a CGI::Auth
object using parameters that are passed via a hash reference that can/should contain the following items (optional ones are indicated):
-cgi
-
(optional)
This parameter provides
CGI::Auth
with a CGI object reference so that the extra overhead of creating another object can be avoided. If your script is going to use CGI.pm, it is most efficient to create the CGI object and pass it toCGI::Auth
, rather than both your script and Auth having to create separate objects. -admin
-
(optional if
-formaction
given)This parameter should be used by command-line utilities that perform administration of the user database. If Auth is given this parameter, it will only allow command-line execution (execution from CGI will be aborted).
-authdir
-
(required)
Directory where Auth will look for its files. In other words, if
-sessdir
,-userfile
,-logintmpl
,-loginheader
or-loginfooter
are scalars and do not begin with a slash (i.e., are not absolute paths), this directory will be prepended to them. -sessdir
-
(optional, default = 'sess')
Directory where Auth will store session files. These files should be pruned periodically (i.e., nightly or weekly) since a session file will remain here if a user does not log out.
-userfile
-
(optional, default = 'user.dat')
File containing definitions of users, including login information and any extra parameters. This file will be created, edited and read by
CGI::Auth
and its command-line administration tool. -logintmpl
-
(optional, excludes
-loginheader
and-loginfooter
if present)Template for use with
HTML::Template
. The template can be given in one of three ways:An
HTML::Template
object reference,A hash containing parameters for
HTML::Template->new
, orA filename (then
-logintmplpath
can be the path parameter).
The template must contain a form for the user to fill out, and it is recommended that the form not contain any elements with names beginning with 'auth_', since these are reserved for
CGI::Auth
fields.The template should include the following
HTML::Template
items. These are case-insensitive. See theHTML::Template
documentation for more information.Template Variables
Message
-
A message to the user, such as "Login failed", "Session expired", etc...
NOTE: This variable might be left blank when the form is created. So don't depend on it having a value.
Form_Action
-
The 'action' property of the form that submits the authentication information.
Button_Name
-
The 'name' property of the submit button on the form. The tag for the button should look something like this:
<input type=submit name="<TMPL_VAR Name=Button_Name>" value="Submit">
The 'value' property of the submit button can be anything.
Template Loops
Auth_Fields
-
Provides variables for each required Auth field. These are the fields which will be filled in by the user when logging in. The following variables are provided:
Display_Name
-
The display name of the field, e.g., "User Name" or "Password".
Input_Name
-
The 'name' property of the text input for the field.
Input_Type
-
The type, 'text' or 'password', of the input, depending on whether this field is hidden or not.
-logintmplpath
-
(optional, default = [])
List of search path(s) for
HTML::Template
files (the 'path' option). This is used only if-logintmpl
is a filename. Otherwise, the path option must be passed toHTML::Template->new
directly. -loginheader
-
(optional, default = 'login.head' or a simple default header)
Header for login screen.
NOTE:
-loginheader
and-loginfooter
are ignored if-logintmpl
is provided. -
(optional, default = 'login.foot' or a simple default footer)
Footer for login screen.
NOTE:
-loginheader
and-loginfooter
are ignored if-logintmpl
is provided. -formaction
-
(optional if
-admin
given)URL of calling script. This is used by the login screen as the form's "action" property.
-authfields
-
(required)
Array of hashes defining fields in user database. This requires at least one field, which must be 'required' and not 'hidden'. Any other fields can be used to authenticate the user or to contain information about the user such as groups, access levels, etc. Once a user has logged on, all of his fields are available through the
data
method. However, any fields that are marked 'hidden' will be crypted and not readable by the script.Each field in the
-authfields
anonymous array is a hash containing 4 keys:'id' ID of the field. This must be unique across all fields. 'display' Display string which is presented to the user. 'hidden' Flag (0 or 1) that determines whether this field is hidden on the login screen and encrypted in the user file. 'required' Flag (0 or 1) indicating whether this field must be given for authentication.
Here is an example of a simple username/password scheme, with one extra data parameter:
-authfields => [ {id => 'user', display => 'User Name', hidden => 0, required => 1}, {id => 'pw', display => 'Password', hidden => 1, required => 1}, {id => 'group', display => 'Group', hidden => 0, required => 0}, ],
-timeout
-
(optional, default = 60 * 15, 15 minutes)
The timeout value in seconds after which an unused session file will expire.
METHODS
check
-
Ensures authentication. If the session file is not present or has expired, a login form is presented to the user. A call to this method should occur in every script that must be secured.
data
-
Returns a given data field. The field's ID is passed as the parameter, and the data is returned. The special field 'sess_file' returns the name of the current session file in the
-sessdir
directory. endsession
-
Deletes a user's session file so that he must log in again to gain access.
urlfield
-
Returns the session file parameter as a field suitable for tacking onto the end of an URL (such as in a link), e.g.:
'auth_sessfile=DBEEL87CXV7H'.
formfield
-
Returns the session file parameter as a hidden input field suitable for inserting in a <FORM>, e.g.:
'<input type=hidden name="auth_sessfile" value="DBEEL87CXV7H">'
NOTE ON SECURITY
Any hidden fields such as passwords are sent over the network in clear text, so anyone with low-level access to the network (such as an ISP owner or a lucky/skilled hacker) could read the passwords and gain access to your application. CGI::Auth has no control over this since it is currently a server-side-only solution.
If your application must be fully secured, an encryption layer such as HTTPS should be used to encrypt the session so that passwords cannot be snooped by unauthorized individuals.
SEE ALSO
BUGS
CGI::Auth
doesn't use cookies, so it is left up to the script author to ensure that auth data (i.e., the session file) is passed around consistently through all links and entry forms.
AUTHOR
C. Chad Wallace, cmdrwalrus@canada.com
If you have any suggestions, comments or bug reports, please send them to me. I will be happy to hear them.
COPYRIGHT AND LICENCE
Copyright (c) 2001, 2002, 2003 C. Chad Wallace. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.