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

 <Limit GET>
 require valid-user
 </Limit>

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.

DESCRIPTION

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

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.

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_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.

CONFIGURATION

The module should be loaded upon startup of the Apache daemon. Add the following line to your httpd.conf or srm.conf:

 PerlModule Apache::AuthenDBI

PREREQUISITES

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

  perl Makefile.PL PERL_AUTHEN=1. 

SEE ALSO

Apache, mod_perl, DBI

AUTHORS

• 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>

COPYRIGHT

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