docs/manual/mod/mod_authz_dbd.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Copyright 2002-2005 The Apache Software Foundation or its licensors, as
 applicable.

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