NAME

Apache::AuthDBI - Authentication and Authorization via Perl's DBI

SYNOPSIS

 # Configuration in httpd.conf or startup.pl:


 PerlModule Apache::AuthDBI


 # Authentication and Authorization in .htaccess:


 AuthName DBI
 AuthType Basic


 PerlAuthenHandler Apache::AuthDBI::authen
 PerlAuthzHandler  Apache::AuthDBI::authz


 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
 # authentication: SELECT pwd_field FROM pwd_table WHERE uid_field=$user
 PerlSetVar Auth_DBI_grp_field     groupname
 # authorization: SELECT grp_field FROM pwd_table WHERE uid_field=$user


 require valid-user
 require user   user_1  user_2 ...
 require group group_1 group_2 ...

The AuthType is limited to Basic. You may use one or more valid require lines. For a single require line with the requirement 'valid-user' or with the requirements 'user user_1 user_2 ...' it is sufficient to use only the authentication handler.

DESCRIPTION

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

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

Authentication:

For the given username the password is looked up in the cache. If the cache is not configured or if the user is not found in the cache, or if the given password does not match the cached password, 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 from the database 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) are retrieved from the database. The result is put into the environment variable REMOTE_PASSWORDS. Then it 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 and the password is put into the environment variable REMOTE_PASSWORD.

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.

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

Authorization:

When the authorization handler is called, the authentication has already been done. This means, that the given username/password has been validated.

The handler analyzes and processes the requirements line by line. The request is accepted if the first requirement is fulfilled.

In case of 'valid-user' the request is accepted.

In case of one or more user-names, they are compared with the given user-name until the first match.

In case of one or more group-names, all groups of the given username are looked up in the cache. If the cache is not configured or if the user is not found in the cache, or if the requested group does not match the cached group, the groups are requested from the database. A comma separated list of all these groups is put into the environment variable REMOTE_GROUPS. Then these groups are compared with the required groups until the first match.

If there is no match and the authoritative directive is set to 'on' the request is rejected.

In case the authorization succeeds, the environment variable REMOTE_GROUP is set to the group name, which can be used by user scripts without accessing the database again.

The SQL-select used for retrieving the groups is as follows (depending upon the existence of a grp_table): 

 SELECT grp_field FROM pwd_table WHERE uid_field = user
 SELECT grp_field FROM grp_table WHERE uid_field = user

This way the group-information can either be held in the main users table, or in an extra table, if there is an m:n relationship between users and groups. From all selected groups a comma-separated list is build, which is compared with the required groups. If you don't like normalized group records you can put such a comma-separated list of groups (no spaces) into the grp_field instead of single groups.

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

Cache:

The module maintains an optional cash for all passwords/groups. See the method setCacheTime(n) on how to enable the cache. Every server has it's own cache. Optionally the cache can be put into a shared memory segment, so that it can be shared among all servers. See the CONFIGURATION section on how to enable the usage of shared memory.

In order to prevent the cache from growing indefinitely a CleanupHandler can be initialized, which skips through the cache and deletes all outdated entries. This can be done once per request after sending the response, hence without slowing down response time to the client. The minimum time between two successive runs of the CleanupHandler is configurable (see the CONFIGURATION section). The default is 0, which runs the CleanupHandler after every request. 

 
=head1 LIST OF TOKENS