NAME

CGI::Session::Auth::DBI - Authenticated sessions for CGI scripts

SYNOPSIS

use CGI;
use CGI::Session;
use CGI::Session::Auth::DBI;

my $cgi = new CGI;
my $session = new CGI::Session(undef, $cgi, {Directory=>'/tmp'});
my $auth = new CGI::Session::Auth::DBI({
    CGI => $cgi,
    Session => $session,
    DSN => 'dbi:mysql:host=localhost,database=cgiauth',
});
$auth->authenticate();

if ($auth->loggedIn) {
    showSecretPage;
}
else {
    showLoginPage;
}

DESCRIPTION

CGI::Session::Auth::DBI is a subclass of CGI::Session::Auth. It uses a relational database for storing the authentication data, using the DBI module as database interface.

Database setup

Use your favourite database administration tool to create and populate the database:

CREATE TABLE auth_user ( userid CHAR(32) NOT NULL, username VARCHAR(30) NOT NULL, passwd VARCHAR(32) NOT NULL default '', PRIMARY KEY (userid), UNIQUE username (username) );

INSERT INTO auth_user VALUES ( '325684ec1b028eaf562dd484c5607a65', 'admin', 'qwe123' ); INSERT INTO auth_user VALUES ( 'ef19a80d627b5c48728d388c11900f3f', 'guest', 'guest' );

CREATE TABLE auth_group ( groupname VARCHAR(30) NOT NULL, userid CHAR(32) NOT NULL, PRIMARY KEY (groupname) );

CREATE TABLE auth_ip ( network char(15) NOT NULL, netmask char(15) NOT NULL, userid char(32) NOT NULL, PRIMARY KEY (network, netmask) );

INSERT INTO auth_ip VALUES ('127.0.0.1', '255.0.0.0', 'ef19a80d627b5c48728d388c11900f3f' );

Mandatory columns in auth_user are userid, username and passwd. All additional columns will also be stored and accessible as user profile fields.

userid is a 32-character string and can be generated randomly by

perl -MCGI::Session::Auth -e 'print CGI::Session::Auth::uniqueUserID("myname"), "\n";'

The auth_ip table is used for IP address based authentication. Every row combines a pair of network address and subnet mask (both in dotted quad notation) with a user ID. The userid column is used as a foreign key into the auth_user table.

Constructor parameters

Additional to the standard parameters used by the new constructor of all CGI::Session::Auth classes, CGI::Session::Auth::DBI understands the following parameters:

DBHandle: Active database handle. For an explanation, see the DBI documentation.

DSN: Data source name for the database connection. For an explanation, see the DBI documentation.

DBUser: Name of the user account used for the database connection. (Default: none)

DBPasswd: Password of the user account used for the database connection. (Default: none)

DBAttr: Optional attributes used for the database connection. (Default: none)

UserTable: Name of the table containing the user authentication data and profile. (Default: 'auth_user')

UserIDField: Name of the column for the user id key. (Default: 'userid')

UsernameField: Name of the column for the user name. (Default: 'username')

PasswordField: Name of the column for the user password. (Default: 'passwd')

GroupTable: Name of the table containing user group relations. For every user that belongs to a group, there is a record with the group name and the user's id. (Default: 'auth_group')

GroupField: Name of the column for the group name. (Default: 'groupname')

GroupUserIDField: Name of the column for the user id. (Default: 'userid')

IPTable: Name of the table containing the by-IP authentication data. (Default: 'auth_ip')

IPUserIDField: Name of the column for the user id. (Default: 'userid')

IPAddressField: Name of the column for the IP address. (Default: 'network')

IPNetMaskField Name of the column for the IP network mask. (Default: 'netmask')

SEE ALSO

CGI::Session::Auth

AUTHOR

Jochen Lillich, <geewiz@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2003-2010 by Jochen Lillich

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