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  Copyright 2002-2005 The Apache Software Foundation or its licensors, as
   8  applicable.
   9
  10  Licensed under the Apache License, Version 2.0 (the "License");
  11  you may not use this file except in compliance with the License.
  12  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.2 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. It also provides
  36        database/backend login/logout in conjunction with
  37        <module>mod_authn_dbd</module>.</p>
  38 </summary>
  39
  40 <seealso><directive module="core">Require</directive></seealso>
  41 <seealso><directive module="core">Satisfy</directive></seealso>
  42 <seealso><directive module="mod_dbd">DBDriver</directive></seealso>
  43 <seealso><directive module="mod_dbd">DBDParams</directive></seealso>
  44
  45 <section id="login">
  46 <title>Database Login</title>
  47 <p>In addition to the standard authz function of checking group
  48 membership, this module provides database Login/Logout capability.
  49 Specifically, we can maintain a logged in/logged out status in
  50 the database, and control the status via designated URLs (subject
  51 of course to users supplying the necessary credentials).</p>
  52 <p>This works by defining two special
  53 <directive module="core">Require</directive> types:
  54 <code>Require dbd-login</code> and <code>Require dbd-logout</code>.
  55 For usage details, see the configuration example below.</p>
  56 </section>
  57
  58 <section id="client">
  59 <title>Client Login</title>
  60 <p>In conjunction with server login/logout, we may wish to implement
  61 clientside login/out, for example by setting and unsetting a cookie
  62 or other such token.  Although this is not the business of an authz
  63 module, client session management software should be able to tie its
  64 operation in to database login/logout.  To support this,
  65 <module>mod_authz_dbd</module> exports an optional hook that will
  66 be run whenever a user successfully logs into or out of the database.
  67 Session management modules can use the hook to implement functions
  68 to start and end a client session.</p>
  69 </section>
  70
  71 <section id="example">
  72 <title>Configuration Example</title>
  73 <example><pre><code>
  74 # DBD Configuration
  75 DBDriver oracle
  76 DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
  77
  78 DBDMin  4
  79 DBDKeep 8
  80 DBDMax  20
  81 DBDExptime 300
  82
  83 &lt;Directory /usr/www/my.site/team-private/&gt;
  84    # authn with mod_authn_dbd
  85    AuthType Basic
  86    AuthName Team
  87    AuthBasicProvider dbd
  88    AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s AND login = true"
  89
  90    # Require dbd-group and authz_dbd implementation
  91    Require dbd-group team
  92    AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
  93
  94    # When a user fails to authn/authz, invite them to login
  95    ErrorDocument 401 /team-private/login-form.html
  96
  97    &lt;Files login.html&gt;
  98       # Don't require that we're already logged in!
  99       AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s"
 100
 101       # dbd-login action executes a query to set our own state
 102       Require dbd-login
 103       AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"
 104
 105       # Return user to referring page (if any) on successful login
 106       AuthzDBDLoginToReferer On
 107    &lt;/Files&gt;
 108
 109    &lt;Files logout.html&gt;
 110       # dbd-logout action executes a query to set our own state
 111       Require dbd-logout
 112       AuthzDBDQuery "UPDATE authn SET login = false WHERE user = %s"
 113    &lt;/Files&gt;
 114 &lt;/Directory&gt;
 115 </code></pre>
 116 </example>
 117 </section>
 118
 119 <directivesynopsis>
 120 <name>AuthzDBDQuery</name>
 121 <description>Specify the SQL Query for the required operation</description>
 122 <syntax>AuthzDBDQuery SQL-Query</syntax>
 123 <contextlist><context>directory</context></contextlist>
 124
 125 <usage>
 126     <p>The <directive>AuthzDBDQuery</directive> specifies an SQL
 127     query to run.  The purpose of the query depends on the
 128     <directive module="core">Require</directive> directive in
 129     effect.</p>
 130     <ul>
 131     <li>With <code>Require dbd-group</code>, it specifies a query
 132     to look up groups for the current user.  This is the standard
 133     functionality of other authz modules such as
 134     <module>mod_authz_file</module> and <module>mod_authz_dbm</module>.
 135     In this case it will typically take the form<br/>
 136     <code>AuthzDBDQuery "SELECT group FROM groups WHERE user= %s"</code>
 137     </li>
 138     <li>With <code>Require dbd-login</code> or <code>Require dbd-logout</code>,
 139     it will never deny access, but will instead execute an SQL Query
 140     designed to log the user (who must already be authenticated with
 141     <module>mod_authn_dbd</module>) in or out.  Such a query will
 142     typically take the form<br/>
 143     <code>AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"</code>
 144     </li>
 145     </ul>
 146 </usage>
 147 </directivesynopsis>
 148
 149 <directivesynopsis>
 150 <name>AuthzDBDRedirectQuery</name>
 151 <description>Specify a query to look up a login page for the user</description>
 152 <syntax>AuthzDBDRedirectQuery SQL-Query</syntax>
 153 <contextlist><context>directory</context></contextlist>
 154
 155 <usage>
 156     <p>Specifies an optional query to use after successful login
 157     (or logout) to redirect the user to a page, which may be
 158     specific to the user.  Such a query will take the form<br/>
 159     <code>AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"</code>
 160     </p>
 161     <p>Note that <directive>AuthzDBDLoginToReferer</directive> takes
 162     precedence if both are set.</p>
 163 </usage>
 164 </directivesynopsis>
 165
 166 <directivesynopsis>
 167 <name>AuthzDBDLoginToReferer</name>
 168 <description>Determines whether to redirect the Client to the Referring
 169 page on successful login or logout if a <code>Referer</code> request
 170 header is present</description>
 171 <syntax>AuthzDBDLoginToReferer On|Off</syntax>
 172 <default>AuthzDBDLoginToReferer Off</default>
 173 <contextlist><context>directory</context></contextlist>
 174
 175 <usage>
 176     <p>In conjunction with <code>Require dbd-login</code> or
 177     <code>Require dbd-logout</code>, this provides the option to
 178     redirect the client back to the Referring page (the URL in
 179     the <code>Referer</code> HTTP request header, if present.
 180     When there is no <code>Referer</code> header,
 181     <code>AuthzDBDLoginToReferer On</code> will be ignored.</p>
 182 </usage>
 183 </directivesynopsis>
 184
 185 <directivesynopsis>
 186 <name>AuthzDBDAuthoritative</name>
 187 <description>Sets whether authorization will be passed on to lower level
 188 modules</description>
 189 <syntax>AuthzDBDAuthoritative On|Off</syntax>
 190 <default>AuthzDBDAuthoritative On</default>
 191 <contextlist><context>directory</context></contextlist>
 192
 193 <usage>
 194     <p>Setting the <directive>AuthzDBDAuthoritative</directive>
 195     directive explicitly to <code>Off</code> allows group authorization
 196     to be handled by another authz module if the userID is not
 197     in any authorized dbd-group. If there are any groups
 198     specified, the usual checks will be applied and a failure will
 199     give an Authentication Required reply.</p>
 200
 201     <p>So if a userID appears in the database of more than one module;
 202     or if a valid <directive module="core">Require</directive>
 203     directive applies to more than one module; then the first module
 204     will verify the credentials; and no access is passed on;
 205     regardless of the <directive>AuthAuthoritative</directive> setting.</p>
 206
 207     <p>A common use for this is in conjunction with one of the
 208     auth providers; such or
 209     <module>mod_authn_file</module>. Whereas this DBD module supplies
 210     the bulk of the user credential checking; a few (administrator) related
 211     accesses fall through to a lower level with a well protected
 212     <code>.htpasswd</code> file.</p>
 213
 214     <p>By default, control is not passed on and an unknown group
 215     will result in an Authentication Required reply. Not
 216     setting it thus keeps the system secure and forces an NCSA
 217     compliant behaviour.</p>
 218 </usage>
 219 </directivesynopsis>
 220
 221 </modulesynopsis>