1Apache::AuthDBI(3)    User Contributed Perl Documentation   Apache::AuthDBI(3)
2
3
4

NAME

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

SYNOPSIS

9        # Configuration in httpd.conf or startup.pl:
10
11        PerlModule Apache::AuthDBI
12
13        # Authentication and Authorization in .htaccess:
14
15        AuthName DBI
16        AuthType Basic
17
18        PerlAuthenHandler Apache::AuthDBI::authen
19        PerlAuthzHandler  Apache::AuthDBI::authz
20
21        PerlSetVar Auth_DBI_data_source   dbi:driver:dsn
22        PerlSetVar Auth_DBI_username      db_username
23        PerlSetVar Auth_DBI_password      db_password
24        #DBI->connect($data_source, $username, $password)
25
26        PerlSetVar Auth_DBI_pwd_table     users
27        PerlSetVar Auth_DBI_uid_field     username
28        PerlSetVar Auth_DBI_pwd_field     password
29        # authentication: SELECT pwd_field FROM pwd_table WHERE uid_field=$user
30        PerlSetVar Auth_DBI_grp_field     groupname
31        # authorization: SELECT grp_field FROM pwd_table WHERE uid_field=$user
32
33        require valid-user
34        require user   user_1  user_2 ...
35        require group group_1 group_2 ...
36
37       The AuthType is limited to Basic. You may use one or more valid require
38       lines.  For a single require line with the requirement 'valid-user' or
39       with the requirements 'user user_1 user_2 ...' it is sufficient to use
40       only the authentication handler.
41

DESCRIPTION

43       This module allows authentication and authorization against a database
44       using Perl's DBI. For supported DBI drivers see:
45
46        http://dbi.perl.org/
47
48       Authentication:
49
50       For the given username the password is looked up in the cache. If the
51       cache is not configured or if the user is not found in the cache, or if
52       the given password does not match the cached password, it is requested
53       from the database.
54
55       If the username does not exist and the authoritative directive is set
56       to 'on', the request is rejected. If the authoritative directive is set
57       to 'off', the control is passed on to next module in line.
58
59       If the password from the database for the given username is empty and
60       the nopasswd directive is set to 'off', the request is rejected. If the
61       nopasswd directive is set to 'on', any password is accepted.
62
63       Finally the passwords (multiple passwords per userid are allowed) are
64       retrieved from the database. The result is put into the environment
65       variable REMOTE_PASSWORDS. Then it is compared to the password given.
66       If the encrypted directive is set to 'on', the given password is
67       encrypted using perl's crypt() function before comparison. If the
68       encrypted directive is set to 'off' the plain-text passwords are
69       compared.
70
71       If this comparison fails the request is rejected, otherwise the request
72       is accepted and the password is put into the environment variable
73       REMOTE_PASSWORD.
74
75       The SQL-select used for retrieving the passwords is as follows:
76
77        SELECT pwd_field FROM pwd_table WHERE uid_field = user
78
79       If a pwd_whereclause exists, it is appended to the SQL-select.
80
81       This module supports in addition a simple kind of logging mechanism.
82       Whenever the handler is called and a log_string is configured, the
83       log_field will be updated with the log_string. As log_string -
84       depending upon the database - macros like TODAY can be used.
85
86       The SQL-select used for the logging mechanism is as follows:
87
88        UPDATE pwd_table SET log_field = log_string WHERE uid_field = user
89
90       Authorization:
91
92       When the authorization handler is called, the authentication has
93       already been done. This means, that the given username/password has
94       been validated.
95
96       The handler analyzes and processes the requirements line by line. The
97       request is accepted if the first requirement is fulfilled.
98
99       In case of 'valid-user' the request is accepted.
100
101       In case of one or more user-names, they are compared with the given
102       user-name until the first match.
103
104       In case of one or more group-names, all groups of the given username
105       are looked up in the cache. If the cache is not configured or if the
106       user is not found in the cache, or if the requested group does not
107       match the cached group, the groups are requested from the database. A
108       comma separated list of all these groups is put into the environment
109       variable REMOTE_GROUPS. Then these groups are compared with the
110       required groups until the first match.
111
112       If there is no match and the authoritative directive is set to 'on' the
113       request is rejected.
114
115       In case the authorization succeeds, the environment variable
116       REMOTE_GROUP is set to the group name, which can be used by user
117       scripts without accessing the database again.
118
119       The SQL-select used for retrieving the groups is as follows (depending
120       upon the existence of a grp_table):
121
122        SELECT grp_field FROM pwd_table WHERE uid_field = user
123        SELECT grp_field FROM grp_table WHERE uid_field = user
124
125       This way the group-information can either be held in the main users
126       table, or in an extra table, if there is an m:n relationship between
127       users and groups.  From all selected groups a comma-separated list is
128       build, which is compared with the required groups. If you don't like
129       normalized group records you can put such a comma-separated list of
130       groups (no spaces) into the grp_field instead of single groups.
131
132       If a grp_whereclause exists, it is appended to the SQL-select.
133
134       Cache:
135
136       The module maintains an optional cash for all passwords/groups. See the
137       method setCacheTime(n) on how to enable the cache. Every server has
138       it's own cache. Optionally the cache can be put into a shared memory
139       segment, so that it can be shared among all servers. See the
140       CONFIGURATION section on how to enable the usage of shared memory.
141
142       In order to prevent the cache from growing indefinitely a
143       CleanupHandler can be initialized, which skips through the cache and
144       deletes all outdated entries.  This can be done once per request after
145       sending the response, hence without slowing down response time to the
146       client. The minimum time between two successive runs of the
147       CleanupHandler is configurable (see the CONFIGURATION section). The
148       default is 0, which runs the CleanupHandler after every request.
149

LIST OF TOKENS

151       •   Auth_DBI_data_source (Authentication and Authorization)
152
153           The data_source value has the syntax 'dbi:driver:dsn'. This
154           parameter is passed to the database driver for processing during
155           connect. The data_source parameter (as well as the username and the
156           password parameters) may be a tilde ('~') separated list of several
157           data_sources. All of these triples will be used until a successful
158           connect is made. This way several backup-servers can be configured.
159           if you want to use the environment variable DBI_DSN instead of a
160           data_source, do not specify this parameter at all.
161
162       •   Auth_DBI_username (Authentication and Authorization)
163
164           The username argument is passed to the database driver for
165           processing during connect. This parameter may be a tilde ('~')
166           separated list.  See the data_source parameter above for the usage
167           of a list.
168
169       •   Auth_DBI_password (Authentication and Authorization)
170
171           The password argument is passed to the database driver for
172           processing during connect. This parameter may be a tilde ('~')
173           separated list.  See the data_source parameter above for the usage
174           of a list.
175
176       •   Auth_DBI_pwd_table (Authentication and Authorization)
177
178           Contains at least the fields with the username and the (possibly
179           encrypted) password. The username should be unique.
180
181       •   Auth_DBI_uid_field (Authentication and Authorization)
182
183           Field name containing the username in the Auth_DBI_pwd_table.
184
185       •   Auth_DBI_pwd_field (Authentication only)
186
187           Field name containing the password in the Auth_DBI_pwd_table.
188
189       •   Auth_DBI_pwd_whereclause (Authentication only)
190
191           Use this option for specifying more constraints to the SQL-select.
192
193       •   Auth_DBI_grp_table (Authorization only)
194
195           Contains at least the fields with the username and the groupname.
196
197       •   Auth_DBI_grp_field (Authorization only)
198
199           Field-name containing the groupname in the Auth_DBI_grp_table.
200
201       •   Auth_DBI_grp_whereclause (Authorization only)
202
203           Use this option for specifying more constraints to the SQL-select.
204
205       •   Auth_DBI_log_field (Authentication only)
206
207           Field name containing the log string in the Auth_DBI_pwd_table.
208
209       •   Auth_DBI_log_string (Authentication only)
210
211           String to update the Auth_DBI_log_field in the Auth_DBI_pwd_table.
212           Depending upon the database this can be a macro like 'TODAY'.
213
214       •   Auth_DBI_authoritative  < on / off> (Authentication and
215           Authorization)
216
217           Default is 'on'. When set 'on', there is no fall-through to other
218           authentication methods if the authentication check fails. When this
219           directive is set to 'off', control is passed on to any other
220           authentication modules. Be sure you know what you are doing when
221           you decide to switch it off.
222
223       •   Auth_DBI_nopasswd  < on / off > (Authentication only)
224
225           Default is 'off'. When set 'on' the password comparison is skipped
226           if the password retrieved from the database is empty, i.e. allow
227           any password.  This is 'off' by default to ensure that an empty
228           Auth_DBI_pwd_field does not allow people to log in with a random
229           password. Be sure you know what you are doing when you decide to
230           switch it on.
231
232       •   Auth_DBI_encrypted  < on / off > (Authentication only)
233
234           Default is 'on'. When set to 'on', the password retrieved from the
235           database is assumed to be crypted. Hence the incoming password will
236           be crypted before comparison. When this directive is set to 'off',
237           the comparison is done directly with the plain-text entered
238           password.
239
240       •   Auth_DBI_encryption_method < sha1hex/md5hex/crypt > (Authentication
241           only)
242
243           Default is blank. When set to one or more encryption method, the
244           password retrieved from the database is assumed to be crypted.
245           Hence the incoming password will be crypted before comparison.  The
246           method supports falling back so specifying 'sha1hex/md5hex' would
247           allow for a site that is upgrading to sha1 to support both methods.
248           sha1 is the recommended method.
249
250       •   Auth_DBI_encryption_salt < password / userid > (Authentication
251           only)
252
253           When crypting the given password AuthDBI uses per default the
254           password selected from the database as salt. Setting this parameter
255           to 'userid', the module uses the userid as salt.
256
257       •   Auth_DBI_uidcasesensitive  < on / off > (Authentication and
258           Authorization)
259
260           Default is 'on'. When set 'off', the entered userid is converted to
261           lower case.  Also the userid in the password select-statement is
262           converted to lower case.
263
264       •   Auth_DBI_pwdcasesensitive  < on / off > (Authentication only)
265
266           Default is 'on'. When set 'off', the entered password is converted
267           to lower case.
268
269       •   Auth_DBI_placeholder < on / off > (Authentication and
270           Authorization)
271
272           Default is 'off'.  When set 'on', the select statement is prepared
273           using a placeholder for the username.  This may result in improved
274           performance for databases supporting this method.
275

CONFIGURATION

277       The module should be loaded upon startup of the Apache daemon.  Add the
278       following line to your httpd.conf:
279
280        PerlModule Apache::AuthDBI
281
282       A common usage is to load the module in a startup file via the
283       PerlRequire directive. See eg/startup.pl for an example.
284
285       There are three configurations which are server-specific and which can
286       be done in a startup file:
287
288        Apache::AuthDBI->setCacheTime(0);
289
290       This configures the lifetime in seconds for the entries in the cache.
291       Default is 0, which turns off the cache. When set to any value n > 0,
292       the passwords/groups of all users will be cached for at least n
293       seconds. After finishing the request, a special handler skips through
294       the cache and deletes all outdated entries (entries, which are older
295       than the CacheTime).
296
297        Apache::AuthDBI->setCleanupTime(-1);
298
299       This configures the minimum time in seconds between two successive runs
300       of the CleanupHandler, which deletes all outdated entries from the
301       cache. The default is -1, which disables the CleanupHandler. Setting
302       the interval to 0 runs the CleanupHandler after every request. For a
303       heavily loaded server this should be set to a value, which reflects a
304       compromise between scanning a large cache possibly containing many
305       outdated entries and between running many times the CleanupHandler on a
306       cache containing only few entries.
307
308        Apache::AuthDBI->setProjID(1);
309
310       This configures the project ID used to create a semaphore ID for shared
311       memory.  It can be set to any integer 1 to 255 or it will default to a
312       value of 1.
313
314       NOTE: This must be set prior to calling initIPC.
315
316       If you are running multiple instances of Apache on the same server\
317       (for example, Apache1 and Apache2), you may not want (or be able) to
318       use shared memory between them.  In this case, use a different project
319       ID on each server.
320
321       If you are reading this because you suspect you have a permission issue
322       or a collision with a semaphore, use 'ipcs -s' to list semaphores and
323       look for the Semaphore ID from the apache error log.  If found,
324       shutdown Apache (all of them) and use 'ipcrm sem <semaphore key>' to
325       remove the colliding (and hopefully unused) semaphore.
326
327       You may also want to remove any orphaned shared memory segments by
328       using 'ipcs -m' and removing the orphans with ipcrm shm <shared memory
329       id>.
330
331        Apache::AuthDBI->initIPC(50000);
332
333       This enables the usage of shared memory for the cache. Instead of every
334       server maintaining it's own cache, all servers have access to a common
335       cache. This should minimize the database load considerably for sites
336       running many servers.  The number indicates the size of the shared
337       memory segment in bytes. This size is fixed, there is no dynamic
338       allocation of more segments. As a rule of thumb multiply the estimated
339       maximum number of simultaneously cached users by 100 to get a rough
340       estimate of the needed size. Values below 500 will be overwritten with
341       the default 50000.
342
343       To enable debugging the variable $Apache::AuthDBI::DEBUG must be set.
344       This can either be done in startup.pl or in the user script. Setting
345       the variable to 1, just reports about a cache miss. Setting the
346       variable to 2 enables full debug output.
347

PREREQUISITES

349   MOD_PERL 2.0
350       Apache::DBI version 0.96 and should work under mod_perl 2.0 RC5 and
351       later with httpd 2.0.49 and later.
352
353       Apache::DBI versions less than 1.00 are NO longer supported.
354       Additionally, mod_perl versions less then 2.0.0 are NO longer
355       supported.
356
357   MOD_PERL 1.0
358       Note that this module needs mod_perl-1.08 or higher, apache_1.3.0 or
359       higher and that mod_perl needs to be configured with the appropriate
360       call-back hooks:
361
362         PERL_AUTHEN=1 PERL_AUTHZ=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1
363
364       Apache::DBI v0.94 was the last version before dual mod_perl 2.x support
365       was begun.  It still recommened that you use the latest version of
366       Apache::DBI because Apache::DBI versions less than 1.00 are NO longer
367       supported.
368

SECURITY

370       In some cases it is more secure not to put the username and the
371       password in the .htaccess file. The following example shows a solution
372       to this problem:
373
374       httpd.conf:
375
376        <Perl>
377        my($uid,$pwd) = My::dbi_pwd_fetch();
378        $Location{'/foo/bar'}->{PerlSetVar} = [
379            [ Auth_DBI_username  => $uid ],
380            [ Auth_DBI_password  => $pwd ],
381        ];
382        </Perl>
383

SEE ALSO

385       Apache, mod_perl, DBI
386

AUTHORS

388       •   Apache::AuthDBI by Edmund Mergl; now maintained and supported by
389           the modperl mailinglist, subscribe by sending mail to
390           modperl-subscribe@perl.apache.org.
391
392       •   mod_perl by Doug MacEachern.
393
394       •   DBI by Tim Bunce <dbi-users-subscribe@perl.org>
395
397       The Apache::AuthDBI module is free software; you can redistribute it
398       and/or modify it under the same terms as Perl itself.
399
400
401
402perl v5.32.1                      2021-01-26                Apache::AuthDBI(3)
Impressum