<status>Extension</status>
<sourcefile>mod_authz_dbd.c</sourcefile>
<identifier>authz_dbd_module</identifier>
-<compatibility>Available in Apache 2.2 and later</compatibility>
+<compatibility>Available in Apache 2.4 and later</compatibility>
<summary>
<p>This module provides authorization capabilities so that
authenticated users can be allowed or denied access to portions
- of the web site by group membership. It also provides
- database/backend login/logout in conjunction with
- <module>mod_authn_dbd</module>.</p>
+ of the web site by group membership. Similar functionality is
+ provided by <module>mod_authz_groupfile</module> and
+ <module>mod_authz_dbm</module>, with the exception that
+ this module queries a SQL database to determine whether a
+ user is a member of a group.</p>
+ <p>This module can also provide database-backed user login/logout
+ capabilities. These are likely to be of most value when used
+ in conjunction with <module>mod_authn_dbd</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>
</summary>
-<seealso><directive module="core">Require</directive></seealso>
+<seealso><directive module="mod_authz_core">Require</directive></seealso>
+<seealso>
+ <directive module="mod_authn_dbd">AuthDBDUserPWQuery</directive>
+</seealso>
<seealso><directive module="mod_dbd">DBDriver</directive></seealso>
<seealso><directive module="mod_dbd">DBDParams</directive></seealso>
+<section id="requiredirectives"><title>The Require Directives</title>
+
+ <p>Apache's <directive module="mod_authz_core">Require</directive>
+ directives are used during the authorization phase to ensure that
+ a user is allowed to access a resource. mod_authz_dbd extends the
+ authorization types with <code>dbd-group</code>, <code>dbd-login</code> and
+ <code>dbd-logout</code>.</p>
+
+ <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
+ within the DBD require directives.</p>
+
+<section id="reqgroup"><title>Require dbd-group</title>
+
+ <p>This directive specifies group membership that is required for the
+ user to gain access.</p>
+
+ <highlight language="config">
+ Require dbd-group team
+ AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
+ </highlight>
+
+</section>
+
+<section id="reqlogin"><title>Require dbd-login</title>
+
+ <p>This directive specifies a query to be run indicating the user
+ has logged in.</p>
+
+ <highlight language="config">
+ Require dbd-login
+ AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
+ </highlight>
+
+</section>
+
+<section id="reqlogout"><title>Require dbd-logout</title>
+
+ <p>This directive specifies a query to be run indicating the user
+ has logged out.</p>
+
+ <highlight language="config">
+ Require dbd-logout
+ AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
+ </highlight>
+
+</section>
+
+</section>
+
<section id="login">
<title>Database Login</title>
-<p>In addition to the standard authz function of checking group
-membership, this module provides database Login/Logout capability.
-Specifically, we can maintain a logged in/logged out status in
-the database, and control the status via designated URLs (subject
-of course to users supplying the necessary credentials).</p>
+<p>
+In addition to the standard authorization function of checking group
+membership, this module can also provide server-side user session
+management via database-backed login/logout capabilities.
+Specifically, it can update a user's session status in the database
+whenever the user visits designated URLs (subject of course to users
+supplying the necessary credentials).</p>
<p>This works by defining two special
-<directive module="core">Require</directive> types:
+<directive module="mod_authz_core">Require</directive> types:
<code>Require dbd-login</code> and <code>Require dbd-logout</code>.
For usage details, see the configuration example below.</p>
</section>
<section id="client">
-<title>Client Login</title>
-<p>In conjunction with server login/logout, we may wish to implement
-clientside login/out, for example by setting and unsetting a cookie
-or other such token. Although this is not the business of an authz
-module, client session management software should be able to tie its
-operation in to database login/logout. To support this,
-<module>mod_authz_dbd</module> exports an optional hook that will
-be run whenever a user successfully logs into or out of the database.
-Session management modules can use the hook to implement functions
-to start and end a client session.</p>
+<title>Client Login integration</title>
+<p>Some administrators may wish to implement client-side session
+management that works in concert with the server-side login/logout
+capabilities offered by this module, for example, by setting or unsetting
+an HTTP cookie or other such token when a user logs in or out.</p>
+<p>To support such integration, <module>mod_authz_dbd</module> exports an
+optional hook that will be run whenever a user's status is updated in
+the database. Other session management modules can then use the hook
+to implement functions that start and end client-side sessions.</p>
</section>
<section id="example">
-<title>Configuration Example</title>
-<example><pre><code>
-# DBD Configuration
-DBDriver oracle
+<title>Configuration example</title>
+<highlight language="config">
+# mod_dbd configuration
+DBDriver pgsql
DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
DBDMin 4
DBDMax 20
DBDExptime 300
-<Directory /usr/www/my.site/team-private/>
- # authn with mod_authn_dbd
- AuthType Basic
- AuthName Team
- AuthBasicProvider dbd
- AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s AND login = true"
+<Directory "/usr/www/my.site/team-private/">
+ # mod_authn_core and mod_auth_basic configuration
+ # for mod_authn_dbd
+ AuthType Basic
+ AuthName Team
+ AuthBasicProvider dbd
- # Require dbd-group and authz_dbd implementation
- Require dbd-group team
- AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
+ # mod_authn_dbd SQL query to authenticate a logged-in user
+ AuthDBDUserPWQuery \
+ "SELECT password FROM authn WHERE user = %s AND login = 'true'"
- # When a user fails to authn/authz, invite them to login
- ErrorDocument 401 /team-private/login-form.html
+ # mod_authz_core configuration for mod_authz_dbd
+ Require dbd-group team
- <Files login.html>
- # Don't require that we're already logged in!
- AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s"
+ # mod_authz_dbd configuration
+ AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
- # dbd-login action executes a query to set our own state
- Require dbd-login
- AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"
+ # when a user fails to be authenticated or authorized,
+ # invite them to login; this page should provide a link
+ # to /team-private/login.html
+ ErrorDocument 401 /login-info.html
- # Return user to referring page (if any) on successful login
- AuthzDBDLoginToReferer On
- </Files>
+ <Files "login.html">
+ # don't require user to already be logged in!
+ AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
- <Files logout.html>
- # dbd-logout action executes a query to set our own state
- Require dbd-logout
- AuthzDBDQuery "UPDATE authn SET login = false WHERE user = %s"
- </Files>
+ # dbd-login action executes a statement to log user in
+ Require dbd-login
+ AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
+
+ # return user to referring page (if any) after
+ # successful login
+ AuthzDBDLoginToReferer On
+ </Files>
+
+ <Files "logout.html">
+ # dbd-logout action executes a statement to log user out
+ Require dbd-logout
+ AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
+ </Files>
</Directory>
-</code></pre>
-</example>
+</highlight>
+</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>AuthzDBDQuery</name>
<description>Specify the SQL Query for the required operation</description>
-<syntax>AuthzDBDQuery SQL-Query</syntax>
+<syntax>AuthzDBDQuery <var>query</var></syntax>
<contextlist><context>directory</context></contextlist>
<usage>
<p>The <directive>AuthzDBDQuery</directive> specifies an SQL
query to run. The purpose of the query depends on the
- <directive module="core">Require</directive> directive in
+ <directive module="mod_authz_core">Require</directive> directive in
effect.</p>
<ul>
- <li>With <code>Require dbd-group</code>, it specifies a query
- to look up groups for the current user. This is the standard
- functionality of other authz modules such as
- <module>mod_authz_file</module> and <module>mod_authz_dbm</module>.
- In this case it will typically take the form<br/>
- <code>AuthzDBDQuery "SELECT group FROM groups WHERE user= %s"</code>
+ <li>When used with a <code>Require dbd-group</code> directive,
+ it specifies a query to look up groups for the current user. This is
+ the standard functionality of other authorization modules such as
+ <module>mod_authz_groupfile</module> and <module>mod_authz_dbm</module>.
+ The first column value of each row returned by the query statement
+ should be a string containing a group name. Zero, one, or more rows
+ may be returned.
+ <highlight language="config">
+Require dbd-group
+AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"
+</highlight>
</li>
- <li>With <code>Require dbd-login</code> or <code>Require dbd-logout</code>,
- it will never deny access, but will instead execute an SQL Query
- designed to log the user (who must already be authenticated with
- <module>mod_authn_dbd</module>) in or out. Such a query will
- typically take the form<br/>
- <code>AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"</code>
+ <li>When used with a <code>Require dbd-login</code> or
+ <code>Require dbd-logout</code> directive, it will never deny access,
+ but will instead execute a SQL statement designed to log the user
+ in or out. The user must already be authenticated with
+ <module>mod_authn_dbd</module>.
+ <highlight language="config">
+Require dbd-login
+AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
+</highlight>
</li>
</ul>
+ <p>In all cases, 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>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>AuthzDBDRedirectQuery</name>
<description>Specify a query to look up a login page for the user</description>
-<syntax>AuthzDBDRedirectQuery SQL-Query</syntax>
+<syntax>AuthzDBDRedirectQuery <var>query</var></syntax>
<contextlist><context>directory</context></contextlist>
<usage>
- <p>Specifies an optional query to use after successful login
- (or logout) to redirect the user to a page, which may be
- specific to the user. Such a query will take the form<br/>
- <code>AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"</code>
- </p>
+ <p>Specifies an optional SQL query to use after successful login
+ (or logout) to redirect the user to a URL, which may be
+ specific to the 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">
+AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"
+</highlight>
+ <p>The first column value of the first row returned by the query
+ statement should be a string containing a URL to which to redirect
+ the client. Subsequent rows will be ignored. If no rows are returned,
+ the client will not be redirected.</p>
<p>Note that <directive>AuthzDBDLoginToReferer</directive> takes
precedence if both are set.</p>
</usage>
<p>In conjunction with <code>Require dbd-login</code> or
<code>Require dbd-logout</code>, this provides the option to
redirect the client back to the Referring page (the URL in
- the <code>Referer</code> HTTP request header, if present.
+ the <code>Referer</code> HTTP request header, if present).
When there is no <code>Referer</code> header,
<code>AuthzDBDLoginToReferer On</code> will be ignored.</p>
</usage>
projects / apache / blobdiff