<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_authz_dbd.xml.meta">

<name>mod_authz_dbd</name>

<description>Group Authorization and Login using SQL</description>

<status>Extension</status>

<sourcefile>mod_authz_dbd.c</sourcefile>

<identifier>authz_dbd_module</identifier>

<compatibility>Available in Apache 2.2 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>

</summary>

<seealso><directive module="core">Require</directive></seealso>

<seealso><directive module="mod_dbd">DBDriver</directive></seealso>

<seealso><directive module="mod_dbd">DBDParams</directive></seealso>

<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>This works by defining two special

<directive module="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>

</section>

<section id="example">

<title>Configuration Example</title>

<example><pre><code>

# DBD Configuration

DBDriver oracle

DBDParams "dbname=apacheauth user=apache pass=xxxxxx"

DBDMin 4

DBDKeep 8

DBDMax 20

DBDExptime 300

&lt;Directory /usr/www/my.site/team-private/&gt;

# authn with mod_authn_dbd

AuthType Basic

AuthName Team

AuthBasicProvider dbd

AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s AND login = true"

# Require dbd-group and authz_dbd implementation

Require dbd-group team

AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"

# When a user fails to authn/authz, invite them to login

ErrorDocument 401 /team-private/login-form.html

&lt;Files login.html&gt;

# Don't require that we're already logged in!

AuthDBDUserPWQuery "SELECT pass FROM authn 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"

# Return user to referring page (if any) on successful login

AuthzDBDLoginToReferer On

&lt;/Files&gt;

&lt;Files logout.html&gt;

# dbd-logout action executes a query to set our own state

Require dbd-logout

AuthzDBDQuery "UPDATE authn SET login = false WHERE user = %s"

&lt;/Files&gt;

&lt;/Directory&gt;

</code></pre>

</example>

</section>

<directivesynopsis>

<name>AuthzDBDQuery</name>

<description>Specify the SQL Query for the required operation</description>

<syntax>AuthzDBDQuery SQL-Query</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

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>

<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>

</ul>

</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>

<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>Note that <directive>AuthzDBDLoginToReferer</directive> takes

precedence if both are set.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthzDBDLoginToReferer</name>

<description>Determines whether to redirect the Client to the Referring

page on successful login or logout if a <code>Referer</code> request

header is present</description>

<syntax>AuthzDBDLoginToReferer On|Off</syntax>

<default>AuthzDBDLoginToReferer Off</default>

<contextlist><context>directory</context></contextlist>

<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.

When there is no <code>Referer</code> header,

<code>AuthzDBDLoginToReferer On</code> will be ignored.</p>

</usage>

</directivesynopsis>

</modulesynopsis>