The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-Auth-Basic-1.23
River stage one • 1 direct dependent • 1 total dependent
++
/ CGI::Auth::Basic

NAME

CGI::Auth::Basic - Basic CGI authentication interface.

SYNOPSIS

   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

DESCRIPTION

This document describes version 1.23 of CGI::Auth::Basic released on 21 January 2015.

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.

Public Methods

new

Parameters

cgi_object

The module needs a CGI object to work. It is used for:

  • Fetching parameters resulted from a POST or GET request (eg: for login and logoff respectively).

  • Implementing/fetching/deleting password cookies.

  • Getting the name and url of your program.

  • Printing HTTP Headers for the module' s GUI.

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.

ihacloaiwtui

See cgi_object.

password

You need a password to validate the user. If you set this parameter, it'll be used as the encoded password string. Note that; it MUST be a crypt()ed string. You must encode it with Perl's crypt() function. You can not login with a plain password string.

file

If you can't provide a password to the module, set this parameter's value to a valid file path. It'll be your password file and will be updated (change your password) if necessary. The module will use this file to store/fetch password string. If the file does not exist, the module will exit with an error. If the file is empty and you set the 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.

setup_pfile

If your "password file" is empty and you set this parameter to a true value, then the module will ask you to enter a password for the first time and will update the password file. Note that: someone that runs the program will set the default value. Also, if you forgot your password, set this parameter. You can replace your password file with an empty file and run the program to set the password. You can turn off this option after the password is set.

The name of the cookie and the name of the password area name in the login form. Default value is password.

http_charset

If you are using custom templates and changed the interface language, set this to a correct value. Defaut is ISO-8859-1 (english).

logoff_param

Default value is 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.

When the user sends the correct password via the login form, the module will send a password cookie to the user. Set this parameter if you want to alter the module's setting. Default is an empty string (means; cookie is a session cookie, it'll be deleted as soon as the user closes all browser windows)

changep_param

Form area name for password change. Same as logoff_param. Cosmetic option.

chmod_value

Password file's chmod value. Default value is 0777. Change this value if you get file open/write errors or want to use different level of permission. Takes octal numbers like 0777.

use_flock

Default value is 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

If the area you want to protect is accessible with some parameters, use this option to set the hidden form areas. Passed as an array of array, AoA:

   hidden => [
               [action => 'private'],
               [do     => 'this'],
   ],

They'll also be used in the refresh pages and links as a query string.

check_user

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.

set_template

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.

set_title

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.

exit_code

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;
   });

Class Methods

fatal_header

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.

Password Regex

Passwords are checked with $CGI::Auth::Basic::RE class variable.

ERROR HANDLING

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().

EXAMPLES

See the 'eg' directory in the distribution. Download the distro from CPAN, if you don't have it.

SEE ALSO

CGI and CGI::Auth.

AUTHOR

Burak Gursoy <burak@cpan.org>.

COPYRIGHT

Copyright 2004 - 2015 Burak Gursoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16.2 or, at your option, any later version of Perl 5 you may have available.