|
CGI::Auth::Basic - Basic CGI authentication interface. |
CGI::Auth::Basic - Basic CGI authentication interface.
use CGI::Auth::Basic;
$auth = CGI::Auth::Basic->new(cgi_object => $cgi,
password => 'J2dmER4GGQfzA');
$auth = CGI::Auth::Basic->new(cgi_object => $cgi,
file => "path/to/password/file.txt");
$auth = CGI::Auth::Basic->new(cgi_object => 'AUTOLOAD_CGI',
password => 'J2dmER4GGQfzA',
cookie_id => 'passcookie',
cookie_timeout => '1h',
http_charset => 'ISO-8859-9',
logoff_param => 'logout');
if ($someone_wants_to_enter_my_secret_area) {
$auth->check_user;
}
or you can just say:
CGI::Auth::Basic->new(cgi_object=>CGI->new,file=>"./pass.txt")->check_user;
# J2dmER4GGQfzA == blah
This module adds a simple (may be a little complex if you use all features) user validation system on top of your program. If you have a basic utility that needs a password protection or some unfinished admin section and you don't want to waste your time with writing hundreds of lines of code to protect this area; this module can be useful.
Module's interface is really simple and you can only have a password area; no username, no other profile areas. This is not a member system afterall (or we can say that; this is a basic, single member system -- or call it a quick hack that does its job). Not designed for larger applications.
Parameters
CGI object to work. It is used for:
POST or GET request
(eg: for login and logoff respectively).
If you don't use/need a CGI object in your program, set the
parameter to AUTOLOAD_CGI:
$obj = CGI::Auth::Basic->new(cgi_object => 'AUTOLOAD_CGI' ...)
Then, CGI::Auth::Basic will load the CGI module itself and create
a CGI object, which you can not access (however, you can access
with the related object table -- but this'll be weird. Create a CGI
object yourself, if you need one and pass it to the module).
If you don't want to use the CGI class, then you have to
give the module a similar object which has these methods:
param, cookie, header and url. They have to work as
the same as CGI object's methods. If this object does not
match this requirement, your program may die or does not function
properly. Also pass ihacloaiwtui parameter with a true value
to new():
$obj = CGI::Auth::Basic->new(cgi_object => $my_other_object,
ihacloaiwtui => 1, ... )
This string is the short form of
i_have_another_cgi_like_object_and_i_want_to_use_it.
Yes, this parameter' s name is weird (and silly), but I
couldn't find a better one.
cgi_object.
crypt()
function. You can not login with a plain password string.
setup_pfile parameter to a true value, you'll be prompted to
enter a password for the first time.
You can not use password and file parameters together. You must
select one of them to use.
Note that: you must protect your password file(s). Put it above your web root if you can. Also, giving it a .cgi extension can be helpful; if a web server tries to execute it, you'll get a 500 ISE, not the source (you can get the source however; it depends on your server software, OS and configuration). You can also put it in a hard-to-guess named directory. But don't put it in your program directory.
Also note that: these are just suggestions and there is no guarantee that any of this will work for you. Just test and see the results.
ISO-8859-1 (english).
logoff. If the user is logged-in, you can show him/her
a logoff link (see logoff_link method). With the default value,
You'll get this link:
<your_program>?logoff=1
If you set it to logout, you'll get:
<your_program>?logout=1
Just a cosmetic option, but good for translation.
logoff_param. Cosmetic
option.
0777. Change this value
if you get file open/write errors or want to use different level of
permission. Takes octal numbers like 0777.
1 and flock() will be used on filehandles. You can
set this to zero to turn off flock for platforms that does not implement
flock (like Win9x).
hidden => [
[action => 'private'],
[do => 'this'],
],
They'll also be used in the refresh pages and links as a query string.
The main method. Just call it anywhere in your code. You do not have to pass any parameters. It'll check if the user knows the password, and until the user enters the real password, he/she will see the login screen and can not run any code below. For example you can password-protect an admin section like this.
Change the module GUI. Create custom templates. Available templates:
login_form, change_pass_form, screen, logoff_link.
$auth->set_template(login_form => qq~ ... ~, ...);
If you want to load the default templates on some part of
the program, pass delete_all parameter with a true value:
$auth->set_template(delete_all => 1);
This can be good for debugging and note that this will delete anything you've set before.
For examples, see the test directory in the distribution.
Create your custom page titles. You can need this if you
want to translate the interface. Available templates:
login_form, cookie_error, login_success, logged_off,
change_pass_form, password_created, password_changed,
error.
$auth->set_title(error => "An error occurred", ...)
If you want to load the default titles on some part of
the program, pass delete_all parameter with a true value
to set_template:
$auth->set_template(delete_all => 1);
For examples, see the test directory in the distribution.
In the templates, you can only use some pre-defined variables
(some are accesible only in one template). These variables are
enclosed by <? and ?> (eg: <?PROGRAM?>).
The variable's name is case-insensitive (you can write:
<?ProGrAm?>). Because this module does not use/subclass
any Template module; you can not use any template loops or such things
that most of the template modules' offer.
Returns the code that includes logoff and change password links if the user is logged-in, returns an empty string otherwise.
Sets the exit code. By default, CORE::exit() will be called. But you can change this behaviour by using this method. Accepts a subref:
$auth->exit_code(sub { Apache->exit });
You can also do some clean up before exiting:
$auth->exit_code(sub {
untie %session;
$dbh->disconnect;
exit;
});
Sets the HTTP Header for fatal(). Example:
CGI::Auth::Basic->fatal_header("Content-Type: text/html; charset=ISO-8859-9\n\n");
Call before creating the object.
Passwords are checked with $CGI::Auth::Basic::RE class variable.
Your script will die on any perl syntax error. But the API errors
are trapped by a private fatal error handler. If you do something
illegal with the methods like; wrong number of parameters, or calling an
undefined method, it'll be trapped by fatal handler. Currently, you
can not control the behaviour of this method (unless you subclass it),
but you can define it's HTTP Header; see fatal_header.
On any fatal error, it will print the error message and some usefull
information as a web page, then it will terminate the program. You can
set the exit code with exit_code method.
All error messages (including fatal) are accessible via the class variable
%CGI::Auth::Basic::ERROR. Dump this variable to see the keys and values.
If you want to change the error messages, do this before calling new().
See the 'eg' directory in the distribution. Download the distro from CPAN, if you don't have it.
If you are using perl 5.5.3 and older on Win32 platform (this issue
may not be limited with Win32 but I'm not sure), you may need to
install the Crypt::UnixCrypt manpage. The CORE::crypt() function is not
implemented on this version.
Contact the author if you find any.
the CGI manpage and the CGI::Auth manpage.
Burak Gürsoy, <burak&64;cpan.org>
Copyright 2004-2006 Burak Gürsoy. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.
|
CGI::Auth::Basic - Basic CGI authentication interface. |