NAME

Apache::AuthenDBI - Authentication via Perl's DBI

SYNOPSIS

# Configuration in httpd.conf or srm.conf:

PerlModule Apache::AuthenDBI

# Authentication in .htaccess:

AuthName DBI
AuthType Basic

#authenticate via DBI
PerlAuthenHandler Apache::AuthenDBI

PerlSetVar Auth_DBI_data_source   dbi:driver:dsn
PerlSetVar Auth_DBI_username      db_username
PerlSetVar Auth_DBI_password      db_password
#DBI->connect($data_source, $username, $password)

PerlSetVar Auth_DBI_pwd_table     users
PerlSetVar Auth_DBI_uid_field     username
PerlSetVar Auth_DBI_pwd_field     password
#SELECT pwd_field FROM pwd_table WHERE uid_field=$user

require valid-user

The AuthType is limited to Basic. The require directive is limited to 'valid-user'. For 'user user_1 user_2 ...' and for group support see AuthzDBI.pm.

DESCRIPTION

This module allows authentication against a database using Perl's DBI. For supported DBI drivers see:

http://www.symbolstone.org/technology/perl/DBI/

For the given username the password is looked up in the cache. If it is not found in the cache, it is requested from the database.

If the username does not exist and the authoritative directive is set to 'on', the request is rejected. If the authoritative directive is set to 'off', the control is passed on to next module in line.

If the password for the given username is empty and the nopasswd directive is set to 'off', the request is rejected. If the nopasswd directive is set to 'on', any password is accepted.

Finally the passwords (multiple passwords per userid are allowed) retrieved from the database are compared to the password given. If the encrypted directive is set to 'on', the given password is encrypted using perl's crypt() function before comparison. If the encrypted directive is set to 'off' the plain-text passwords are compared.

If this comparison fails the request is rejected, otherwise the request is accepted.

The SQL-select used for retrieving the passwords is as follows:

SELECT pwd_field FROM pwd_table WHERE uid_field = user

If a pwd_whereclause exists, it is appended to the SQL-select.

At the end a CleanupHandler is initialized, which skips through the password cache and deletes all outdated entries. This is done after sending the response, hence without slowing down response time to the client. The default cache_time is set to 0, which disables the cache, because any user will be deleted immediately from the cache.

This module supports in addition a simple kind of logging mechanism. Whenever the handler is called and a log_string is configured, the log_field will be updated with the log_string. As log_string - depending upon the database - macros like TODAY can be used.

The SQL-select used for the logging mechanism is as follows:

UPDATE pwd_table SET log_field = log_string WHERE uid_field = user

LIST OF TOKENS

• Auth_DBI_data_source

  The data_source value should begin with 'dbi:driver_name:'. This value (with the 'dbi:...:' prefix removed) is passed to the database driver for processing during connect.

• Auth_DBI_username

  The username argument is passed to the database driver for processing during connect.

• Auth_DBI_password

  The password argument is passed to the database driver for processing during connect.

• Auth_DBI_pwd_table

  Contains at least the fields with the username and the (encrypted) password. The username should be unique.

• Auth_DBI_uid_field

  Field name containing the username in the Auth_DBI_pwd_table.

• Auth_DBI_pwd_field

  Field name containing the password in the Auth_DBI_pwd_table.

• Auth_DBI_pwd_whereclause

  Use this option for specifying more constraints to the SQL-select.

• Auth_DBI_log_field

  Field name containing the log string in the Auth_DBI_pwd_table.

• Auth_DBI_log_string

  String to update the Auth_DBI_log_field in the Auth_DBI_pwd_table. Depending upon the database this can be a macro like 'TODAY'.

• Auth_DBI_authoritative < on / off>

  Default is 'on'. When set 'on', there is no fall-through to other authentication methods if the authentication check fails. When this directive is set to 'off', control is passed on to any other authentication modules. Be sure you know what you are doing when you decide to switch it off.

• Auth_DBI_nopasswd < on / off >

  Default is 'off'. When set 'on' the password comparison is skipped if the Auth_DBI_pwd_field is empty, i.e. allow any password. This is 'off' by default to ensure that an empty Auth_DBI_pwd_field does not allow people to log in with a random password. Be sure you know what you are doing when you decide to switch it on.

• Auth_DBI_encrypted < on / off >

  Default is 'on'. When set 'on', the value in the Auth_DBI_pwd_field is assumed to be crypted using perl's crypt() function and the incoming password is crypted before comparison. When this directive is set to 'off', the comparison is done directly with the plain-text entered password.

• Auth_DBI_uidcasesensitive < on / off >

  Default is 'on'. When set 'off', the entered userid is converted to lower case. Also the userid in the password select-statement is converted to lower case.

• Auth_DBI_pwdcasesensitive < on / off >

  Default is 'on'. When set 'off', the entered password is converted to lower case.

• Auth_DBI_cache_time

  Default is 0 = off. When set to any value n > 0, the passwords of all users will be cached for n seconds. After finishing the request, a special handler skips through the cache and deletes all outdated entries (entries, which are older than the cache_time).

• Auth_DBI_placeholder < on / off > Default is 'off'. When set 'on', the select statement is prepared using a placeholder for the username. This may result in improved performance for databases supporting this method.

CONFIGURATION

The module should be loaded upon startup of the Apache daemon. Note that this needs mod_perl-1.08 or higher, apache_1.3.0 or higher and that mod_perl needs to be configured with

PERL_AUTHEN=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1. 

Add the following line to your httpd.conf or srm.conf:

PerlModule Apache::AuthenDBI

PREREQUISITES

For Apache::AuthenDBI you need to enable the appropriate call-back hooks when making mod_perl:

perl Makefile.PL PERL_AUTHEN=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1. 

SECURITY

In some cases it is more secure not to put the username and the password in the .htaccess file. The following example shows a solution to this problem:

httpd.conf:

<Perl>
my($uid,$pwd) = My::dbi_pwd_fetch();
$Location{'/foo/bar'}->{PerlSetVar} = [
    [ Auth_DBI_username  => $uid ],
    [ Auth_DBI_password  => $pwd ],
];
</Perl>

SEE ALSO

Apache, mod_perl, DBI

AUTHORS

• mod_perl by Doug MacEachern <dougm@telebusiness.co.nz>

• DBI by Tim Bunce <Tim.Bunce@ig.co.uk>

• Apache::AuthenDBI by Edmund Mergl <E.Mergl@bawue.de>

COPYRIGHT

The Apache::AuthenDBI module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Apache::DBI

perl -MCPAN -e shell
install Apache::DBI