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 <compatibility>Available in Apache 2.1 and later</compatibility>
  31
  32 <summary>
  33     <p>This module provides authentication front-ends such as
  34     <module>mod_auth_digest</module> and <module>mod_auth_basic</module>
  35     to authenticate users by looking up users in SQL tables.
  36     Similar functionality is provided by, for example,
  37     <module>mod_authn_file</module>.</p>
  38     <p>This module relies on <module>mod_dbd</module> to specify
  39     the backend database driver and connection parameters, and
  40     manage the database connections.</p>
  41
  42     <p>When using <module>mod_auth_basic</module> or
  43     <module>mod_auth_digest</module>, this module is invoked via the
  44     <directive module="mod_auth_basic">AuthBasicProvider</directive> or
  45     <directive module="mod_auth_digest">AuthDigestProvider</directive>
  46     with the <code>dbd</code> value.</p>
  47 </summary>
  48
  49 <seealso><directive module="mod_authn_core">AuthName</directive></seealso>
  50 <seealso><directive module="mod_authn_core">AuthType</directive></seealso>
  51 <seealso>
  52   <directive module="mod_auth_basic">AuthBasicProvider</directive>
  53 </seealso>
  54 <seealso>
  55   <directive module="mod_auth_digest">AuthDigestProvider</directive>
  56 </seealso>
  57 <seealso><directive module="mod_dbd">DBDriver</directive></seealso>
  58 <seealso><directive module="mod_dbd">DBDParams</directive></seealso>
  59
  60 <section id="example">
  61 <title>Configuration Example</title>
  62 <p>This simple example shows use of this module in the context of
  63 the Authentication and DBD frameworks.</p>
  64 <example><pre>
  65 # mod_dbd configuration
  66 DBDriver pgsql
  67 DBDParams "dbname=apacheauth user=apache password=xxxxxx"
  68
  69 DBDMin  4
  70 DBDKeep 8
  71 DBDMax  20
  72 DBDExptime 300
  73
  74 &lt;Directory /usr/www/myhost/private&gt;
  75   # mod_authn_core and mod_auth_basic configuration
  76   # for mod_authn_dbd
  77   AuthType Basic
  78   AuthName "My Server"
  79   AuthBasicProvider dbd
  80
  81   # mod_authz_core configuration
  82   Require valid-user
  83
  84   # mod_authn_dbd SQL query to authenticate a user
  85   AuthDBDUserPWQuery \
  86     "SELECT password FROM authn WHERE user = %s"
  87 &lt;/Directory&gt;
  88 </pre></example>
  89 </section>
  90
  91 <section id="exposed">
  92 <title>Exposing Login Information</title>
  93 <p>
  94 If httpd was built against <glossary>APR</glossary> version 1.3.0
  95 or higher, then whenever a query is made to the database server, all
  96 column values in the first row returned by the query are placed in the
  97 environment, using environment variables with the prefix "AUTHENTICATE_".
  98 </p>
  99 <p>If a database query for example returned the username, full name
 100 and telephone number of a user, a CGI program will have access to
 101 this information without the need to make a second independent database
 102 query to gather this additional information.</p>
 103 <p>This has the potential to dramatically simplify the coding and
 104 configuration required in some web applications.
 105 </p>
 106 </section>
 107
 108 <directivesynopsis>
 109 <name>AuthDBDUserPWQuery</name>
 110 <description>SQL query to look up a password for a user</description>
 111 <syntax>AuthDBDUserPWQuery <var>query</var></syntax>
 112 <contextlist><context>directory</context>
 113 </contextlist>
 114
 115 <usage>
 116     <p>The <directive>AuthDBDUserPWQuery</directive> specifies an
 117     SQL query to look up a password for a specified user.  The user's ID
 118     will be passed as a single string parameter when the SQL query is
 119     executed.  It may be referenced within the query statement using
 120     a <code>%s</code> format specifier.</p>
 121     <example><title>Example</title><pre>
 122 AuthDBDUserPWQuery \
 123   "SELECT password FROM authn WHERE user = %s"
 124 </pre></example>
 125     <p>The first column value of the first row returned by the query
 126     statement should be a string containing the encrypted password.
 127     Subsequent rows will be ignored.  If no rows are returned, the user
 128     will not be authenticated through <module>mod_authn_dbd</module>.</p>
 129     <p>If httpd was built against <glossary>APR</glossary> version 1.3.0
 130     or higher, any additional column values in the first row returned by
 131     the query statement will be stored as environment variables with
 132     names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
 133     </p>
 134 </usage>
 135 </directivesynopsis>
 136
 137 <directivesynopsis>
 138 <name>AuthDBDUserRealmQuery</name>
 139 <description>SQL query to look up a password hash for a user and realm.
 140 </description>
 141 <syntax>AuthDBDUserRealmQuery <var>query</var></syntax>
 142 <contextlist><context>directory</context>
 143 </contextlist>
 144
 145 <usage>
 146     <p>The <directive>AuthDBDUserRealmQuery</directive> specifies an
 147     SQL query to look up a password for a specified user and realm.
 148     The user's ID and the realm, in that order, will be passed as string
 149     parameters when the SQL query is executed.  They may be referenced
 150     within the query statement using <code>%s</code> format specifiers.</p>
 151     <example><title>Example</title><pre>
 152 AuthDBDUserRealmQuery \
 153   "SELECT password FROM authn WHERE user = %s AND realm = %s"
 154 </pre></example>
 155     <p>The first column value of the first row returned by the query
 156     statement should be a string containing the encrypted password.
 157     Subsequent rows will be ignored.  If no rows are returned, the user
 158     will not be authenticated through <module>mod_authn_dbd</module>.</p>
 159     <p>If httpd was built against <glossary>APR</glossary> version 1.3.0
 160     or higher, any additional column values in the first row returned by
 161     the query statement will be stored as environment variables with
 162     names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
 163     </p>
 164 </usage>
 165 </directivesynopsis>
 166
 167 </modulesynopsis>