| <?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="requiredirectives"><title>The Require Directives</title> |
| |
| <p>Apache's <directive module="mod_authz_core">Require</directive> |
| directives are used during the authorization phase to ensure that |
| a user is allowed to access a resource. mod_authz_dbd extends the |
| authorization types with <code>dbd-group</code>, <code>dbd-login</code> and |
| <code>dbd-logout</code>.</p> |
| |
| <p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported |
| within the DBD require directives.</p> |
| |
| <section id="reqgroup"><title>Require dbd-group</title> |
| |
| <p>This directive specifies group membership that is required for the |
| user to gain access.</p> |
| |
| <highlight language="config"> |
| Require dbd-group team |
| AuthzDBDQuery "SELECT group FROM authz WHERE user = %s" |
| </highlight> |
| |
| </section> |
| |
| <section id="reqlogin"><title>Require dbd-login</title> |
| |
| <p>This directive specifies a query to be run indicating the user |
| has logged in.</p> |
| |
| <highlight language="config"> |
| Require dbd-login |
| AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s" |
| </highlight> |
| |
| </section> |
| |
| <section id="reqlogout"><title>Require dbd-logout</title> |
| |
| <p>This directive specifies a query to be run indicating the user |
| has logged out.</p> |
| |
| <highlight language="config"> |
| Require dbd-logout |
| AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s" |
| </highlight> |
| |
| </section> |
| |
| </section> |
| |
| <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 integration</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.</p> |
| <p>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> |
| <highlight language="config"> |
| # mod_dbd configuration |
| DBDriver pgsql |
| DBDParams "dbname=apacheauth user=apache pass=xxxxxx" |
| |
| DBDMin 4 |
| DBDKeep 8 |
| DBDMax 20 |
| DBDExptime 300 |
| |
| <Directory "/usr/www/my.site/team-private/"> |
| # 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 |
| |
| <Files "login.html"> |
| # 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 |
| </Files> |
| |
| <Files "logout.html"> |
| # dbd-logout action executes a statement to log user out |
| Require dbd-logout |
| AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s" |
| </Files> |
| </Directory> |
| </highlight> |
| </section> |
| |
| <section id="security"> |
| <title>Preventing SQL injections</title> |
| <p>Whether you need to care about SQL security depends on what DBD driver |
| and backend you use. With most drivers you don't have to do anything : |
| the statement is prepared by the database at startup, and user input is |
| used only as data. But you may need to untaint your input. At the time |
| of writing, the only driver that requires you to take care is FreeTDS.</p> |
| <p>Please read <module>mod_dbd</module> documentation for more information |
| about security on this scope.</p> |
| </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. |
| <highlight language="config"> |
| Require dbd-group |
| AuthzDBDQuery "SELECT group FROM groups WHERE user = %s" |
| </highlight> |
| </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>. |
| <highlight language="config"> |
| Require dbd-login |
| AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s" |
| </highlight> |
| </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> |
| <highlight language="config"> |
| AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s" |
| </highlight> |
| <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> |