[Mod-auth-commit] mod_auth_webspace/htdocs/docs/mod_authn_dbi index.xml,1.8,1.9
Brought to you by:
firechipmunk,
honx
Menu
▾
▴
[Mod-auth-commit] mod_auth_webspace/htdocs/docs/mod_authn_dbi index.xml,1.8,1.9
|
From: <ho...@us...> - 2003-12-02 03:57:01
|
Update of /cvsroot/mod-auth/mod_auth_webspace/htdocs/docs/mod_authn_dbi
In directory sc8-pr-cvs1:/tmp/cvs-serv7044
Modified Files:
index.xml
Log Message:
some more documentation on how to configure and use mod_authn_dbi
Index: index.xml
===================================================================
RCS file: /cvsroot/mod-auth/mod_auth_webspace/htdocs/docs/mod_authn_dbi/index.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** index.xml 24 Nov 2003 23:15:22 -0000 1.8
--- index.xml 1 Dec 2003 22:07:16 -0000 1.9
***************
*** 28,32 ****
</p>
<p>
! <code>mod_authn_dbi</code> is quite flexible and offers several levels of
customization. This makes it easy to integrate it into existing
installations and authenticate users without having to alter the
--- 28,32 ----
</p>
<p>
! <code>mod_authn_dbi</code> is <em>very flexible</em> and offers several levels of
customization. This makes it easy to integrate it into existing
installations and authenticate users without having to alter the
***************
*** 107,172 ****
/><br />
to your <code>httpd.conf</code> as usual and restart Apache.
- </p>
-
- </section>
- <section id="overview">
- <title>An overview of mod_authn_dbi</title>
- <p><b>in progress....</b></p>
- <p>
- The configuration of <code>mod_authn_dbi</code> consists of two main
- parts. First, you configure one or more configuration sets. Second, you use
- these configuration sets in any number of basic or digest authentication realms.
</p>
<p>
! <h3>Configuration sets</h3>
! Most configuration directives of <code>mod_authn_dbi</code> are of the
! format<br /><br />
! <code>DirectiveName <name> <value></code>
! <br /><br />
! Configuration sets are implicitely created each time you specify a
! <code><name></code> that has not been used before. All directives that are not
! specified for a given configuration set remain at their default
! values. So the minimum to create a usable configuration set is just one
! of the directives.<br />
! Configuration sets contain all the information needed to connect to the
! database server, choose the correct database and table and extract the
! values needed for authenticating users. Additionally, you can specify
! options that for example influence the pooling of connections (see below)
! or the way that the data in the table is interpreted.
!
! <example>
! <title>An example configuration set</title>
! <pre>
! AuthnDbiDriver Server1 mysql
! AuthnDbiHost Server1 mycoolcatserver.com
! AuthnDbiUsername Server1 MyUser
! AuthnDbiPassword Server1 MyPass
! AuthnDbiName Server1 MyDatabaseName
! AuthnDbiTable Server1 MyDatabaseTable
! AuthnDbiUsernameField Server1 theUserNameField
! AuthnDbiPasswordField Server1 PasswordField
! AuthnDbiIsActiveField Server1 IsActiveField
! AuthnDbiConnMin Server1 3
! AuthnDbiConnSoftMax Server1 12
! AuthnDbiConnHardMax Server1 20
! AuthnDbiConnTTL Server1 600
! </pre>
! </example>
! </p>
! <p>
! <h3>Authentication realms</h3>
! <example>
! <title>An example authentication realm</title>
! <pre>
! <Directory "/path/to/htdocs/to/be/area_1_protected">
! AuthType Basic
! AuthName "basic authn_dbi testing area"
! AuthBasicProvider dbi
! AuthnDbiServerConfig Server1
! Require valid-user
! </Directory>
! </pre>
! </example>
! </p>
</section>
<section id="db">
--- 107,120 ----
/><br />
to your <code>httpd.conf</code> as usual and restart Apache.
</p>
<p>
! Upon startup, <code>mod_authn_dbi</code> will read in all drivers that
! are in the driver directory of <code>libdbi</code>. This directory is a
! default vaule compiled into <code>libdbi</code> (usually
! <em><installation prefix of libdbi></em><code>/lib/dbd/</code>). If
! you want <code>mod_authn_dbi</code> to look into a different directory,
! have a look at the <a
! href="#authndbidriverdir"><code>AuthnDbiDriverDir</code></a> directive.
! </p>
</section>
<section id="db">
***************
*** 221,245 ****
<section id="basic">
<title>Basic configuration of mod_authn_dbi</title>
! <p><b>Draft...</b></p>
! <p>
! At the moment, there is only one global option (AuthnDbiDriverDir),
! which you will probably not need at first, so we will start with the
! section about mod_authn_dbi server configs.
! All options that are used for the creation of server configs take
! the name of the server config as first parameter and then some
! value(s) behind that. Server configs are created implicitly, each
! time the module encounters a configuration directive with a config
! name that it has not seen yet.
! To quote from the example above:
! AuthnDbiTable Server1 MyDatabaseTable
- This says that the config with the name "Server1" should use
- the table "MyDatabaseTable" instead of the default "AuthDB",
- you get the idea...
- </p>
</section>
--- 169,337 ----
<section id="basic">
<title>Basic configuration of mod_authn_dbi</title>
! <p>
! The configuration of <code>mod_authn_dbi</code> consists of two main
! parts. First, you configure one or more configuration sets. Then, you use
! these configuration sets in any number of basic or digest authentication realms.
! </p>
! <p>
! At the moment, there is only one global option (<code>AuthnDbiDriverDir</code>),
! which you will probably not need at first, so we will start with the
! section about mod_authn_dbi server configs.
!
! All options that are used for the creation of server configs take
! the name of the server config as first parameter and then some
! value(s) behind that. Server configs are created implicitly, each
! time the module encounters a configuration directive with a config
! name that it has not seen yet.<br /><br />
!
! For example:<br /><br />
!
! <code>AuthnDbiTable Server1 MyDatabaseTable</code>
! <br /><br />
! This says that the config with the name "Server1" should use
! the table "MyDatabaseTable" instead of the default "AuthDB",
! you get the idea...
! </p>
!
+ <p>
+ <h3>Creating Configuration sets</h3>
+ Most configuration directives of <code>mod_authn_dbi</code> are of the
+ format<br /><br />
+ <code>DirectiveName <name> <value></code>
+ <br /><br />
+ Configuration sets are implicitely created each time you specify a
+ <code><name></code> that has not been used before (so beware of
+ typos in the sets name). There is no enclosing syntactic structure around
+ the directives and directives of different sets may be mixed, but it is
+ probably best to keep all directives of one set together like in the
+ example below. All directives that are not
+ specified for a given configuration set remain at their default
+ values. So the minimum to create a usable configuration set is just one
+ of the directives.<br />
+ Configuration sets contain all the information needed to connect to the
+ database server, choose the correct database and table and extract the
+ values needed for authenticating users. Additionally, you can specify
+ options that for example influence the pooling of connections (see below)
+ or the way that the data in the table is interpreted.
+
+ <example>
+ <title>An example configuration set</title>
+ <pre>
+ AuthnDbiDriver Server1 mysql
+ AuthnDbiHost Server1 mycoolcatserver.com
+ AuthnDbiUsername Server1 MyUser
+ AuthnDbiPassword Server1 MyPass
+ AuthnDbiName Server1 MyDatabaseName
+ AuthnDbiTable Server1 MyDatabaseTable
+ AuthnDbiUsernameField Server1 theUserNameField
+ AuthnDbiPasswordField Server1 PasswordField
+ AuthnDbiIsActiveField Server1 IsActiveField
+ AuthnDbiConnMin Server1 3
+ AuthnDbiConnSoftMax Server1 12
+ AuthnDbiConnHardMax Server1 20
+ AuthnDbiConnTTL Server1 600
+ </pre>
+ </example>
+ Configuration sets can only be defined in the main Apache configuration
+ file or one that is included into it. Specifying configuration sets in a
+ <code>.htaccess</code> files is <em>not</em> supported at the moment,
+ altough it might be added in a future release. If this is a feature you
+ would like to see, e.g. to provide hosting users with a possibility to use
+ their own database for authentication, then tell us so on the
+ "mod-auth-devel" mailinglist.
+ </p>
+ <p>
+ <h3>Defining Authentication realms</h3>
+ The authentication of users has changed a lot between versions 1.x/2.0 and
+ 2.1 of Apache. An AAA framework (Authentication, Authorization,
+ Access-Control) has been introduced that allows for more flexibility and
+ orthogonality in the configuration. There is not much (up-to-date) documentation at the moment.
+ There is documentation about <code><a
+ href="http://httpd.apache.org/docs-2.1/mod/mod_auth_basic.html">mod_auth_basic</a></code> and <code><a href="http://httpd.apache.org/docs-2.1/mod/mod_auth_digest.html">mod_auth_digest</a></code> the two main parts of the authentication part ("<code>authn</code>") of the framework .
+
+ Refer to the slides of the talk at the O'Reilly Open Source conference
+ by Justin Erenkrantz "<a
+ href="http://www.erenkrantz.com/oscon/">Authentication in Apache HTTP
+ Server 2.1</a>" for some additional information about the new
+ framework. More documentation will be available on this site Real Soon Now[tm].
+ The an updated version of the official authentication tutorial will be available in the manual
+ section "<a
+ href="http://httpd.apache.org/docs-2.1/howto/auth.html">Authentication,
+ Authorization and Access
+ Control</a>", but at the moment, that page still documents the old
+ system from 2.0 and earlier.
+ <br /><br />
+ </p>
+ <p>
+ <code>mod_authn_dbi</code> registers itself as an Authentication
+ Provider with the name "<code>dbi</code>" in Apache's Authentication
+ Framework. It provides authenticating users with both Basic and Digest
+ Authentication. Basic Authentication is by far the more common one, but
+ you might want to consider Digest Authentication as well, since it is
+ more secure than Basic Authentication and supported by all major
+ browsers. To the user, both will look the same, i.e. appear as a dialog
+ box requesting username and password. The two mechanisms just differ in
+ the way data is exchanged in the background between browser and
+ webserver.
+ <br />
+ </p>
+ <p>
+ To use a configuration set (in one of Apaches central configuration files), you will need the
+ <code><a href="#authndbiserverconfig">AuthnDbiServerConfig</a></code> directive from
+ <code>mod_authn_dbi</code> plus at least <code>AuthType</code>,
+ <code><a
+ href="http://httpd.apache.org/docs-2.1/mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code> or <code><a
+ href="http://httpd.apache.org/docs-2.1/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
+ (depending on the value you pass to <code><a
+ href="http://httpd.apache.org/docs-2.1/mod/core.html#authtype">AuthType</a></code>) and
+ <code><a href="http://httpd.apache.org/docs-2.1/mod/core.html#require">Require</a></code> and a <a
+ href="http://httpd.apache.org/docs-2.1/sections.html">directory-level
+ container</a> like <code><Location></code> or
+ <code><Directory></code> to use them in.
+ </p>
+ <p>
+ First, decide wheter to use Basic or Digest Authentication and set
+ <code><a
+ href="http://httpd.apache.org/docs-2.1/mod/core.html#authtype">AuthType</a></code> to <code>Digest</code> or <code>Basic</code> accordingly.
+ Then, set the matching provider directive (<code><a
+ href="http://httpd.apache.org/docs-2.1/mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code> or <code><a
+ href="http://httpd.apache.org/docs-2.1/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>) to "<code>dbi</code>", this links <code>mod_authn_dbi</code> to this authentication section. Next, you need to tell <code>mod_authn_dbi</code> which configuration set to use by setting <code><a href="#authndbiserverconfig">AuthnDbiServerConfig</a></code> to the name of the set. Configuration sets can be used for both Basic and Digest Authentication (even at the same time) and for any number of authentication sections. Now, this authentication section is linked to a specific configuration set within <code>mod_authn_dbi</code>. If you specify <code><a href="#authndbiserverconfig">AuthnDbiServerConfig</a></code> more than once, the last value will be used.<br />
+ Finally, you specify who may access the section with <code><a
+ href="http://httpd.apache.org/docs-2.1/mod/core.html#require">Require</a></code> to actually use this authentication section when a client request comes in. (Well, most of this is not really <em>that</em> different from what is is in 2.0 and earlier). Authentication realms that use <code>mod_authn_dbi</code> can also be used
+ from a <code>.htaccess</code> file as usual. Just leave off the container directives.
! </p>
! <p>
! Below you find two example configurations, one for Basic and one for
! Digest Authentication.
! <example>
! <title>An example authentication realm for Digest Authentication</title>
! <pre>
! <Directory "/path/to/htdocs/to/be/area_1_protected">
! AuthType Digest
! AuthName "digest authn_dbi testing area"
! AuthDigestProvider dbi
! AuthnDbiServerConfig Server1
! Require valid-user
! </Directory>
! </pre>
! </example>
! <example>
! <title>An example authentication realm for Basic Authentication</title>
! <pre>
! <Directory "/path/to/htdocs/to/be/area_2_protected">
! AuthType Basic
! AuthName "basic authn_mysql testing area"
! AuthBasicProvider dbi
! AuthnDbiServerConfig Server1
! Require valid-user
! </Directory>
! </pre>
! </example>
! </p>
</section>
***************
*** 247,252 ****
<title>Advanced configuration of mod_authn_dbi</title>
<p>
! insert kung-foo here...
</p>
</section>
--- 339,353 ----
<title>Advanced configuration of mod_authn_dbi</title>
<p>
! As mentioned earlier, <code>mode_authn_dbi</code> is very flexible. You
! can do all kinds of nifty things, with (or even without) your user
! database, especially with the <a
! href="#AuthnDbiPasswordQuery">AuthnDbiPasswordQuery</a>.
! </p>
! <p>
! <b>
! More kung-foo will be added here soon...
! </b>
</p>
+
</section>
***************
*** 254,258 ****
<title>Pooling of database connections</title>
<p>
! coming soon...
</p>
</section>
--- 355,395 ----
<title>Pooling of database connections</title>
<p>
! To handle incoming requests in an efficient but also performant way,
! <code>mod_authn_dbi</code> organizes connections to the database
! server(s) into pools, with one connection pool per configuration set. It
! opens and closes connections depending on the load the webserver is
! experiencing at a given time. The pooling mechanism is built on the
! <a href="http://apr.apache.org/">Resource List Routines</a> of <code><a
! href="http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html">libapr-util</a></code> (and you probably had to download separately) and is similar to the way Apache manages the number of server processes or threads.
! </p>
! <p>
! When first started, <code>mod_authn_dbi</code> creates a mimimum number of
! connections to the database server before accepting client requests.
! When a client request comes in that needs to be Authenticated, a database
! connection is requested from the connection pool of the matching
! configuration set. The connection is used for autentication and then
! released back into the pool of idle connections. If no idle connection is
! available and the number of connections in the pool has not reached its
! hard maximum, a new connection to the database is created and used. After
! use, it is not destroyed but added as idle connection to the pool of
! connections.<br />
! Each configuration contains soft maximum value and a time-to-live (TTL)
! value (e.g. 600 seconds). If more than the soft maximum number of idle
! database connections is in a given pool, connections that have been idle
! for longer than the time-to-live value will be closed until a value not
! larger than the soft maximum is reached.
! </p>
! <p>
! These four directives can be used to control the various limits:
! <ul>
! <li><code><a href="#AuthnDbiConnMin">AuthnDbiConnMin</a></code>- The
! minimum (and initial) number of connections.</li>
! <li><code><a href="#AuthnDbiConnSoftMax">AuthnDbiConnSoftMax</a></code> -
! The soft maximum value of connections.</li>
! <li><code><a href="#AuthnDbiConnHardMax">AuthnDbiConnHardMax</a></code> -
! The hard maximum of connections.</li>
! <li><code><a href="#AuthnDbiConnTTL">AuthnDbiConnTTL</a></code> - The
! time-to-live in seconds.</li>
! </ul>
</p>
</section>
***************
*** 401,410 ****
foot). Changing its value may also change the behaviour of
<code>AuthnDbiUsernameField</code>, <code>AuthnDbiPasswordField</code>,
! <code>AuthnDbiIsActiveField</code>, <code>AuthnDbiTable</code> from
what is documented in here.
</p>
<p>
For <em>each request</em> that is received (not just at configuration
! time), mod_authn_dbi will go through the following steps:
<ol>
<li><b>Replace variables in the query string by their corresponding
--- 538,547 ----
foot). Changing its value may also change the behaviour of
<code>AuthnDbiUsernameField</code>, <code>AuthnDbiPasswordField</code>,
! <code>AuthnDbiIsActiveField</code>, <code>AuthnDbiTable</code> from
what is documented in here.
</p>
<p>
For <em>each request</em> that is received (not just at configuration
! time), <code>mod_authn_dbi</code> will go through the following steps:
<ol>
<li><b>Replace variables in the query string by their corresponding
***************
*** 617,622 ****
<usage>
<p>
! See <a
! href="http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html">http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html</a> for now. More info follows soon.
</p>
</usage>
--- 754,759 ----
<usage>
<p>
! See section "<a
! href="#pooling">Pooling of database connections</a>" for now. More info follows soon.
</p>
</usage>
***************
*** 634,639 ****
<usage>
<p>
! See <a
! href="http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html">http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html</a> for now. More info follows soon.
</p>
</usage>
--- 771,776 ----
<usage>
<p>
! See section "<a
! href="#pooling">Pooling of database connections</a>" for now. More info follows soon.
</p>
</usage>
***************
*** 651,656 ****
<usage>
<p>
! See <a
! href="http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html">http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html</a> for now. More info follows soon.
</p>
</usage>
--- 788,793 ----
<usage>
<p>
! See section "<a
! href="#pooling">Pooling of database connections</a>" for now. More info follows soon.
</p>
</usage>
***************
*** 668,673 ****
<usage>
<p>
! See <a
! href="http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html">http://apr.apache.org/docs/apr-util/group__APR__Util__RL.html</a> for now. More info follows soon.
</p>
</usage>
--- 805,810 ----
<usage>
<p>
! See section "<a
! href="#pooling">Pooling of database connections</a>" for now. More info follows soon.
</p>
</usage>
|
