granicus.if.org Git - apache/blob - docs/manual/mod/mod_authn_socache.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_socache.xml.meta">
  24
  25 <name>mod_authn_socache</name>
  26 <description>Manages a cache of authentication credentials to relieve
  27 the load on backends</description>
  28 <status>Base</status>
  29 <sourcefile>mod_authn_socache.c</sourcefile>
  30 <identifier>authn_socache_module</identifier>
  31 <compatibility>Version 2.3 and later</compatibility>
  32
  33 <summary>
  34     <p>Maintains a cache of authentication credentials, so that a new backend
  35     lookup is not required for every authenticated request.</p>
  36 </summary>
  37
  38 <section id="intro"><title>Authentication Cacheing</title>
  39     <p>Some users of more heavyweight authentication such as SQL database
  40     lookups (<module>mod_authn_dbd</module>) have reported it putting an
  41     unacceptable load on their authentication provider.  A typical case
  42     in point is where an HTML page contains hundreds of objects
  43     (images, scripts, stylesheets, media, etc), and a request to the page
  44     generates hundreds of effectively-immediate requests for authenticated
  45     additional contents.</p>
  46     <p>mod_authn_socache provides a solution to this problem by
  47     maintaining a cache of authentication credentials.</p>
  48 </section>
  49
  50 <section id="usage"><title>Usage</title>
  51     <p>The authentication cache should be used where authentication
  52     lookups impose a significant load on the server, or a backend or
  53     network.  Authentication by file (<module>mod_authn_file</module>)
  54     or dbm (<module>mod_authn_dbm</module>) are unlikely to benefit,
  55     as these are fast and lightweight in their own right (though in some
  56     cases, such as a network-mounted file, cacheing may be worthwhile).
  57     Other providers such as SQL or LDAP based authentication are more
  58     likely to benefit, particularly where there is an observed
  59     performance issue.  Amongst the standard modules, <module
  60     >mod_authnz_ldap</module> manages its own cache, so only
  61     <module>mod_authn_dbd</module> will usually benefit from this cache.</p>
  62     <p>The basic rules to cache for a provider are:</p>
  63     <ol><li>Include the provider you're cacheing for in an
  64             <directive>AuthnCacheProvideFor</directive> directive.</li>
  65         <li>List <var>socache</var> ahead of the provider you're
  66             cacheing for in your <directive module="mod_auth_basic"
  67             >AuthBasicProvider</directive> or <directive module=
  68             "mod_auth_digest">AuthDigestProvider</directive> directive.</li>
  69     </ol>
  70     <p>A simple usage example to accelerate <module>mod_authn_dbd</module>
  71     using dbm as a cache engine:</p>
  72     <highlight language="config">
  73 &lt;Directory /usr/www/myhost/private&gt;
  74     AuthType Basic
  75     AuthName "Cached Authentication Example"
  76     AuthBasicProvider socache dbd
  77     AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
  78     AuthnCacheProvideFor dbd
  79     AuthnCacheContext dbd-authn-example
  80     AuthnCacheSOCache dbm
  81     Require valid-user
  82 &lt;/Directory&gt;
  83     </highlight>
  84 </section>
  85
  86 <section id="dev"><title>Cacheing with custom modules</title>
  87     <p>Module developers should note that their modules must be enabled
  88     for cacheing with mod_authn_socache.  A single optional API function
  89     <var>ap_authn_cache_store</var> is provided to cache credentials
  90     a provider has just looked up or generated.  Usage examples are
  91     available in <a
  92     href="http://svn.eu.apache.org/viewvc?view=revision&amp;revision=957072"
  93     >r957072</a>, in which three authn providers are enabled for cacheing.</p>
  94 </section>
  95
  96 <directivesynopsis>
  97 <name>AuthnCacheEnable</name>
  98 <description>Enable Authn caching configured anywhere</description>
  99 <syntax>AuthnCacheEnable</syntax>
 100 <contextlist><context>server config</context></contextlist>
 101 <override>None</override>
 102
 103 <usage>
 104     <p>This directive is not normally necessary: it is implied if
 105     authentication cacheing is enabled anywhere in <var>httpd.conf</var>.
 106     However, if it is not enabled anywhere in <var>httpd.conf</var>
 107     it will by default not be initialised, and is therefore not
 108     available in a <var>.htaccess</var> context.  This directive
 109     ensures it is initialised so it can be used in <var>.htaccess</var>.</p>
 110 </usage>
 111 </directivesynopsis>
 112
 113 <directivesynopsis>
 114 <name>AuthnCacheSOCache</name>
 115 <description>Select socache backend provider to use</description>
 116 <syntax>AuthnCacheSOCache <var>provider-name</var></syntax>
 117 <contextlist><context>server config</context></contextlist>
 118 <override>None</override>
 119
 120 <usage>
 121     <p>This is a server-wide setting to select a provider for the
 122     <a href="../socache.html">shared object cache</a>.
 123     Values are "dbm", "dc", "memcache", or "shmcb", each subject to the
 124     appropriate module being loaded.  If not set, your platform's
 125        default will be used.</p>
 126 </usage>
 127 </directivesynopsis>
 128
 129 <directivesynopsis>
 130 <name>AuthnCacheProvideFor</name>
 131 <description>Specify which authn provider(s) to cache for</description>
 132 <syntax>AuthnCacheProvideFor <var>authn-provider</var> [...]</syntax>
 133 <default>None</default>
 134 <contextlist><context>directory</context><context>.htaccess</context></contextlist>
 135 <override>AuthConfig</override>
 136
 137 <usage>
 138     <p>This directive specifies an authentication provider or providers
 139     to cache for.  Credentials found by a provider not listed in an
 140     AuthnCacheProvideFor directive will not be cached.</p>
 141
 142     <p>For example, to cache credentials found by <module>mod_authn_dbd</module>
 143     or by a custom provider <var>myprovider</var>, but leave those looked
 144     up by lightweight providers like file or dbm lookup alone:</p>
 145     <highlight language="config">
 146 AuthnCacheProvideFor dbd myprovider
 147     </highlight>
 148 </usage>
 149 </directivesynopsis>
 150
 151 <directivesynopsis>
 152 <name>AuthnCacheTimeout</name>
 153 <description>Set a timeout for cache entries</description>
 154 <syntax>AuthnCacheTimeout <var>timeout</var> (seconds)</syntax>
 155 <default>300 (5 minutes)</default>
 156 <contextlist><context>directory</context><context>.htaccess</context></contextlist>
 157 <override>AuthConfig</override>
 158
 159 <usage>
 160     <p>Cacheing authentication data can be a security issue, though short-term
 161     cacheing is unlikely to be a problem.  Typically a good solution is to
 162     cache credentials for as long as it takes to relieve the load on a
 163     backend, but no longer, though if changes to your users and passwords
 164     are infrequent then a longer timeout may suit you.  The default 300
 165     seconds (5 minutes) is both cautious and ample to keep the load
 166     on a backend such as dbd (SQL database queries) down.</p>
 167     <p>This should not be confused with session timeout, which is an
 168     entirely separate issue.  However, you may wish to check your
 169     session-management software for whether cached credentials can
 170     "accidentally" extend a session, and bear it in mind when setting
 171     your timeout.</p>
 172 </usage>
 173 </directivesynopsis>
 174
 175 <directivesynopsis>
 176 <name>AuthnCacheContext</name>
 177 <description>Specify a context string for use in the cache key</description>
 178 <syntax>AuthnCacheContext <var>directory|server|custom-string</var></syntax>
 179 <default>directory</default>
 180 <contextlist><context>directory</context></contextlist>
 181
 182 <usage>
 183     <p>This directive specifies a string to be used along with the supplied
 184     username (and realm in the case of Digest Authentication) in constructing
 185     a cache key.  This serves to disambiguate identical usernames serving
 186     different authentication areas on the server.</p>
 187     <p>Two special values for this are <var>directory</var>, which uses
 188     the directory context of the request as a string, and <var>server</var>
 189     which uses the virtual host name.</p>
 190     <p>The default is <var>directory</var>, which is also the most
 191     conservative setting.  This is likely to be less than optimal, as it
 192     (for example) causes <var>$app-base</var>, <var>$app-base/images</var>,
 193     <var>$app-base/scripts</var> and <var>$app-base/media</var> each to
 194     have its own separate cache key.  A better policy is to name the
 195     <directive>AuthnCacheContext</directive> for the password
 196     provider: for example a <var>htpasswd</var> file or database table.</p>
 197     <p>Contexts can be shared across different areas of a server, where
 198     credentials are shared.  However, this has potential to become a vector
 199     for cross-site or cross-application security breaches, so this directive
 200     is not permitted in <var>.htaccess</var> contexts.</p>
 201 </usage>
 202 </directivesynopsis>
 203
 204 </modulesynopsis>
 205