mod_authz_dbd.xml revision 1f1b6bf13313fdd14a45e52e553d3ff28689b717
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
782d5365e084a40e4f717dafbe00fc41476a7cfeChristian Maeder<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
97018cf5fa25b494adffd7e9b4e87320dae6bf47Christian Maeder<!-- $LastChangedRevision$ -->
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder Licensed to the Apache Software Foundation (ASF) under one or more
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder contributor license agreements. See the NOTICE file distributed with
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder this work for additional information regarding copyright ownership.
f3a94a197960e548ecd6520bb768cb0d547457bbChristian Maeder The ASF licenses this file to You under the Apache License, Version 2.0
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder (the "License"); you may not use this file except in compliance with
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder the License. You may obtain a copy of the License at
25a0b76bc87e80c0f697951d9817862755a71d33Christian Maeder Unless required by applicable law or agreed to in writing, software
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder distributed under the License is distributed on an "AS IS" BASIS,
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder See the License for the specific language governing permissions and
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder limitations under the License.
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<modulesynopsis metafile="mod_authz_dbd.xml.meta">
ae179fb240298858539e0ff2b2e515d39ac17efcChristian Maeder<description>Group Authorization and Login using SQL</description>
41076bb5f87e3dbebb53d762ccb9795801b4a27aChristian Maeder<compatibility>Available in Apache 2.4 and later</compatibility>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder <p>This module provides authorization capabilities so that
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder authenticated users can be allowed or denied access to portions
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder of the web site by group membership. Similar functionality is
792df0347edab377785d98c63e2be8e2ce0a8bdeChristian Maeder provided by <module>mod_authz_groupfile</module> and
792df0347edab377785d98c63e2be8e2ce0a8bdeChristian Maeder <module>mod_authz_dbm</module>, with the exception that
ae179fb240298858539e0ff2b2e515d39ac17efcChristian Maeder this module queries a SQL database to determine whether a
ae179fb240298858539e0ff2b2e515d39ac17efcChristian Maeder user is a member of a group.</p>
ae179fb240298858539e0ff2b2e515d39ac17efcChristian Maeder <p>This module can also provide database-backed user login/logout
792df0347edab377785d98c63e2be8e2ce0a8bdeChristian Maeder capabilities. These are likely to be of most value when used
792df0347edab377785d98c63e2be8e2ce0a8bdeChristian Maeder in conjunction with <module>mod_authn_dbd</module>.</p>
792df0347edab377785d98c63e2be8e2ce0a8bdeChristian Maeder <p>This module relies on <module>mod_dbd</module> to specify
792df0347edab377785d98c63e2be8e2ce0a8bdeChristian Maeder the backend database driver and connection parameters, and
792df0347edab377785d98c63e2be8e2ce0a8bdeChristian Maeder manage the database connections.</p>
eca4db63ed0bdbd93b62678feea6e3eb80aa47bbChristian Maeder<seealso><directive module="mod_authz_core">Require</directive></seealso>
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maeder <directive module="mod_authn_dbd">AuthDBDUserPWQuery</directive>
782d5365e084a40e4f717dafbe00fc41476a7cfeChristian Maeder<seealso><directive module="mod_dbd">DBDriver</directive></seealso>
782d5365e084a40e4f717dafbe00fc41476a7cfeChristian Maeder<seealso><directive module="mod_dbd">DBDParams</directive></seealso>
a008ea3d3b5667969f058f75e9919f9b9c26260fChristian Maeder<section id="requiredirectives"><title>The Require Directives</title>
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maeder <p>Apache's <directive module="mod_authz_core">Require</directive>
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maeder directives are used during the authorization phase to ensure that
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maeder a user is allowed to access a resource. mod_authz_dbd extends the
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder authorization types with <code>dbd-group</code>, <code>dbd-login</code> and
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maeder <p>Since v2.4.8, <a href="/expr.html">expressions</a> are supported
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maeder within the DBD require directives.</p>
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder<section id="reqgroup"><title>Require dbd-group</title>
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder <p>This directive specifies group membership that is required for the
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder user to gain access.</p>
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder Require dbd-group team
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
a255351561838b3743d03c1629d335cfb8b83804Christian Maeder<section id="reqlogin"><title>Require dbd-login</title>
a255351561838b3743d03c1629d335cfb8b83804Christian Maeder <p>This directive specifies a query to be run indicating the user
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder has logged in.</p>
fe216849cef7b87c6800aad21178d1e686575d8fChristian Maeder Require dbd-login
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
02a2037f53b925617df45eb62ca743d777672265Klaus Luettich<section id="reqlogout"><title>Require dbd-logout</title>
5908cc06d7a3f4dd46d2d7c7fe0fad43b6cd921fChristian Maeder <p>This directive specifies a query to be run indicating the user
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder has logged out.</p>
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder Require dbd-logout
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian MaederIn addition to the standard authorization function of checking group
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maedermembership, this module can also provide server-side user session
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maedermanagement via database-backed login/logout capabilities.
41076bb5f87e3dbebb53d762ccb9795801b4a27aChristian MaederSpecifically, it can update a user's session status in the database
41076bb5f87e3dbebb53d762ccb9795801b4a27aChristian Maederwhenever the user visits designated URLs (subject of course to users
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maedersupplying the necessary credentials).</p>
41076bb5f87e3dbebb53d762ccb9795801b4a27aChristian Maeder<p>This works by defining two special
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder<directive module="mod_authz_core">Require</directive> types:
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder<code>Require dbd-login</code> and <code>Require dbd-logout</code>.
ee1ceac4345bc824210b2f7c6d6b182cb1902547Christian MaederFor usage details, see the configuration example below.</p>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<p>Some administrators may wish to implement client-side session
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maedermanagement that works in concert with the server-side login/logout
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maedercapabilities offered by this module, for example, by setting or unsetting
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maederan HTTP cookie or other such token when a user logs in or out.</p>
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder<p>To support such integration, <module>mod_authz_dbd</module> exports an
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maederoptional hook that will be run whenever a user's status is updated in
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maederthe database. Other session management modules can then use the hook
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maederto implement functions that start and end client-side sessions.</p>
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder# mod_dbd configuration
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian MaederDBDriver pgsql
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian MaederDBDParams "dbname=apacheauth user=apache pass=xxxxxx"
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian MaederDBDExptime 300
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder<Directory "/usr/www/my.site/team-private/">
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder # mod_authn_core and mod_auth_basic configuration
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder # for mod_authn_dbd
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder AuthType Basic
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder AuthName Team
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder AuthBasicProvider dbd
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder # mod_authn_dbd SQL query to authenticate a logged-in user
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder AuthDBDUserPWQuery \
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder "SELECT password FROM authn WHERE user = %s AND login = 'true'"
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder # mod_authz_core configuration for mod_authz_dbd
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder Require dbd-group team
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder # mod_authz_dbd configuration
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
88ece6e49930670e8fd3ee79c89a2e918d2fbd0cChristian Maeder # when a user fails to be authenticated or authorized,
88ece6e49930670e8fd3ee79c89a2e918d2fbd0cChristian Maeder # invite them to login; this page should provide a link
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder ErrorDocument 401 /login-info.html
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder <Files "login.html">
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder # don't require user to already be logged in!
36fcac4cf0f6a1f8a0fee696ac7f4b91d769843cChristian Maeder AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
c29fabd288a7c6c0b46e134f70b48138aae9214aChristian Maeder # dbd-login action executes a statement to log user in
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder Require dbd-login
0e2ae85e2453466d03c1fc5884a3d693235bb9d9Christian Maeder AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
0678d323bee844db79af13113ae252546629a594Christian Maeder # return user to referring page (if any) after
0678d323bee844db79af13113ae252546629a594Christian Maeder # successful login
c29fabd288a7c6c0b46e134f70b48138aae9214aChristian Maeder AuthzDBDLoginToReferer On
0678d323bee844db79af13113ae252546629a594Christian Maeder </Files>
36fcac4cf0f6a1f8a0fee696ac7f4b91d769843cChristian Maeder <Files "logout.html">
0678d323bee844db79af13113ae252546629a594Christian Maeder # dbd-logout action executes a statement to log user out
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder Require dbd-logout
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder </Files>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder</Directory>
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder <p>Whether you need to care about SQL security depends on what DBD driver
0678d323bee844db79af13113ae252546629a594Christian Maeder and backend you use. With most drivers you don't have to do anything :
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder the statement is prepared by the database at startup, and user input is
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder used only as data. But you may need to untaint your input. At the time
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder of writing, the only driver that requires you to take care is FreeTDS.</p>
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder <p>Please read <module>mod_dbd</module> documentation for more information
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder about security on this scope.</p>
0678d323bee844db79af13113ae252546629a594Christian Maeder<directivesynopsis>
0678d323bee844db79af13113ae252546629a594Christian Maeder<description>Specify the SQL Query for the required operation</description>
d183a4514d8a5b6a5d48d15a8dff52d0c96691eaChristian Maeder<syntax>AuthzDBDQuery <var>query</var></syntax>
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder<contextlist><context>directory</context></contextlist>
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>The <directive>AuthzDBDQuery</directive> specifies an SQL
0678d323bee844db79af13113ae252546629a594Christian Maeder query to run. The purpose of the query depends on the
a625226f55956c1dccb72888417d1f25db3cf173Christian Maeder <directive module="mod_authz_core">Require</directive> directive in
5e605dc61ff9ec5724c319603905dc9b0dccc05fChristian Maeder <li>When used with a <code>Require dbd-group</code> directive,
0678d323bee844db79af13113ae252546629a594Christian Maeder it specifies a query to look up groups for the current user. This is
0678d323bee844db79af13113ae252546629a594Christian Maeder the standard functionality of other authorization modules such as
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder <module>mod_authz_groupfile</module> and <module>mod_authz_dbm</module>.
0678d323bee844db79af13113ae252546629a594Christian Maeder The first column value of each row returned by the query statement
4fc4ac78b045c631bc979f849582d9e161568aacChristian Maeder should be a string containing a group name. Zero, one, or more rows
4fc4ac78b045c631bc979f849582d9e161568aacChristian Maeder may be returned.
0678d323bee844db79af13113ae252546629a594Christian MaederRequire dbd-group
0678d323bee844db79af13113ae252546629a594Christian MaederAuthzDBDQuery "SELECT group FROM groups WHERE user = %s"
0678d323bee844db79af13113ae252546629a594Christian Maeder <li>When used with a <code>Require dbd-login</code> or
0678d323bee844db79af13113ae252546629a594Christian Maeder <code>Require dbd-logout</code> directive, it will never deny access,
0678d323bee844db79af13113ae252546629a594Christian Maeder but will instead execute a SQL statement designed to log the user
0678d323bee844db79af13113ae252546629a594Christian Maeder in or out. The user must already be authenticated with
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian MaederRequire dbd-login
0678d323bee844db79af13113ae252546629a594Christian MaederAuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
f7d2e793728bbb7fd185e027eb9dfd7b9dd11c21Christian Maeder <p>In all cases, the user's ID will be passed as a single string
0678d323bee844db79af13113ae252546629a594Christian Maeder parameter when the SQL query is executed. It may be referenced within
0678d323bee844db79af13113ae252546629a594Christian Maeder the query statement using a <code>%s</code> format specifier.</p>
0678d323bee844db79af13113ae252546629a594Christian Maeder</directivesynopsis>
0678d323bee844db79af13113ae252546629a594Christian Maeder<directivesynopsis>
0678d323bee844db79af13113ae252546629a594Christian Maeder<description>Specify a query to look up a login page for the user</description>
0678d323bee844db79af13113ae252546629a594Christian Maeder<syntax>AuthzDBDRedirectQuery <var>query</var></syntax>
0678d323bee844db79af13113ae252546629a594Christian Maeder<contextlist><context>directory</context></contextlist>
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>Specifies an optional SQL query to use after successful login
0678d323bee844db79af13113ae252546629a594Christian Maeder (or logout) to redirect the user to a URL, which may be
0678d323bee844db79af13113ae252546629a594Christian Maeder specific to the user. The user's ID will be passed as a single string
e85b224577b78d08ba5c39fe9dcc2e53995454a2Christian Maeder parameter when the SQL query is executed. It may be referenced within
0678d323bee844db79af13113ae252546629a594Christian Maeder the query statement using a <code>%s</code> format specifier.</p>
0678d323bee844db79af13113ae252546629a594Christian MaederAuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"
0678d323bee844db79af13113ae252546629a594Christian Maeder <p>The first column value of the first row returned by the query