From: Nick Kew Date: Fri, 25 Jun 2010 14:12:16 +0000 (+0000) Subject: Make a start on documenting mod_authn_socache X-Git-Tag: 2.3.7~129 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f1da46def6978965b0f8e2f3b3c9d2b6f53c8ae5;p=apache Make a start on documenting mod_authn_socache git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@957958 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_authn_socache.xml b/docs/manual/mod/mod_authn_socache.xml new file mode 100644 index 0000000000..f339c51c21 --- /dev/null +++ b/docs/manual/mod/mod_authn_socache.xml @@ -0,0 +1,174 @@ + + + + + + + + +mod_authn_socache +Manages a cache of authentication credentials to relieve +the load on backends +Base +mod_authn_socache.c +authn_socache_module +Version 2.3 and later + + +

Maintains a cache of authentication credentials, so that a new backend + lookup is not required for every authenticated request.

+ + +
Authentication Cacheing +

Some users of more heavyweight authentication such as SQL database + lookups (mod_authn_dbd) have reported it putting an + unacceptable load on their authentication provider. A typical case + in point is where an HTML page contains hundreds of objects + (images, scripts, stylesheets, media, etc), and a request to the page + generates hundreds of effectively-immediate requests for authenticated + additional contents.

+

mod_authn_socache provides a solution to this problem by + maintaining a cache of authentication credentials.

+
+ +
Usage +

The authentication cache should be used where authentication + lookups impose a significant load on the server, or a backend or + network. Authentication by file (mod_authn_file) + or dbm (mod_authn_dbm) are unlikely to benefit, + as these are fast and lightweight in their own right (though in some + cases, such as a network-mounted file, cacheing may be worthwhile). + Other providers such as SQL, LDAP or Radius based authentication + are more likely to benefit, particularly where there is an observed + performance issue.

+

The basic rules to cache for a provider are:

+
  1. Include the provider you're cacheing for in an + AuthnCacheProvider directive.
    2. +
  2. List socache ahead of the provider you're + cacheing for in your AuthBasicProvider or AuthDigestProvider directive.
    3. +
+

A simple usage example to accelerate mod_authn_dbd + [TODO]

+
+ +
Cacheing with custom modules +

Module developers should note that their modules must be enabled + for cacheing with mod_authn_cache. A single optional API function + ap_authn_cache_store is provided to cache credentials + a provider has just looked up or generated. Usage examples are + available in r957072, in which three authn providers are enabled for cacheing.

+
+ + +AuthnCacheSOCache +Select socache backend provider to use +AuthnCacheSOCache provider-name +server config +None + + +

This is a server-wide setting. If not set, your platform's + default will be used.

+ socache +

The cache is built on the the socache framework. + We need a link here once that's documented!

+ + + + + +AuthnCacheProvider +Specify which authn provider(s) to cache for +AuthnCacheProvider authn-provider [...] +directory.htaccess +AuthConfig +None + + +

This directive specifies an authentication provider or providers + to cache for. Credentials found by a provider not listed in an + AuthnCacheProvider directive will not be cached.

+ +

For example, to cache credentials found by mod_authn_dbd + or by a custom provider myprovider, but leave those looked + up by lightweight providers like file or dbm lookup alone:

+ + AuthnCacheProvider dbd myprovider + + + + + +AuthnCacheTimeout +Set a timeout for cache entries +AuthnCacheTimeout timeout (seconds) +directory.htaccess +AuthConfig +300 (5 minutes) + + +

Cacheing authentication data can be a security issue, though short-term + cacheing is unlikely to be a problem. Typically a good solution is to + cache credentials for as long as it takes to relieve the load on a + backend, but no longer, though if changes to your users and passwords + are infrequent then a longer timeout may suit you. The default 300 + seconds (5 minutes) is both cautious and ample to keep the load + on a backend such as dbd (SQL database queries) down.

+

This should not be confused with session timeout, which is an + entirely separate issue. However, you may wish to check your + session-management software for whether cached credentials can + "accidentally" extend a session, and bear it in mind when setting + your timeout.

+ + + + +AuthnCacheContext +Specify a context string for use in the cache key +AuthnCacheContext directory|server|custom-string +directory +directory + + +

This directive specifies a string to be used along with the supplied + username (and realm in the case of Digest Authentication) in constructing + a cache key. This serves to disambiguate identical usernames serving + different authentication areas on the server.

+

Two special values for this are directory, which uses + the directory context of the request as a string, and server + which uses the virtual host name.

+

The default is directory, which is also the most + conservative setting. This is likely to be less than optimal, as it + (for example) causes $app-base, $app-base/images, + $app-base/scripts and $app-base/media each to + have its own separate cache key. A better policy is to name the + AuthnCacheContext for the password + provider: for example a htpasswd file or database table.

+

Contexts can be shared across different areas of a server, where + credentials are shared. However, this has potential to become a vector + for cross-site or cross-application security breaches, so this directive + is not permitted in .htaccess contexts.

+ + + + +