httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r378124 - /httpd/httpd/trunk/docs/manual/howto/auth.xml
Date Wed, 15 Feb 2006 23:48:30 GMT
Author: bnicholes
Date: Wed Feb 15 15:48:29 2006
New Revision: 378124

Add more detail about how to use the new authorization configuration


Modified: httpd/httpd/trunk/docs/manual/howto/auth.xml
--- httpd/httpd/trunk/docs/manual/howto/auth.xml (original)
+++ httpd/httpd/trunk/docs/manual/howto/auth.xml Wed Feb 15 15:48:29 2006
@@ -46,9 +46,11 @@
-  <li>Authentication provider
+  <li>Authentication provider (see the 
+  <directive module="mod_auth_basic">AuthBasicProvider</directive> and
+  <directive module="mod_auth_digest">AuthDigestProvider</directive> directives)
-      <li><module>mod_authn_alias</module></li>
@@ -62,24 +64,28 @@
+      <li><module>mod_authz_dbm</module></li>
+      <li><module>mod_authz_host</module></li>
-  <p>The module <module>mod_authnz_ldap</module> is both an
-  authentication and authorization provider.  The module
-  <module>mod_authn_alias</module> is not an authentication provider
-  in itself, but allows other authentication providers to be
-  configured in a flexible manner.</p>
+  <p>In addition to these modules, there are also 
+  <module>mod_authn_core</module> and 
+  <module>mod_authz_core</module>.  These module implement core
+  directives that are core to all auth modules.</p>
-  <p>The module <module>mod_authz_host</module> provides authorization
+  <p>The module <module>mod_authnz_ldap</module> is both an
+  authentication and authorization provider.  The module 
+  <module>mod_authz_host</module> provides authorization
   and access control based on hostname, IP address or characteristics
   of the request, but is not part of the authentication provider
-  system.</p>
+  system. For backwards compatibility with the mod_access, there is 
+  a new module <module>mod_access_compat</module>.</p>
   <p>You probably also want to take a look at the <a
   href="access.html">Access Control</a> howto, which discusses the
@@ -131,6 +137,13 @@
     structure of your server, in order to know where some files are
     kept. This should not be terribly difficult, and I'll try to
     make this clear when we come to that point.</p>
+    <p>You will also need to make sure that the modules 
+    <module>mod_authn_core</module> and <module>mod_authz_core</module>

+    have either been built into the httpd binary or loaded by the 
+    httpd.conf configuration file. Both of these modules provide core 
+    directives and functionality that are critical to the configuration 
+    and use of authentication and authorization in the web server.</p>
 <section id="gettingitworking"><title>Getting it working</title>
@@ -370,12 +383,239 @@
     <module>mod_authn_dbm</module> documentation for more details.</p>
+<section id="multprovider"><title>Using multiple providers</title>
+    <p>With the introduction of the new provider based authentication and
+    authorization architecture, you are no longer locked into a single 
+    authentication or authorization method. In fact any number of the 
+    providers can be mixed and matched to provide you with exactly the 
+    scheme that meets your needs. In the following example, both the 
+    file and ldap based authentication providers are being used.</p>
+    <example>
+    &lt;Directory /www/docs/private&gt;<br />
+    AuthName "Private"<br />
+    AuthType Basic<br />
+    AuthBasicProvider file ldap<br />
+    AuthUserFile /usr/local/apache/passwd/passwords<br />
+    AuthLDAPURL ldap://ldaphost/o=yourorg<br />
+    Require valid-user
+    </example>
+    <p>In this example the file provider will attempt to authenticate
+    the user first. If it is unable to authenticate the user, the ldap
+    provider will be called. This allows the scope of authentication
+    to be broadened if your organization implements more than
+    one type of authentication store. Other authentication and authorization
+    scenarios may include mixing one type of authentication with a
+    different type of authorization. For example, authenticating against
+    a password file yet authorizing against and ldap directory.</p>
+    <p>Just as multiple authentication providers can be implemented, multiple
+    authorization methods can also be used. In this example both file group
+    authorization as well as ldap group authorization is being used.</p>
+    <example>
+    &lt;Directory /www/docs/private&gt;<br />
+    AuthName "Private"<br />
+    AuthType Basic<br />
+    AuthBasicProvider file<br />
+    AuthUserFile /usr/local/apache/passwd/passwords<br />
+    AuthLDAPURL ldap://ldaphost/o=yourorg
+    AuthGroupFile /usr/local/apache/passwd/groups<br />
+    Require group GroupName<br />
+    Require ldap-group cn=mygroup,o=yourorg
+    </example>
+    <p>To take authorization a little further, the directives
+    <directive module="mod_authz_core">&lt;SatisfyAll&gt;</directive>
+    <directive module="mod_authz_core">&lt;SatisfyOne&gt;</directive>
+    AND/OR logic to be applied so that the order in which authorization
+    is handled can be completely controled through the configuration. See
+    these directives for a complete example on they can be applied.</p>
+<section id="multprovider"><title>Beyond just authorization</title>
+    <p>The way that authorization can be apply is now much more flexible 
+    than just a single check against a single data store. Ordering, logic
+    and choosing how authorization will be done is now possible.</p>
+    <section id="authandororder"><title>Applying AND/OR logic and ordering</title>
+        <p>Controling how and in what order authorization will be applied
+        has been a bit of a mystery in the past. In Apache 2.2 a provider based
+        authentication mechanism was introduced to decouple the actual 
+        authentication process from authorization and supporting functionality.
+        One of the side benefits was that authentication providers could be
+        configured and called in a specific order which didn't depend on the 
+        load order of the auth module itself. This same provider based mechanism 
+        has been brought forward into authorization as well. What this means is 
+        that the <directive module="mod_authz_core">Require</directive> directive

+        not only specifies which authorization methods should be used, it also 
+        specifies the order in which they are called. Multiple autorization 
+        methods are called in the same order in which the 
+        <directive module="mod_authz_core">Require</directive> directives appear

+        in the configuration.</p>
+        <p>With the introduction of the directives 
+        <directive module="mod_authz_core">&lt;SatisfyAll&gt;</directive>
+        <directive module="mod_authz_core">&lt;SatisfyOne&gt;</directive>,
+        configuration also has control over when the
+        authorization methods are called and what criteria determines when 
+        access is granted. For example the following authorization block would 
+        apply the logic:</p>
+        <p><var>
+        if ((user == "John") || <br />
+        &nbsp;&nbsp;&nbsp;((Group == "admin") &amp;&amp; (ldap-group
&lt;ldap-object&gt; contains auth'ed_user) &amp;&amp;<br />
+        &nbsp;&nbsp;&nbsp;&nbsp;((ldap-attribute dept == "sales") || 
+        (file-group contains contains auth'ed_user))))<br />
+        then<br />
+        &nbsp;&nbsp;auth_granted<br />
+        else<br />
+        &nbsp;&nbsp;auth_denied<br />
+        </var></p>
+        <example>
+        &lt;Directory /www/mydocs&gt;<br />
+        &nbsp;  Authname ...<br />
+        &nbsp;  AuthBasicProvider ...<br />
+        &nbsp;  ...<br />
+        &nbsp;  Require user John<br />
+        &nbsp;  &lt;SatisfyAll&gt;<br />
+        &nbsp;&nbsp;    Require Group admins<br />
+        &nbsp;&nbsp;    Require ldap-group cn=mygroup,o=foo<br />
+        &nbsp;&nbsp;    &lt;SatisfyOne&gt;<br />
+        &nbsp;&nbsp;&nbsp;      Require ldap-attribute dept="sales"<br />
+        &nbsp;&nbsp;&nbsp;      Require file-group<br />
+        &nbsp;&nbsp;    &lt;/SatisfyOne&gt;<br />
+        &nbsp;  &lt;/SatisfyAll&gt;<br />
+        &lt;/Directory&gt;<br />
+        </example>
+        <p>By default all <directive module="mod_authz_core">Require</directive>

+        directives are handled through and OR operation. In other words, if 
+        any of the specified authorization methods succeed, then authorization 
+        is granted. By enclosing a set of 
+        <directive module="mod_authz_core">Require</directive> directives within
+        a <directive module="mod_authz_core">&lt;SatisfyAll&gt;</directive>
+        the processing switches to an AND operation which requires all authorization 
+        methods to succeed before authorization is granted.</p>
+    </section>
+    <section id="reqaccessctrl"><title>Using 'Require' or 'Reject' for access
+        <p>Authentication by username and password is only part of the
+        story. Frequently you want to let people in based on something
+        other than who they are. Something such as where they are
+        coming from.</p>
+        <p>The authorization providers <directive module="mod_authz_host">
+        all</directive>, <directive module="mod_authz_host">
+        env</directive>, <directive module="mod_authz_host">
+        host</directive> and <directive module="mod_authz_host">
+        ip</directive> let you allow or deny access based other host based
+        criteria such as host name or ip address of the machine requesting 
+        a document.</p> 
+        <p>The usage of these providers is specified through the 
+        <directive module="mod_authz_core">Require</directive> and 
+        <directive module="mod_authz_core">Reject</directive> directives.
+        These directives register the authorization providers
+        that will be called during the authorization stage of the request
+        processing. For example:</p>
+        <example>
+          Require ip <var>address</var>
+        </example>
+        <p>where <var>address</var> is an IP address (or a partial IP
+        address) or:</p>
+        <example>
+          Require host <var>domain_name</var>
+        </example>
+        <p>where <var>domain_name</var> is a fully qualified domain name

+        (or a partial domain name); you may provide multiple addresses or 
+        domain names, if desired.</p>
+        <p>For example, if you have someone spamming your message
+        board, and you want to keep them out, you could do the
+        following:</p>
+        <example>
+          Reject ip
+        </example>
+        <p>Visitors coming from that address will not be able to see
+        the content covered by this directive. If, instead, you have a
+        machine name, rather than an IP address, you can use that.</p>
+        <example>
+          Reject host <var></var>
+        </example>
+        <p>And, if you'd like to block access from an entire domain,
+        you can specify just part of an address or domain name:</p>
+        <example>
+          &lt;SatisfyAll&gt;<br />
+          &nbsp;  Reject ip <var>192.101.205</var><br />
+          &nbsp;  Reject host <var></var> <var></var><br
+          &nbsp;  Reject host ke<br />
+          &lt;/SatisfyAll&gt;
+        </example>
+        <p>Using the <directive module="mod_authz_host">Reject</directive>
+        inside of a <directive module="mod_authz_core">&lt;SatisfyAll&gt;</directive>
+        block, will let you be sure that you are actually restricting things to 
+        only the group that you want to let in.</p>
+        <p>The above example uses the <directive module="mod_authz_core">
+        &lt;SatisfyAll&gt;</directive> block to make sure that all of the 
+        <directive module="mod_authz_host">Reject</directive> directives are

+        satisfied before granting access. </p>
+    </section>
+    <section id="filesystem"><title>Access Control backwards compatibility</title>
+        <p>One of the side effects of adopting a provider based mechanism for 
+        authentication is that the need for the previous access control directives
+        <directive module="mod_access_compat">Order</directive>,
+        <directive module="mod_access_compat">Allow</directive>,
+        <directive module="mod_access_compat">Deny</directive> and 
+        <directive module="mod_access_compat">Satisfy</directive> are no longer
+        However to provide backwards compatibility for older configurations, these 
+        directives have been moved to the <module>mod_access_compat</module>
+        <p>One of the problems with these directives was that the line between
+        authorization and access control was very fuzzy. The 
+        <directive module="mod_access_compat">Satisfy</directive> directive
+        tried to tie these two stages together by hooking itself into the 
+        request processing itself. Now that these directive have been moved to the
+        <module>mod_access_compat</module>, mixing the new authorization directives
+        with the older access control directives becomes difficult. To address this
+        issue, the <module>mod_authz_default</module> module becomes very important
and must
+        be loaded. The main purpose of the <module>mod_authz_default</module>
module is 
+        to handle any authorization requests that could not be handled by the 
+        authorization providers. But when the older access control directives are used, 
+        it also links access control with authorization and determines if access 
+        should be granted based on the outcome of each stage. Therefore if the 
+        older directives do not seem to be working properly, it might be because the
+        <module>mod_authz_default</module> module has not been loaded.</p>
+    </section>
 <section id="moreinformation"><title>More information</title>
     <p>You should also read the documentation for
     <module>mod_auth_basic</module> and <module>mod_authz_host</module>
     contain some more information about how this all works.
-    <module>mod_authn_alias</module> can also help in simplifying certain
-    authentication configurations.</p>
+    The directive <directive module="mod_authn_core">&lt;AuthnProviderAlias&gt;</directive>

+    can also help in simplifying certain authentication configurations.</p>
     <p>And you may want to look at the <a href="access.html">Access
     Control</a> howto, which discusses a number of related topics.</p>

View raw message