view release on metacpan or  search on metacpan

lib/CGI/Builder/Auth.pm  view on Meta::CPAN

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

=over

=item * B<DB>

The complete path to your group database file. Default is C<./.htgroup>.  This
file must be writable by your web server! Insufficient file permission is the
most common support problem, so please check this before sending mail to the
list for support.
  
  $app->auth_group_config(DB => './.htgroup'');
  

=back

=head2 C<auth_config>

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

=over

=item * B<magic_string>

The C<magic_string> is used to verify the authentication token that is
retrieved from the session. It should be set to something unique for your
application. It I<must> be set before the first use of the C<auth> object,
and I<must not> be changed during the execution of your program.

=item * B<User_factory> (advanced)

This configuration parameter is for advanced users who wish to supply their own
custom class for user objects. See L<"Custom User and Group Classes"> below.

=item * B<Group_factory> (advanced)

This configuration parameter is for advanced users who wish to supply their own
custom class for group objects. See L<"Custom User and Group Classes"> below.

=back


=head1 TROUBLESHOOTING

If C<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.

=over

=item * Set DB in OH_init

Ensure you have set the DB configuration option for users and groups in your
code B<before> the first use of the C<auth> property.

=item * Set File Permissions!

Ensure that the DB files are B<writable> by your web server. On many systems
the web server runs as a special user, which might be called 'apache', 'www',
or 'nobody'. This user B<must> be able to read and write your DB files. You may
have to C<chmod 777 filename> to get this to work. THIS IS THE MOST COMMON
PROBLEM.

=item * Set Directory Permissions

Ensure that the DB files actually exist after running your program. Your web
server will need write access to the directory in order to create them. If it
cannot, you may have to create them manually using C<touch filename>, and then
set permissions appropriately.

=item * Configure Session First

Ensure that you have set the configuration options for CGI::Builder::Session in
your code B<before> the first use of the C<auth> property.

=back



=head1 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 I<must> implement the interface described in
L<CGI::Builder::Auth::User>, and your custom group class I<must> implement the
interface described in L<CGI::Builder::Auth::Group>. They may of course have
many other properties and methods, but all the ones described in these resources
I<must> be supported.

However, your custom classes should I<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 C<auth> object to use your custom classes, set the
C<User_factory> and C<Group_factory> auth_config parameters to the appropriate
class names in your OH_init. The configurator will attempt to C<require> these
modules at the time you set the values. If they cannot be found, the auth_config
method will C<croak>.

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


=head1 TO DO

=over

=item * Test Integration

Make the test suite actually test the CGI::Builder integration!