path: root/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$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You 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.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.  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="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="login">
<title>Database Login</title>
<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="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>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.
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>
# 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; this page should provide a link
  # to /team-private/login.html
  ErrorDocument 401 /login-info.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_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.
    <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>