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.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="mod_authz_core">Require</directive></seealso>
  41 <seealso><directive module="mod_dbd">DBDriver</directive></seealso>
  42 <seealso><directive module="mod_dbd">DBDParams</directive></seealso>
  43
  44 <section id="login">
  45 <title>Database Login</title>
  46 <p>In addition to the standard authz function of checking group
  47 membership, this module provides database Login/Logout capability.
  48 Specifically, we can maintain a logged in/logged out status in
  49 the database, and control the status via designated URLs (subject
  50 of course to users supplying the necessary credentials).</p>
  51 <p>This works by defining two special
  52 <directive module="mod_authz_core">Require</directive> types:
  53 <code>Require dbd-login</code> and <code>Require dbd-logout</code>.
  54 For usage details, see the configuration example below.</p>
  55 </section>
  56
  57 <section id="client">
  58 <title>Client Login</title>
  59 <p>In conjunction with server login/logout, we may wish to implement
  60 clientside login/out, for example by setting and unsetting a cookie
  61 or other such token.  Although this is not the business of an authz
  62 module, client session management software should be able to tie its
  63 operation in to database login/logout.  To support this,
  64 <module>mod_authz_dbd</module> exports an optional hook that will
  65 be run whenever a user successfully logs into or out of the database.
  66 Session management modules can use the hook to implement functions
  67 to start and end a client session.</p>
  68 </section>
  69
  70 <section id="example">
  71 <title>Configuration Example</title>
  72 <example><pre>
  73 # mod_dbd configuration
  74 DBDriver pgsql
  75 DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
  76
  77 DBDMin  4
  78 DBDKeep 8
  79 DBDMax  20
  80 DBDExptime 300
  81
  82 &lt;Directory /usr/www/my.site/team-private/&gt;
  83   # mod_authn_core and mod_auth_basic configuration
  84   # for mod_authn_dbd
  85   AuthType Basic
  86   AuthName Team
  87   AuthBasicProvider dbd
  88
  89   # mod_authn_dbd SQL query to authenticate a logged-in user
  90   AuthDBDUserPWQuery \
  91     "SELECT password FROM authn WHERE user = %s AND login = true"
  92
  93   # mod_authz_core configuration for mod_authz_dbd
  94   Require dbd-group team
  95
  96   # mod_authz_dbd configuration
  97   AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
  98
  99   # when a user fails to be authenticated or authorized,
 100   # invite them to login
 101   ErrorDocument 401 /team-private/login-form.html
 102
 103   &lt;Files login.html&gt;
 104     # don't require user to already be logged in!
 105     AuthDBDUserPWQuery \
 106       "SELECT password FROM authn WHERE user = %s"
 107
 108     # dbd-login action executes a statement to log user in
 109     Require dbd-login
 110     AuthzDBDQuery \
 111       "UPDATE authn SET login = true WHERE user = %s"
 112
 113     # return user to referring page (if any) after
 114     # successful login
 115     AuthzDBDLoginToReferer On
 116   &lt;/Files&gt;
 117
 118   &lt;Files logout.html&gt;
 119     # dbd-logout action executes a statement to log user out
 120     Require dbd-logout
 121     AuthzDBDQuery \
 122       "UPDATE authn SET login = false WHERE user = %s"
 123   &lt;/Files&gt;
 124 &lt;/Directory&gt;
 125 </pre></example>
 126 </section>
 127
 128 <directivesynopsis>
 129 <name>AuthzDBDQuery</name>
 130 <description>Specify the SQL Query for the required operation</description>
 131 <syntax>AuthzDBDQuery <var>query</var></syntax>
 132 <contextlist><context>directory</context></contextlist>
 133
 134 <usage>
 135     <p>The <directive>AuthzDBDQuery</directive> specifies an SQL
 136     query to run.  The purpose of the query depends on the
 137     <directive module="mod_authz_core">Require</directive> directive in
 138     effect.</p>
 139     <ul>
 140     <li>When used with a <code>Require dbd-group</code> directive,
 141     it specifies a query to look up groups for the current user.  This is
 142     the standard functionality of other authorization modules such as
 143     <module>mod_authz_file</module> and <module>mod_authz_dbm</module>.
 144     The first column value of each row returned by the query statement
 145     should be a string containing a group name.  Zero, one, or more rows
 146     may be returned.
 147     <example><title>Example</title><pre>
 148 Require dbd-group
 149 AuthzDBDQuery \
 150   "SELECT group FROM groups WHERE user = %s"
 151 </pre></example>
 152     </li>
 153     <li>When used with a <code>Require dbd-login</code> or
 154     <code>Require dbd-logout</code> directive, it will never deny access,
 155     but will instead execute a SQL statement designed to log the user
 156     in or out.  The user must already be authenticated with
 157     <module>mod_authn_dbd</module>.
 158     <example><title>Example</title><pre>
 159 Require dbd-login
 160 AuthzDBDQuery \
 161   "UPDATE authn SET login = true WHERE user = %s"
 162 </pre></example>
 163     </li>
 164     </ul>
 165     <p>In all cases, the user's ID will be passed as a single string
 166     parameter when the SQL query is executed.  It may be referenced within
 167     the query statement using a <code>%s</code> format specifier.</p>
 168 </usage>
 169 </directivesynopsis>
 170
 171 <directivesynopsis>
 172 <name>AuthzDBDRedirectQuery</name>
 173 <description>Specify a query to look up a login page for the user</description>
 174 <syntax>AuthzDBDRedirectQuery <var>query</var></syntax>
 175 <contextlist><context>directory</context></contextlist>
 176
 177 <usage>
 178     <p>Specifies an optional SQL query to use after successful login
 179     (or logout) to redirect the user to a URL, which may be
 180     specific to the user.  The user's ID will be passed as a single string
 181     parameter when the SQL query is executed.  It may be referenced within
 182     the query statement using a <code>%s</code> format specifier.</p>
 183     <example><title>Example</title><pre>
 184 AuthzDBDRedirectQuery \
 185   "SELECT userpage FROM userpages WHERE user = %s"
 186 </pre></example>
 187     <p>The first column value of the first row returned by the query
 188     statement should be a string containing a URL to which to redirect
 189     the client.  Subsequent rows will be ignored.  If no rows are returned,
 190     the client will not be redirected.</p>
 191     <p>Note that <directive>AuthzDBDLoginToReferer</directive> takes
 192     precedence if both are set.</p>
 193 </usage>
 194 </directivesynopsis>
 195
 196 <directivesynopsis>
 197 <name>AuthzDBDLoginToReferer</name>
 198 <description>Determines whether to redirect the Client to the Referring
 199 page on successful login or logout if a <code>Referer</code> request
 200 header is present</description>
 201 <syntax>AuthzDBDLoginToReferer On|Off</syntax>
 202 <default>AuthzDBDLoginToReferer Off</default>
 203 <contextlist><context>directory</context></contextlist>
 204
 205 <usage>
 206     <p>In conjunction with <code>Require dbd-login</code> or
 207     <code>Require dbd-logout</code>, this provides the option to
 208     redirect the client back to the Referring page (the URL in
 209     the <code>Referer</code> HTTP request header, if present.
 210     When there is no <code>Referer</code> header,
 211     <code>AuthzDBDLoginToReferer On</code> will be ignored.</p>
 212 </usage>
 213 </directivesynopsis>
 214
 215 </modulesynopsis>