|
CGI::Auth - Simple session-based password authentication for CGI applications |
CGI::Auth - Simple session-based password authentication for CGI applications
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;
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.
Before anything can be done with CGI::Auth, an object must be created:
my $auth = new CGI::Auth( \%options );
newThe 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):
-cgiThis 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
to CGI::Auth, rather than both your script and Auth having to create
separate objects.
Note: As of version 2.4.3, CGI::Auth can now be used with CGI::Simple.
This hasn't been tested thoroughly yet, so use caution if you decide to do so.
-admin-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).
-authdirDirectory 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.
-sessdirDirectory 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.
-userfileFile 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-loginheader and -loginfooter if present)
Template for use with HTML::Template. The template can be given in one of
three ways:
HTML::Template object reference,
HTML::Template->new, or
-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.
A sample template file (login.html) is included in the extra subdirectory of
this package.
For a list of what should be included in the template, see Template Variables and Template Loops below.
-logintmplpathList 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 to HTML::Template->new directly.
-loginheaderHeader for login screen.
NOTE: -loginheader and -loginfooter are ignored if -logintmpl is
provided.
-loginfooterFooter for login screen.
NOTE: -loginheader and -loginfooter are ignored if -logintmpl is
provided.
-formaction-admin given)
URL of calling script. This is used by the login screen as the form's ``action'' property.
-authfieldsArray 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},
],
-timeoutThe timeout value in seconds after which an unused session file will expire.
-cgipruneWhether to allow calls to prune in CGI mode. If your CGI scripts need (or want) to delete old session files, this will have to be set to true. I can't think of any particular reason not to allow this, but it isn't allowed by default.
-md5pwdWhether to use an MD5 hash for hidden fields in the user data file. If false,
the Perl built-in crypt is used twice (via the DoubleCrypt sub below), so
hidden fields are restricted to 16 characters. If true, MD5 hashes are used,
and there is no length restriction for hidden fields.
If this option is changed, the user data file will have to be recreated using MD5 hashes, so it's best to make this decision at the beginning.
Using MD5 hashes will result in a slight performance hit when logging in. This will probably not be noticeable at all.
These template variables are required. The names of these are case-insensitive by default. See the HTML::Template manpage for more information.
MessageNOTE: This variable might be left blank when the form is created. So don't depend on it having a value.
Form_ActionButton_Name
<input type=submit name="<TMPL_VAR Name=Button_Name>" value="Submit">
The 'value' property of the submit button can be anything.
These loops must exist in the template. The names of these are case-insensitive by default. See the HTML::Template manpage for more information.
Auth_FieldsDisplay_NameInput_NameInput_Type
There are two groups of public methods in CGI::Auth. The CGI-mode methods are called from CGI scripts for the purposes of authenticating a user and managing sessions. The command-line methods are used only in command-line scripts, such as the authman.pl sample userbase manager script. The latter methods will abort execution if they are run in a CGI environment.
These are used for creating a CGI::Auth object.
newnew.
initnew. This should not be called
directly.
These methods are called from CGI scripts.
checkendsessionReturns 1 if session file deleted successfully, 0 if an error occurred ($! will contain the error), or -1 if the session file did not exist.
setdatadata-sessdir directory.
sfparam_namesfparam_valueformfield (deprecated)urlfield and formfield is discouraged in favour
of sfparam_name and sfparam_value because the latter provide much more
flexibility. For example, they allow you to create elements that are
XHTML-compliant, whereas the data returned from formfield is only valid for
HTML 4.
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">'
urlfieldurlfield and formfield is discouraged in favour
of sfparam_name and sfparam_value because the latter provide much more
flexibility. For example, they allow you to create elements that are
XHTML-compliant, whereas the data returned from formfield is only valid for
HTML 4.
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'.
These methods are used for user maintenance. They cannot be run under a CGI environment. Use them only in command-line programs as an administrator (or as a user with write access to the user data file).
adduser
$auth->adduser('KAM', 'smokey'); # Branchname, Password
listusersviewuserdeluserprune
There are also some private methods. Use of them by unauthorized dirrty scripts is a federal offence in some jurisdictions, carrying a maximum sentence of yearly noogies by yours-truly. This may or may not be legal in your country.
GetUserDataPrintLoginFormHTML::Template or a header and footer.
This is called by check when the user is not authenticated.
This method hands off either to PLF_template or to PLF_headerfooter.
PLF_templatePLF_headerfooterFormFieldsFor any single-valued parameters, it creates a hidden <input> control,
and for any multi-valued parameters, it creates a hidden (i.e.,
style="display: none") <select> control with all of its values.
CreateSessionFileOpenSessionFileThe return value is one of three things:
Feel free to use and abuse these. They just do dirty little jobs.
DenyCGIDoubleCryptMD5CryptThis is used instead of DoubleCrypt if the -md5pwd option is set.
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.
It would be adequate to use HTTPS only for the login process, and avoid the overhead of encryption during the rest of the session. But I expect that this would require modification of this module.
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.
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 (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.
|
CGI::Auth - Simple session-based password authentication for CGI applications |