Apache::AuthenDBI - Authentication via Perl's DBI
# 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' and 'user user_1 user_2 ...'. For group support see AuthzDBI.pm.
This module allows authentication against a database using Perl's DBI. For supported DBI drivers see:
http://www.hermetica.com/technologia/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 password retrieved from the database is 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 password 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.
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
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.
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_casesensitive < on / off >
Default is 'on'. When set 'off', the entered userid and password is converted to lower case.
Auth_DBI_cache_time Default is 0 = off. When set to any value > 0, the passwords of all users will be cached. After finishing the request, a special handler skips through the cache and deletes all outdated entries (entries, which are older than the cache_time).
The module should be loaded upon startup of the Apache daemon. Note that this needs mod_perl-1.08 or higher, apache_1.3b6 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
For Apache::AuthenDBI you need to enable the appropriate call-back hooks when making mod_perl:
perl Makefile.PL DO_HTTPD=1 PERL_AUTHEN=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1.
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>
Apache, mod_perl, DBI
mod_perl by Doug MacEachern <dougm@osf.org>
DBI by Tim Bunce <Tim.Bunce@ig.co.uk>
Apache::AuthenDBI by Edmund Mergl <E.Mergl@bawue.de>
The Apache::AuthenDBI module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
4 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install Apache, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache
CPAN shell
perl -MCPAN -e shell install Apache
For more information on module installation, please visit the detailed CPAN module installation guide.