View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Vincent E. Veselosky > CGI-Builder-Auth-0.06 > CGI::Builder::Auth



Annotate this POD


New  2
Open  0
View/Report Bugs
Module Version: 0.06   Source  


CGI::Builder::Auth - Add user authentication to the CGI::Builder Framework


  # Recommended: Include CGI::Builder::Session BEFORE CGI::Builder::Auth
  use CGI::Builder qw/ CGI::Builder::Session CGI::Builder::Auth /;
  # 'protected' page available only to authenticated (logged in) users
  sub SH_protected {
    my ($app) = @_;
    $app->auth->require_valid_user or return $app->switch_to('login');
  # 'admin' page available only to members of 'administrators' group
  sub SH_admin {
    my ($app) = @_;
      or return $app->switch_to('forbidden');
  # 'private' page available only to select users
  sub SH_private {
    my ($app) = @_;
    $app->auth->require_user(qw/ bob carol ted alice /) 
      or return $app->switch_to('forbidden');


Adds user authentication and authorization to the CGI::Builder Framework.


For those who prefer to read code rather than documentation, see the examples directory in the distribution. The example is well commented and exercises the API fully.

CGI::Builder::Auth adds an authentication system to the CBF. An object stored in the auth property keeps track of the current user, and provides methods for performing common tests to determine that user's status in the current context. It talks to the user database through the configured User_factory and Group_factory classes.

The module includes default User_factory and Group_factory classes which store their database in plain text files. The files should be compatible with Apache password files generated by the htpasswd utility, but this feature is untested as of release 0.06. The default classes also have preliminary support for storing user/group information in a SQL database. If you are interested in using this feature, please see the example file in the distribution examples/ (Many thanks to Rusty Phillips for this code.)

A developer may provide custom User_factory and Group_factory classes so that the CBF can access a database of his own design. These classes must conform to the API for the User Class and Group Class respectively. The example shows one possible implementation of alternative User_factroy and Group_factory classes (implemented in the CDBI_*.pm files). Please look in the examples directory of this distribution and read "Custom User and Group Classes" below.

WARNING: The default User and Group factories provided with this module are not thread-safe. You may have issues using them on a multi-threaded web server such as the Windows version of Apache or any version of Apache2. (Apache 1.x on Linux should be fine). If you intend to deploy on a multi-threaded platform, you should design your own User and Group factories. Also, even on supported platforms you may run into file-locking issues under heavy loads, because only one web server process may have the database open at a time. Developers are encouraged to use a SQL database to avoid these issues.

This module can use CGI::Builder::Session to track the authentication context from one request to the next, so a user can login once and remain logged in until her session terminates. This happens automatically when the module detects that you are using sessions. You don't need to do anything special. The module will function without sessions, but only within the current request. Realistically, for any real web application you will want to use the session integration.

Any session keys set by this module will begin with 'CBA_'. Do not attempt to access these keys directly, they are intended for internal use only.


This module adds the following methods to the CBF.


The authentication context object. Its API is documented separately in CGI::Builder::Auth::Context.


A group accessor (like the param property). Supported configuration options:


A group accessor (like the param property). Supported configuration options:


A group accessor (like the param property). Supported configuration options:


If make test works for you but your application does not work as you expect, please check the following things before sending email to the mailing list for support.

Custom User and Group Classes ^

WARNING: This is an experimental feature.

It may happen that you have your user information stored in a relational database, and you would like to access additional columns in the user table, or perform special queries on related tables. This module can work together with custom classes that you create to implement this additional functionality.

Your custom user class must implement the interface described in CGI::Builder::Auth::User, and your custom group class must implement the interface described in CGI::Builder::Auth::Group. They may of course have many other properties and methods, but all the ones described in these resources must be supported.

However, your custom classes should not inherit from these default classes. The default classes are designed to work specifically with the text file format and do not contain any reusable methods for SQL databases.

Custom classes come as a matched set. If you use a custom user class, you must also use a custom group class.

To instruct the auth object to use your custom classes, set the User_factory and Group_factory auth_config parameters to the appropriate class names in your OH_init. The configurator will attempt to require these modules at the time you set the values. If they cannot be found, the auth_config method will croak.

    User_factory  => 'My::Personal::User::Class',
    Group_factory => 'My::Personal::Group::Class',
  ); # croaks if these classes cannot be 'required'




Support for this module and all the modules of the CBF is via the mailing list. The list is used for general support on the use of the CBF, announcements, bug reports, patches, suggestions for improvements or new features. The API to the CBF is stable, but if you use the CBF in a production environment, it's probably a good idea to keep a watch on the list.

You can join the CBF mailing list at this url:


Vincent Veselosky


Large portions of the code are borrowed from the HTTPD-User-Manage collection by Doug MacEachern and Lincoln Stein.

Rusty Phillips contributed many fixes to get DBI support working and provided the example application.


Copyright 2004 by Vincent Veselosky

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: