1Apache::AuthDBI(3) User Contributed Perl Documentation Apache::AuthDBI(3)
2
6 Apache::AuthDBI - Authentication and Authorization via Perl's DBI
7
9 # Configuration in httpd.conf or startup.pl:
10 PerlModule Apache::AuthDBI
12 # Authentication and Authorization in .htaccess:
14 AuthName DBI
16 AuthType Basic
17 PerlAuthenHandler Apache::AuthDBI::authen
19 PerlAuthzHandler Apache::AuthDBI::authz
20 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 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 require valid-user
34 require user user_1 user_2 ...
35 require group group_1 group_2 ...
36 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
43 This module allows authentication and authorization against a database
44 using Perl's DBI. For supported DBI drivers see:
45 http://dbi.perl.org/
47 Authentication:
49 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 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 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 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 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 The SQL-select used for retrieving the passwords is as follows:
76 SELECT pwd_field FROM pwd_table WHERE uid_field = user
78 If a pwd_whereclause exists, it is appended to the SQL-select.
80 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 The SQL-select used for the logging mechanism is as follows:
87 UPDATE pwd_table SET log_field = log_string WHERE uid_field = user
89 Authorization:
91 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 The handler analyzes and processes the requirements line by line. The
97 request is accepted if the first requirement is fulfilled.
98 In case of 'valid-user' the request is accepted.
100 In case of one or more user-names, they are compared with the given
102 user-name until the first match.
103 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 If there is no match and the authoritative directive is set to 'on' the
113 request is rejected.
114 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 The SQL-select used for retrieving the groups is as follows (depending
120 upon the existence of a grp_table):
121 SELECT grp_field FROM pwd_table WHERE uid_field = user
123 SELECT grp_field FROM grp_table WHERE uid_field = user
124 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 If a grp_whereclause exists, it is appended to the SQL-select.
133 Cache:
135 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 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
151 • Auth_DBI_data_source (Authentication and Authorization)
152 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 • Auth_DBI_username (Authentication and Authorization)
163 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 • Auth_DBI_password (Authentication and Authorization)
170 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 • Auth_DBI_pwd_table (Authentication and Authorization)
177 Contains at least the fields with the username and the (possibly
179 encrypted) password. The username should be unique.
180 • Auth_DBI_uid_field (Authentication and Authorization)
182 Field name containing the username in the Auth_DBI_pwd_table.
184 • Auth_DBI_pwd_field (Authentication only)
186 Field name containing the password in the Auth_DBI_pwd_table.
188 • Auth_DBI_pwd_whereclause (Authentication only)
190 Use this option for specifying more constraints to the SQL-select.
192 • Auth_DBI_grp_table (Authorization only)
194 Contains at least the fields with the username and the groupname.
196 • Auth_DBI_grp_field (Authorization only)
198 Field-name containing the groupname in the Auth_DBI_grp_table.
200 • Auth_DBI_grp_whereclause (Authorization only)
202 Use this option for specifying more constraints to the SQL-select.
204 • Auth_DBI_log_field (Authentication only)
206 Field name containing the log string in the Auth_DBI_pwd_table.
208 • Auth_DBI_log_string (Authentication only)
210 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 • Auth_DBI_authoritative < on / off> (Authentication and
215 Authorization)
216 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 • Auth_DBI_nopasswd < on / off > (Authentication only)
224 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 • Auth_DBI_encrypted < on / off > (Authentication only)
233 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 • Auth_DBI_encryption_method < sha1hex/md5hex/crypt > (Authentication
241 only)
242 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 • Auth_DBI_encryption_salt < password / userid > (Authentication
251 only)
252 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 • Auth_DBI_uidcasesensitive < on / off > (Authentication and
258 Authorization)
259 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 • Auth_DBI_pwdcasesensitive < on / off > (Authentication only)
265 Default is 'on'. When set 'off', the entered password is converted
267 to lower case.
268 • Auth_DBI_placeholder < on / off > (Authentication and
270 Authorization)
271 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
277 The module should be loaded upon startup of the Apache daemon. Add the
278 following line to your httpd.conf:
279 PerlModule Apache::AuthDBI
281 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 There are three configurations which are server-specific and which can
286 be done in a startup file:
287 Apache::AuthDBI->setCacheTime(0);
289 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 Apache::AuthDBI->setCleanupTime(-1);
298 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 Apache::AuthDBI->setProjID(1);
309 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 NOTE: This must be set prior to calling initIPC.
315 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 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 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 Apache::AuthDBI->initIPC(50000);
332 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 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
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 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 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 PERL_AUTHEN=1 PERL_AUTHZ=1 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1
363 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
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 httpd.conf:
375 <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
385 Apache, mod_perl, DBI
386
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 • mod_perl by Doug MacEachern.
393 • 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.
399perl v5.36.0 2022-07-22 Apache::AuthDBI(3)