granicus.if.org Git - apache/blob - docs/manual/mod/mod_authn_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_authn_dbd.xml.meta">
  24
  25 <name>mod_authn_dbd</name>
  26 <description>User authentication using an SQL database</description>
  27 <status>Extension</status>
  28 <sourcefile>mod_authn_dbd.c</sourcefile>
  29 <identifier>authn_dbd_module</identifier>
  30
  31 <summary>
  32     <p>This module provides authentication front-ends such as
  33     <module>mod_auth_digest</module> and <module>mod_auth_basic</module>
  34     to authenticate users by looking up users in SQL tables.
  35     Similar functionality is provided by, for example,
  36     <module>mod_authn_file</module>.</p>
  37     <p>This module relies on <module>mod_dbd</module> to specify
  38     the backend database driver and connection parameters, and
  39     manage the database connections.</p>
  40
  41     <p>When using <module>mod_auth_basic</module> or
  42     <module>mod_auth_digest</module>, this module is invoked via the
  43     <directive module="mod_auth_basic">AuthBasicProvider</directive> or
  44     <directive module="mod_auth_digest">AuthDigestProvider</directive>
  45     with the <code>dbd</code> value.</p>
  46 </summary>
  47
  48 <seealso><directive module="mod_authn_core">AuthName</directive></seealso>
  49 <seealso><directive module="mod_authn_core">AuthType</directive></seealso>
  50 <seealso>
  51   <directive module="mod_auth_basic">AuthBasicProvider</directive>
  52 </seealso>
  53 <seealso>
  54   <directive module="mod_auth_digest">AuthDigestProvider</directive>
  55 </seealso>
  56 <seealso><directive module="mod_dbd">DBDriver</directive></seealso>
  57 <seealso><directive module="mod_dbd">DBDParams</directive></seealso>
  58 <seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso>
  59
  60 <section id="socache">
  61 <title>Performance and Cacheing</title>
  62 <p>Some users of DBD authentication in HTTPD 2.2/2.4 have reported that it
  63 imposes a problematic load on the database.  This is most likely where
  64 an HTML page contains hundreds of objects (e.g. images, scripts, etc)
  65 each of which requires authentication.  Users affected (or concerned)
  66 by this kind of problem should use <module>mod_authn_socache</module>
  67 to cache credentials and take most of the load off the database.</p>
  68 </section>
  69
  70 <section id="example">
  71 <title>Configuration Example</title>
  72 <p>This simple example shows use of this module in the context of
  73 the Authentication and DBD frameworks.</p>
  74 <highlight language="config">
  75 # mod_dbd configuration
  76 # UPDATED to include authentication cacheing
  77 DBDriver pgsql
  78 DBDParams "dbname=apacheauth user=apache password=xxxxxx"
  79
  80 DBDMin  4
  81 DBDKeep 8
  82 DBDMax  20
  83 DBDExptime 300
  84
  85 &lt;Directory /usr/www/myhost/private&gt;
  86   # mod_authn_core and mod_auth_basic configuration
  87   # for mod_authn_dbd
  88   AuthType Basic
  89   AuthName "My Server"
  90
  91   # To cache credentials, put socache ahead of dbd here
  92   AuthBasicProvider socache dbd
  93
  94   # Also required for caching: tell the cache to cache dbd lookups!
  95   AuthnCacheProvideFor dbd
  96   AuthnCacheContext my-server
  97
  98   # mod_authz_core configuration
  99   Require valid-user
 100
 101   # mod_authn_dbd SQL query to authenticate a user
 102   AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
 103 &lt;/Directory&gt;
 104 </highlight>
 105 </section>
 106
 107 <section id="exposed">
 108 <title>Exposing Login Information</title>
 109 <p>
 110 If httpd was built against <glossary>APR</glossary> version 1.3.0
 111 or higher, then whenever a query is made to the database server, all
 112 column values in the first row returned by the query are placed in the
 113 environment, using environment variables with the prefix "AUTHENTICATE_".
 114 </p>
 115 <p>If a database query for example returned the username, full name
 116 and telephone number of a user, a CGI program will have access to
 117 this information without the need to make a second independent database
 118 query to gather this additional information.</p>
 119 <p>This has the potential to dramatically simplify the coding and
 120 configuration required in some web applications.
 121 </p>
 122 </section>
 123
 124 <section id="security">
 125 <title>Preventing SQL injections</title>
 126   <p>Whether you need to care about SQL security depends on what DBD driver
 127   and backend you use.  With most drivers you don't have to do anything :
 128   the statement is prepared by the database at startup, and user input is
 129   used only as data.  But you may need to untaint your input.  At the time
 130   of writing, the only driver that requires you to take care is FreeTDS.</p>
 131   <p>Please read <module>mod_dbd</module> documentation for more information
 132   about security on this scope.</p>
 133 </section>
 134
 135 <directivesynopsis>
 136 <name>AuthDBDUserPWQuery</name>
 137 <description>SQL query to look up a password for a user</description>
 138 <syntax>AuthDBDUserPWQuery <var>query</var></syntax>
 139 <contextlist><context>directory</context>
 140 </contextlist>
 141
 142 <usage>
 143     <p>The <directive>AuthDBDUserPWQuery</directive> specifies an
 144     SQL query to look up a password for a specified user.  The user's ID
 145     will be passed as a single string parameter when the SQL query is
 146     executed.  It may be referenced within the query statement using
 147     a <code>%s</code> format specifier.</p>
 148     <highlight language="config">
 149 AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
 150 </highlight>
 151     <p>The first column value of the first row returned by the query
 152     statement should be a string containing the encrypted password.
 153     Subsequent rows will be ignored.  If no rows are returned, the user
 154     will not be authenticated through <module>mod_authn_dbd</module>.</p>
 155     <p>If httpd was built against <glossary>APR</glossary> version 1.3.0
 156     or higher, any additional column values in the first row returned by
 157     the query statement will be stored as environment variables with
 158     names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
 159     </p>
 160     <p>The encrypted password format depends on which authentication
 161     frontend (e.g. <module>mod_auth_basic</module> or
 162     <module>mod_auth_digest</module>) is being used.  See <a
 163     href="../misc/password_encryptions.html">Password Formats</a> for
 164     more information.</p>
 165 </usage>
 166 </directivesynopsis>
 167
 168 <directivesynopsis>
 169 <name>AuthDBDUserRealmQuery</name>
 170 <description>SQL query to look up a password hash for a user and realm.
 171 </description>
 172 <syntax>AuthDBDUserRealmQuery <var>query</var></syntax>
 173 <contextlist><context>directory</context>
 174 </contextlist>
 175
 176 <usage>
 177     <p>The <directive>AuthDBDUserRealmQuery</directive> specifies an
 178     SQL query to look up a password for a specified user and realm in a
 179     digest authentication process.
 180     The user's ID and the realm, in that order, will be passed as string
 181     parameters when the SQL query is executed.  They may be referenced
 182     within the query statement using <code>%s</code> format specifiers.</p>
 183     <highlight language="config">
 184 AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s"
 185 </highlight>
 186     <p>The first column value of the first row returned by the query
 187     statement should be a string containing the encrypted password.
 188     Subsequent rows will be ignored.  If no rows are returned, the user
 189     will not be authenticated through <module>mod_authn_dbd</module>.</p>
 190     <p>If httpd was built against <glossary>APR</glossary> version 1.3.0
 191     or higher, any additional column values in the first row returned by
 192     the query statement will be stored as environment variables with
 193     names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
 194     </p>
 195     <p>The encrypted password format depends on which authentication
 196     frontend (e.g. <module>mod_auth_basic</module> or
 197     <module>mod_auth_digest</module>) is being used.  See <a
 198     href="../misc/password_encryptions.html">Password Formats</a> for
 199     more information.</p>
 200 </usage>
 201 </directivesynopsis>
 202
 203 </modulesynopsis>