granicus.if.org Git - apache/blob - docs/manual/mod/mod_authz_dbd.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_authz_dbd.xml.meta">
  24
  25 <name>mod_authz_dbd</name>
  26 <description>Group Authorization and Login using SQL</description>
  27 <status>Extension</status>
  28 <sourcefile>mod_authz_dbd.c</sourcefile>
  29 <identifier>authz_dbd_module</identifier>
  30 <compatibility>Available in Apache 2.4 and later</compatibility>
  31
  32 <summary>
  33     <p>This module provides authorization capabilities so that
  34        authenticated users can be allowed or denied access to portions
  35        of the web site by group membership.  Similar functionality is
  36        provided by <module>mod_authz_groupfile</module> and
  37        <module>mod_authz_dbm</module>, with the exception that
  38        this module queries a SQL database to determine whether a
  39        user is a member of a group.</p>
  40     <p>This module can also provide database-backed user login/logout
  41        capabilities.  These are likely to be of most value when used
  42        in conjunction with <module>mod_authn_dbd</module>.</p>
  43     <p>This module relies on <module>mod_dbd</module> to specify
  44        the backend database driver and connection parameters, and
  45        manage the database connections.</p>
  46 </summary>
  47
  48 <seealso><directive module="mod_authz_core">Require</directive></seealso>
  49 <seealso>
  50   <directive module="mod_authz_core">AuthzMergeRules</directive>
  51 </seealso>
  52 <seealso>
  53   <directive module="mod_authn_dbd">AuthDBDUserPWQuery</directive>
  54 </seealso>
  55 <seealso><directive module="mod_dbd">DBDriver</directive></seealso>
  56 <seealso><directive module="mod_dbd">DBDParams</directive></seealso>
  57
  58 <section id="login">
  59 <title>Database Login</title>
  60 <p>
  61 In addition to the standard authorization function of checking group
  62 membership, this module can also provide server-side user session
  63 management via database-backed login/logout capabilities.
  64 Specifically, it can update a user's session status in the database
  65 whenever the user visits designated URLs (subject of course to users
  66 supplying the necessary credentials).</p>
  67 <p>This works by defining two special
  68 <directive module="mod_authz_core">Require</directive> types:
  69 <code>Require dbd-login</code> and <code>Require dbd-logout</code>.
  70 For usage details, see the configuration example below.</p>
  71 </section>
  72
  73 <section id="client">
  74 <title>Client Login</title>
  75 <p>Some administrators may wish to implement client-side session
  76 management that works in concert with the server-side login/logout
  77 capabilities offered by this module, for example, by setting or unsetting
  78 an HTTP cookie or other such token when a user logs in or out.
  79 To support such integration, <module>mod_authz_dbd</module> exports an
  80 optional hook that will be run whenever a user's status is updated in
  81 the database.  Other session management modules can then use the hook
  82 to implement functions that start and end client-side sessions.</p>
  83 </section>
  84
  85 <section id="example">
  86 <title>Configuration Example</title>
  87 <example><pre>
  88 # mod_dbd configuration
  89 DBDriver pgsql
  90 DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
  91
  92 DBDMin  4
  93 DBDKeep 8
  94 DBDMax  20
  95 DBDExptime 300
  96
  97 &lt;Directory /usr/www/my.site/team-private/&gt;
  98   # mod_authn_core and mod_auth_basic configuration
  99   # for mod_authn_dbd
 100   AuthType Basic
 101   AuthName Team
 102   AuthBasicProvider dbd
 103
 104   # mod_authn_dbd SQL query to authenticate a logged-in user
 105   AuthDBDUserPWQuery \
 106     "SELECT password FROM authn WHERE user = %s AND login = 'true'"
 107
 108   # mod_authz_core configuration for mod_authz_dbd
 109   AuthzMergeRules Off
 110   Require dbd-group team
 111
 112   # mod_authz_dbd configuration
 113   AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
 114
 115   # when a user fails to be authenticated or authorized,
 116   # invite them to login; this page should provide a link
 117   # to /team-private/login.html
 118   ErrorDocument 401 /login-info.html
 119
 120   &lt;Files login.html&gt;
 121     # don't require user to already be logged in!
 122     AuthDBDUserPWQuery \
 123       "SELECT password FROM authn WHERE user = %s"
 124
 125     # dbd-login action executes a statement to log user in
 126     AuthzMergeRules Off
 127     Require dbd-login
 128     AuthzDBDQuery \
 129       "UPDATE authn SET login = 'true' WHERE user = %s"
 130
 131     # return user to referring page (if any) after
 132     # successful login
 133     AuthzDBDLoginToReferer On
 134   &lt;/Files&gt;
 135
 136   &lt;Files logout.html&gt;
 137     # dbd-logout action executes a statement to log user out
 138     AuthzMergeRules Off
 139     Require dbd-logout
 140     AuthzDBDQuery \
 141       "UPDATE authn SET login = 'false' WHERE user = %s"
 142   &lt;/Files&gt;
 143 &lt;/Directory&gt;
 144 </pre></example>
 145 </section>
 146
 147 <directivesynopsis>
 148 <name>AuthzDBDQuery</name>
 149 <description>Specify the SQL Query for the required operation</description>
 150 <syntax>AuthzDBDQuery <var>query</var></syntax>
 151 <contextlist><context>directory</context></contextlist>
 152
 153 <usage>
 154     <p>The <directive>AuthzDBDQuery</directive> specifies an SQL
 155     query to run.  The purpose of the query depends on the
 156     <directive module="mod_authz_core">Require</directive> directive in
 157     effect.</p>
 158     <ul>
 159     <li>When used with a <code>Require dbd-group</code> directive,
 160     it specifies a query to look up groups for the current user.  This is
 161     the standard functionality of other authorization modules such as
 162     <module>mod_authz_file</module> and <module>mod_authz_dbm</module>.
 163     The first column value of each row returned by the query statement
 164     should be a string containing a group name.  Zero, one, or more rows
 165     may be returned.
 166     <example><title>Example</title><pre>
 167 Require dbd-group
 168 AuthzDBDQuery \
 169   "SELECT group FROM groups WHERE user = %s"
 170 </pre></example>
 171     </li>
 172     <li>When used with a <code>Require dbd-login</code> or
 173     <code>Require dbd-logout</code> directive, it will never deny access,
 174     but will instead execute a SQL statement designed to log the user
 175     in or out.  The user must already be authenticated with
 176     <module>mod_authn_dbd</module>.
 177     <example><title>Example</title><pre>
 178 Require dbd-login
 179 AuthzDBDQuery \
 180   "UPDATE authn SET login = 'true' WHERE user = %s"
 181 </pre></example>
 182     </li>
 183     </ul>
 184     <p>In all cases, the user's ID will be passed as a single string
 185     parameter when the SQL query is executed.  It may be referenced within
 186     the query statement using a <code>%s</code> format specifier.</p>
 187 </usage>
 188 </directivesynopsis>
 189
 190 <directivesynopsis>
 191 <name>AuthzDBDRedirectQuery</name>
 192 <description>Specify a query to look up a login page for the user</description>
 193 <syntax>AuthzDBDRedirectQuery <var>query</var></syntax>
 194 <contextlist><context>directory</context></contextlist>
 195
 196 <usage>
 197     <p>Specifies an optional SQL query to use after successful login
 198     (or logout) to redirect the user to a URL, which may be
 199     specific to the user.  The user's ID will be passed as a single string
 200     parameter when the SQL query is executed.  It may be referenced within
 201     the query statement using a <code>%s</code> format specifier.</p>
 202     <example><title>Example</title><pre>
 203 AuthzDBDRedirectQuery \
 204   "SELECT userpage FROM userpages WHERE user = %s"
 205 </pre></example>
 206     <p>The first column value of the first row returned by the query
 207     statement should be a string containing a URL to which to redirect
 208     the client.  Subsequent rows will be ignored.  If no rows are returned,
 209     the client will not be redirected.</p>
 210     <p>Note that <directive>AuthzDBDLoginToReferer</directive> takes
 211     precedence if both are set.</p>
 212 </usage>
 213 </directivesynopsis>
 214
 215 <directivesynopsis>
 216 <name>AuthzDBDLoginToReferer</name>
 217 <description>Determines whether to redirect the Client to the Referring
 218 page on successful login or logout if a <code>Referer</code> request
 219 header is present</description>
 220 <syntax>AuthzDBDLoginToReferer On|Off</syntax>
 221 <default>AuthzDBDLoginToReferer Off</default>
 222 <contextlist><context>directory</context></contextlist>
 223
 224 <usage>
 225     <p>In conjunction with <code>Require dbd-login</code> or
 226     <code>Require dbd-logout</code>, this provides the option to
 227     redirect the client back to the Referring page (the URL in
 228     the <code>Referer</code> HTTP request header, if present.
 229     When there is no <code>Referer</code> header,
 230     <code>AuthzDBDLoginToReferer On</code> will be ignored.</p>
 231 </usage>
 232 </directivesynopsis>
 233
 234 </modulesynopsis>