<?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="mod_authz_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="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>

</section>

<section id="example">

<title>Configuration Example</title>

<example><pre>

# mod_dbd configuration

DBDriver pgsql

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

DBDMin 4

DBDKeep 8

DBDMax 20

DBDExptime 300

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

# mod_authn_core and mod_auth_basic configuration

# for mod_authn_dbd

AuthType Basic

AuthName Team

AuthBasicProvider dbd

# mod_authn_dbd SQL query to authenticate a logged-in user

AuthDBDUserPWQuery \

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

# mod_authz_core configuration for mod_authz_dbd

Require dbd-group team

# mod_authz_dbd configuration

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

# when a user fails to be authenticated or authorized,

# invite them to login

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

&lt;Files login.html&gt;

# don't require user to already be logged in!

AuthDBDUserPWQuery \

"SELECT password FROM authn WHERE user = %s"

# 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

&lt;/Files&gt;

&lt;Files logout.html&gt;

# dbd-logout action executes a statement to log user out

Require dbd-logout

AuthzDBDQuery \

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

&lt;/Files&gt;

&lt;/Directory&gt;

</pre></example>

</section>

<directivesynopsis>

<name>AuthzDBDQuery</name>

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

<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="mod_authz_core">Require</directive> directive in

effect.</p>

<ul>

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

<example><title>Example</title><pre>

Require dbd-group

AuthzDBDQuery \

"SELECT group FROM groups WHERE user = %s"

</pre></example>

</li>

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

<example><title>Example</title><pre>

Require dbd-login

AuthzDBDQuery \

"UPDATE authn SET login = true WHERE user = %s"

</pre></example>

</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 <var>query</var></syntax>

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

<usage>

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

<example><title>Example</title><pre>

AuthzDBDRedirectQuery \

"SELECT userpage FROM userpages WHERE user = %s"

</pre></example>

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

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