1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<modulesynopsis metafile="mod_authn_dbd.xml.meta">
<name>mod_authn_dbd</name>
<description>User authentication using an SQL database</description>
<status>Extension</status>
<sourcefile>mod_authn_dbd.c</sourcefile>
<identifier>authn_dbd_module</identifier>
<summary>
<p>This module provides authentication front-ends such as
<module>mod_auth_digest</module> and <module>mod_auth_basic</module>
to authenticate users by looking up users in SQL tables.
Similar functionality is provided by, for example,
<module>mod_authn_file</module>.</p>
<p>This module relies on <module>mod_dbd</module> to specify
the backend database driver and connection parameters, and
manage the database connections.</p>
<p>When using <module>mod_auth_basic</module> or
<module>mod_auth_digest</module>, this module is invoked via the
<directive module="mod_auth_basic">AuthBasicProvider</directive> or
<directive module="mod_auth_digest">AuthDigestProvider</directive>
with the <code>dbd</code> value.</p>
</summary>
<seealso><directive module="mod_authn_core">AuthName</directive></seealso>
<seealso><directive module="mod_authn_core">AuthType</directive></seealso>
<seealso>
<directive module="mod_auth_basic">AuthBasicProvider</directive>
</seealso>
<seealso>
<directive module="mod_auth_digest">AuthDigestProvider</directive>
</seealso>
<seealso><directive module="mod_dbd">DBDriver</directive></seealso>
<seealso><directive module="mod_dbd">DBDParams</directive></seealso>
<seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso>
<section id="socache">
<title>Performance and Cacheing</title>
<p>Some users of DBD authentication in HTTPD 2.2/2.4 have reported that it
imposes a problematic load on the database. This is most likely where
an HTML page contains hundreds of objects (e.g. images, scripts, etc)
each of which requires authentication. Users affected (or concerned)
by this kind of problem should use <module>mod_authn_socache</module>
to cache credentials and take most of the load off the database.</p>
</section>
<section id="example">
<title>Configuration Example</title>
<p>This simple example shows use of this module in the context of
the Authentication and DBD frameworks.</p>
<highlight language="config">
# mod_dbd configuration
# UPDATED to include authentication cacheing
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache password=xxxxxx"
DBDMin 4
DBDKeep 8
DBDMax 20
DBDExptime 300
<Directory "/usr/www/myhost/private">
# mod_authn_core and mod_auth_basic configuration
# for mod_authn_dbd
AuthType Basic
AuthName "My Server"
# To cache credentials, put socache ahead of dbd here
AuthBasicProvider socache dbd
# Also required for caching: tell the cache to cache dbd lookups!
AuthnCacheProvideFor dbd
AuthnCacheContext my-server
# mod_authz_core configuration
Require valid-user
# mod_authn_dbd SQL query to authenticate a user
AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
</Directory>
</highlight>
</section>
<section id="exposed">
<title>Exposing Login Information</title>
<p>
If httpd was built against <glossary>APR</glossary> version 1.3.0
or higher, then whenever a query is made to the database server, all
column values in the first row returned by the query are placed in the
environment, using environment variables with the prefix "AUTHENTICATE_".
</p>
<p>If a database query for example returned the username, full name
and telephone number of a user, a CGI program will have access to
this information without the need to make a second independent database
query to gather this additional information.</p>
<p>This has the potential to dramatically simplify the coding and
configuration required in some web applications.
</p>
</section>
<section id="security">
<title>Preventing SQL injections</title>
<p>Whether you need to care about SQL security depends on what DBD driver
and backend you use. With most drivers you don't have to do anything :
the statement is prepared by the database at startup, and user input is
used only as data. But you may need to untaint your input. At the time
of writing, the only driver that requires you to take care is FreeTDS.</p>
<p>Please read <module>mod_dbd</module> documentation for more information
about security on this scope.</p>
</section>
<directivesynopsis>
<name>AuthDBDUserPWQuery</name>
<description>SQL query to look up a password for a user</description>
<syntax>AuthDBDUserPWQuery <var>query</var></syntax>
<contextlist><context>directory</context>
</contextlist>
<usage>
<p>The <directive>AuthDBDUserPWQuery</directive> specifies an
SQL query to look up a password for a specified user. The user's ID
will be passed as a single string parameter when the SQL query is
executed. It may be referenced within the query statement using
a <code>%s</code> format specifier.</p>
<highlight language="config">
AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
</highlight>
<p>The first column value of the first row returned by the query
statement should be a string containing the encrypted password.
Subsequent rows will be ignored. If no rows are returned, the user
will not be authenticated through <module>mod_authn_dbd</module>.</p>
<p>If httpd was built against <glossary>APR</glossary> version 1.3.0
or higher, any additional column values in the first row returned by
the query statement will be stored as environment variables with
names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
</p>
<p>The encrypted password format depends on which authentication
frontend (e.g. <module>mod_auth_basic</module> or
<module>mod_auth_digest</module>) is being used. See <a
href="../misc/password_encryptions.html">Password Formats</a> for
more information.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>AuthDBDUserRealmQuery</name>
<description>SQL query to look up a password hash for a user and realm.
</description>
<syntax>AuthDBDUserRealmQuery <var>query</var></syntax>
<contextlist><context>directory</context>
</contextlist>
<usage>
<p>The <directive>AuthDBDUserRealmQuery</directive> specifies an
SQL query to look up a password for a specified user and realm in a
digest authentication process.
The user's ID and the realm, in that order, will be passed as string
parameters when the SQL query is executed. They may be referenced
within the query statement using <code>%s</code> format specifiers.</p>
<highlight language="config">
AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s"
</highlight>
<p>The first column value of the first row returned by the query
statement should be a string containing the encrypted password.
Subsequent rows will be ignored. If no rows are returned, the user
will not be authenticated through <module>mod_authn_dbd</module>.</p>
<p>If httpd was built against <glossary>APR</glossary> version 1.3.0
or higher, any additional column values in the first row returned by
the query statement will be stored as environment variables with
names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
</p>
<p>The encrypted password format depends on which authentication
frontend (e.g. <module>mod_auth_basic</module> or
<module>mod_auth_digest</module>) is being used. See <a
href="../misc/password_encryptions.html">Password Formats</a> for
more information.</p>
</usage>
</directivesynopsis>
</modulesynopsis>
|
