2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_authz_dbd.xml.meta">
25 <name>mod_authz_dbd</name>
26 <description>Group Authorization and Login using SQL</description>
27 <status>Extension</status>
28 <sourcefile>mod_authz_dbd.c</sourcefile>
29 <identifier>authz_dbd_module</identifier>
30 <compatibility>Available in Apache 2.4 and later</compatibility>
33 <p>This module provides authorization capabilities so that
34 authenticated users can be allowed or denied access to portions
35 of the web site by group membership. Similar functionality is
36 provided by <module>mod_authz_groupfile</module> and
37 <module>mod_authz_dbm</module>, with the exception that
38 this module queries a SQL database to determine whether a
39 user is a member of a group.</p>
40 <p>This module can also provide database-backed user login/logout
41 capabilities. These are likely to be of most value when used
42 in conjunction with <module>mod_authn_dbd</module>.</p>
43 <p>This module relies on <module>mod_dbd</module> to specify
44 the backend database driver and connection parameters, and
45 manage the database connections.</p>
48 <seealso><directive module="mod_authz_core">Require</directive></seealso>
50 <directive module="mod_authn_dbd">AuthDBDUserPWQuery</directive>
52 <seealso><directive module="mod_dbd">DBDriver</directive></seealso>
53 <seealso><directive module="mod_dbd">DBDParams</directive></seealso>
55 <section id="requiredirectives"><title>The Require Directives</title>
57 <p>Apache's <directive module="mod_authz_core">Require</directive>
58 directives are used during the authorization phase to ensure that
59 a user is allowed to access a resource. mod_authz_dbd extends the
60 authorization types with <code>dbd-group</code>, <code>dbd-login</code> and
61 <code>dbd-logout</code>.</p>
63 <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
64 within the DBD require directives.</p>
66 <section id="reqgroup"><title>Require dbd-group</title>
68 <p>This directive specifies group membership that is required for the
69 user to gain access.</p>
71 <highlight language="config">
72 Require dbd-group team
73 AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
78 <section id="reqlogin"><title>Require dbd-login</title>
80 <p>This directive specifies a query to be run indicating the user
83 <highlight language="config">
85 AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
90 <section id="reqlogout"><title>Require dbd-logout</title>
92 <p>This directive specifies a query to be run indicating the user
95 <highlight language="config">
97 AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
105 <title>Database Login</title>
107 In addition to the standard authorization function of checking group
108 membership, this module can also provide server-side user session
109 management via database-backed login/logout capabilities.
110 Specifically, it can update a user's session status in the database
111 whenever the user visits designated URLs (subject of course to users
112 supplying the necessary credentials).</p>
113 <p>This works by defining two special
114 <directive module="mod_authz_core">Require</directive> types:
115 <code>Require dbd-login</code> and <code>Require dbd-logout</code>.
116 For usage details, see the configuration example below.</p>
119 <section id="client">
120 <title>Client Login integration</title>
121 <p>Some administrators may wish to implement client-side session
122 management that works in concert with the server-side login/logout
123 capabilities offered by this module, for example, by setting or unsetting
124 an HTTP cookie or other such token when a user logs in or out.</p>
125 <p>To support such integration, <module>mod_authz_dbd</module> exports an
126 optional hook that will be run whenever a user's status is updated in
127 the database. Other session management modules can then use the hook
128 to implement functions that start and end client-side sessions.</p>
131 <section id="example">
132 <title>Configuration example</title>
133 <highlight language="config">
134 # mod_dbd configuration
136 DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
143 <Directory /usr/www/my.site/team-private/>
144 # mod_authn_core and mod_auth_basic configuration
148 AuthBasicProvider dbd
150 # mod_authn_dbd SQL query to authenticate a logged-in user
152 "SELECT password FROM authn WHERE user = %s AND login = 'true'"
154 # mod_authz_core configuration for mod_authz_dbd
155 Require dbd-group team
157 # mod_authz_dbd configuration
158 AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
160 # when a user fails to be authenticated or authorized,
161 # invite them to login; this page should provide a link
162 # to /team-private/login.html
163 ErrorDocument 401 /login-info.html
165 <Files login.html>
166 # don't require user to already be logged in!
167 AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
169 # dbd-login action executes a statement to log user in
171 AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
173 # return user to referring page (if any) after
175 AuthzDBDLoginToReferer On
178 <Files logout.html>
179 # dbd-logout action executes a statement to log user out
181 AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
187 <section id="security">
188 <title>Preventing SQL injections</title>
189 <p>Whether you need to care about SQL security depends on what DBD driver
190 and backend you use. With most drivers you don't have to do anything :
191 the statement is prepared by the database at startup, and user input is
192 used only as data. But you may need to untaint your input. At the time
193 of writing, the only driver that requires you to take care is FreeTDS.</p>
194 <p>Please read <module>mod_dbd</module> documentation for more information
195 about security on this scope.</p>
199 <name>AuthzDBDQuery</name>
200 <description>Specify the SQL Query for the required operation</description>
201 <syntax>AuthzDBDQuery <var>query</var></syntax>
202 <contextlist><context>directory</context></contextlist>
205 <p>The <directive>AuthzDBDQuery</directive> specifies an SQL
206 query to run. The purpose of the query depends on the
207 <directive module="mod_authz_core">Require</directive> directive in
210 <li>When used with a <code>Require dbd-group</code> directive,
211 it specifies a query to look up groups for the current user. This is
212 the standard functionality of other authorization modules such as
213 <module>mod_authz_groupfile</module> and <module>mod_authz_dbm</module>.
214 The first column value of each row returned by the query statement
215 should be a string containing a group name. Zero, one, or more rows
217 <highlight language="config">
219 AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"
222 <li>When used with a <code>Require dbd-login</code> or
223 <code>Require dbd-logout</code> directive, it will never deny access,
224 but will instead execute a SQL statement designed to log the user
225 in or out. The user must already be authenticated with
226 <module>mod_authn_dbd</module>.
227 <highlight language="config">
229 AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
233 <p>In all cases, the user's ID will be passed as a single string
234 parameter when the SQL query is executed. It may be referenced within
235 the query statement using a <code>%s</code> format specifier.</p>
240 <name>AuthzDBDRedirectQuery</name>
241 <description>Specify a query to look up a login page for the user</description>
242 <syntax>AuthzDBDRedirectQuery <var>query</var></syntax>
243 <contextlist><context>directory</context></contextlist>
246 <p>Specifies an optional SQL query to use after successful login
247 (or logout) to redirect the user to a URL, which may be
248 specific to the user. The user's ID will be passed as a single string
249 parameter when the SQL query is executed. It may be referenced within
250 the query statement using a <code>%s</code> format specifier.</p>
251 <highlight language="config">
252 AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"
254 <p>The first column value of the first row returned by the query
255 statement should be a string containing a URL to which to redirect
256 the client. Subsequent rows will be ignored. If no rows are returned,
257 the client will not be redirected.</p>
258 <p>Note that <directive>AuthzDBDLoginToReferer</directive> takes
259 precedence if both are set.</p>
264 <name>AuthzDBDLoginToReferer</name>
265 <description>Determines whether to redirect the Client to the Referring
266 page on successful login or logout if a <code>Referer</code> request
267 header is present</description>
268 <syntax>AuthzDBDLoginToReferer On|Off</syntax>
269 <default>AuthzDBDLoginToReferer Off</default>
270 <contextlist><context>directory</context></contextlist>
273 <p>In conjunction with <code>Require dbd-login</code> or
274 <code>Require dbd-logout</code>, this provides the option to
275 redirect the client back to the Referring page (the URL in
276 the <code>Referer</code> HTTP request header, if present).
277 When there is no <code>Referer</code> header,
278 <code>AuthzDBDLoginToReferer On</code> will be ignored.</p>