--- name: "Apache::AuthzDBI" section: "3pm" platform: "linux" package: "libapache-dbi-perl" version: "0.80-1" release: "Debian 2.1 (Slink)" platforms: ["linux"] url: "https://new.carta.tech/Apache::AuthzDBI" --- # Apache::AuthzDBI(3pm) Authorization via Perl's DBI ## NAME Apache::AuthzDBI - Authorization via Perl's DBI ## SYNOPSIS ``` # Configuration in httpd.conf or srm.conf: ``` ``` PerlModule Apache::AuthzDBI ``` ``` # Authorization in .htaccess: ``` ``` AuthName DBI AuthType Basic ``` ``` #authorize via DBI PerlAuthzHandler Apache::AuthzDBI ``` ``` 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_grp_field groupname #SELECT grp_field FROM pwd_table WHERE uid_field=$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 tokens valid-user or with distinct user names it is sufficient to use only the AuthenDBI module. ## DESCRIPTION This module allows authorization against a database using Perl's DBI. For supported DBI drivers see: ``` http://www.hermetica.com/technologia/DBI/ ``` 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 only if all requirement lines are accepted. In case of one or more user-names, they are compared with the given user-name until the first match. If there is no match and the authoritative directive is set to 'on' the request is rejected. In case of one or more group-names, all groups of the given user-name are looked up in the cache. If the user is not found in the cache, 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 of 'valid-user' the request is accepted. In case the authorization succeeds, the environment variable REMOTE\_GROUP is set to the group name, so scripts that are protected by AuthzDBI don't need to bang on the database server again to get the group name. 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 you can have the group-information either in the main users table, or you can use an extra table, if you have 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. At the end a CleanupHandler is initialized, which skips through the groups 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. ## 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\_grp\_table Contains at least the fields with the username and the groupname. \ - • Auth\_DBI\_uid\_field Field-name containing the username in the Auth\_DBI\_grp\_table. \ - • Auth\_DBI\_grp\_field Field-name containing the groupname in the Auth\_DBI\_grp\_table. \ - • Auth\_DBI\_grp\_whereclause Use this option for specifying more constraints to the SQL-select.\ - • Auth\_DBI\_authoritative \< on / off\> Default is 'on'. When set 'on', there is no fall-through to other authorization methods if the authorization check fails. When this directive is set to 'off', control is passed on to any other authorization modules. Be sure you know what you are doing when you decide to switch it off. \ - • 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 groups 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). ## CONFIGURATION The module should be loaded upon startup of the Apache daemon. It needs the AuthenDBI module for the authentication part. 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_AUTHZ=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1. ``` Add the following lines to your httpd.conf or srm.conf: ``` PerlModule Apache::AuthenDBI PerlModule Apache::AuthzDBI ``` ## PREREQUISITES For Apache::AuthzDBI you need to enable the appropriate call-back hooks when making mod\_perl: ``` perl Makefile.PL DO_HTTPD=1 PERL_AUTHEN=1 PERL_AUTHZ=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1. ``` ## SEE ALSO the *Apache* manpage, the *mod\_perl* manpage, the *DBI* manpage ## AUTHORS - • mod\_perl by Doug MacEachern \ - • DBI by Tim Bunce \ - • Apache::AuthzDBI by Edmund Mergl \ ## COPYRIGHT The Apache::AuthzDBI module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.