Commit 1619602e authored by Bradley Nicholes's avatar Bradley Nicholes
Browse files

Update the documentation to show the new provider based authorization 

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/authz-dev@360027 13f79535-47bb-0310-9956-ffa450edef68
parent 640ebd4d

docs/manual/howto/auth.xml

+83 −35
Original line number Diff line number Diff line
@@ -50,6 +50,7 @@ module from each group.</p> 
    <ul>

      <li><module>mod_authn_alias</module></li>

      <li><module>mod_authn_anon</module></li>

      <li><module>mod_authn_core</module></li>

      <li><module>mod_authn_dbd</module></li>

      <li><module>mod_authn_dbm</module></li>

      <li><module>mod_authn_default</module></li>
@@ -58,9 +59,11 @@ module from each group.</p> 
    </ul>

  </li>

  <li>Authorization (see the 

      <directive module="core">Require</directive> directive)

      <directive module="mod_authz_core">Require</directive> and

      <directive module="mod_authz_core">Reject</directive> directives)

    <ul>

      <li><module>mod_authnz_ldap</module></li>

      <li><module>mod_authz_core</module></li>

      <li><module>mod_authz_dbm</module></li>

      <li><module>mod_authz_default</module></li>

      <li><module>mod_authz_groupfile</module></li>
@@ -76,10 +79,10 @@ module from each group.</p> 
  in itself, but allows other authentication providers to be

  configured in a flexible manner.</p>



  <p>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>

  <p>The modules <module>mod_authn_core</module> and <module>mod_authz_core

  </module> should always be loaded. These module provide the core

  directives and functionality that is common to all authentication 

  and authorization providers.</p>



</section>
@@ -172,6 +175,7 @@ module from each group.</p> 
    <example>

      AuthType Basic<br />

      AuthName "Restricted Files"<br />

      AuthBasicProvider file<br />

      AuthUserFile /usr/local/apache/passwd/passwords<br />

      Require user rbowen

    </example>
@@ -205,6 +209,10 @@ module from each group.</p> 
    will always need to ask again for the password whenever the

    hostname of the server changes.</p>



    <p>The <directive module="mod_auth_basic">AuthBasicProvider</directive>

    directive registers which provider or providers will be called to handle

    the authentication processing.</p>



    <p>The <directive module="mod_authn_file">AuthUserFile</directive>

    directive sets the path to the password file that we just

    created with <program>htpasswd</program>. If you have a large number
@@ -266,6 +274,7 @@ person in</title> 
    <example>

      AuthType Basic<br />

      AuthName "By Invitation Only"<br />

      AuthBasicProvider file<br />

      AuthUserFile /usr/local/apache/passwd/passwords<br />

      AuthGroupFile /usr/local/apache/passwd/groups<br />

      Require group GroupName
@@ -321,31 +330,42 @@ do?</title> 
    other than who they are. Something such as where they are

    coming from.</p>



    <p>The <directive module="mod_authz_host">Allow</directive> and

    <directive module="mod_authz_host">Deny</directive> directives let

    you allow and deny access based on the host name, or host

    address, of the machine requesting a document. The

    <directive module="mod_authz_host">Order</directive> directive goes

    hand-in-hand with these two, and tells Apache in which order to

    apply the filters.</p>



    <p>The usage of these directives is:</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 te 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>

      Allow from <var>address</var>

      Require ip <var>address</var>

    </example>



    <p>where <var>address</var> is an IP address (or a partial IP

    address) or a fully qualified domain name (or a partial domain

    name); you may provide multiple addresses or domain names, if

    desired.</p>

    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>

      Deny from 205.252.46.165

      Reject ip 205.252.46.165

    </example>



    <p>Visitors coming from that address will not be able to see
@@ -353,34 +373,62 @@ do?</title> 
    machine name, rather than an IP address, you can use that.</p>



    <example>

      Deny from <var>host.example.com</var>

      Reject host <var>host.example.com</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>

      Deny from <var>192.101.205</var><br />

      Deny from <var>cyberthugs.com</var> <var>moreidiots.com</var><br />

      Deny from ke

      &lt;RequireAll&gt;<br />

      &nbsp;  Reject ip <var>192.101.205</var><br />

      &nbsp;  Reject host <var>cyberthugs.com</var> <var>moreidiots.com</var><br />

      &nbsp;  Reject host ke<br />

      &lt;/RequireAll&gt;

    </example>



    <p>Using <directive module="mod_authz_host">Order</directive> will let you

    be sure that you are actually restricting things to the group that you want

    to let in, by combining a <directive

    module="mod_authz_host">Deny</directive> and an <directive

    module="mod_authz_host">Allow</directive> directive:</p>

    <p>Using the <directive module="mod_authz_host">Reject</directive> directive

    inside of a <directive module="mod_authz_core">&lt;RequireAll&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;RequireAll&gt;</directive> block to make sure that all of the 

    <directive module="mod_authz_host">Reject</directive> directives are 

    satisfied before granting access. The <directive module="mod_authz_core">

    &lt;RequireAll&gt;</directive> block as well as the 

    <directive module="mod_authz_core">&lt;RequireOne&gt;</directive> block 

    allow you to apply "AND" and "OR" logic to the authorization processing. 

    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>

      Order deny,allow<br />

      Deny from all<br />

      Allow from <var>dev.example.com</var>

    &lt;Directory /www/mydocs&gt;<br />

    &nbsp;  Authname ...<br />

    &nbsp;  AuthBasicProvider ...<br />

    &nbsp;  ...<br />

    &nbsp;  Require user John<br />

    &nbsp;  &lt;RequireAll&gt;<br />

    &nbsp;&nbsp;    Require Group admins<br />

    &nbsp;&nbsp;    Require ldap-group cn=mygroup,o=foo<br />

    &nbsp;&nbsp;    &lt;RequireOne&gt;<br />

    &nbsp;&nbsp;&nbsp;      Require ldap-attribute dept="sales"<br />

    &nbsp;&nbsp;&nbsp;      Require file-group<br />

    &nbsp;&nbsp;    &lt;/RequireOne&gt;<br />

    &nbsp;  &lt;/RequireAll&gt;<br />

    &lt;/Directory&gt;<br />

    </example>



    <p>Listing just the <directive module="mod_authz_host">Allow</directive>

    directive would not do what you want, because it will let folks from that

    host in, in addition to letting everyone in. What you want is to let

    <em>only</em> those folks in.</p>

</section>



<section id="moreinformation"><title>More information</title>

docs/manual/mod/core.xml

+0 −207
Original line number Diff line number Diff line
@@ -469,69 +469,6 @@ be passed through</description> 
<seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso>

</directivesynopsis>



<directivesynopsis>

<name>AuthName</name>

<description>Authorization realm for use in HTTP

authentication</description>

<syntax>AuthName <var>auth-domain</var></syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>



<usage>

    <p>This directive sets the name of the authorization realm for a

    directory. This realm is given to the client so that the user

    knows which username and password to send.

    <directive>AuthName</directive> takes a single argument; if the

    realm name contains spaces, it must be enclosed in quotation

    marks.  It must be accompanied by <directive

    module="core">AuthType</directive> and <directive

    module="core">Require</directive> directives, and directives such

    as <directive module="mod_authn_file">AuthUserFile</directive> and

    <directive module="mod_authz_groupfile">AuthGroupFile</directive> to

    work.</p>



   <p>For example:</p>



   <example>

     AuthName "Top Secret"

   </example>



    <p>The string provided for the <code>AuthName</code> is what will

    appear in the password dialog provided by most browsers.</p>

</usage>

<seealso><a

    href="../howto/auth.html">Authentication, Authorization, and

    Access Control</a></seealso>

</directivesynopsis>



<directivesynopsis>

<name>AuthType</name>

<description>Type of user authentication</description>

<syntax>AuthType Basic|Digest</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>



<usage>

    <p>This directive selects the type of user authentication for a

    directory. The authentication types available are

    <code>Basic</code> (implemented by

    <module>mod_auth_basic</module>) and <code>Digest</code>

    (implemented by <module>mod_auth_digest</module>).</p>



    <p>To implement authentication, you must also use the <directive

    module="core">AuthName</directive> and <directive

    module="core">Require</directive> directives.  In addition, the

    server must have an authentication-provider module such as

    <module>mod_authn_file</module> and an authorization module such

    as <module>mod_authz_user</module>.</p>

</usage> 



<seealso><a href="../howto/auth.html">Authentication, Authorization,

    and Access Control</a></seealso> 

</directivesynopsis>



<directivesynopsis>

<name>CGIMapExtension</name>

<description>Technique for locating the interpreter for CGI
@@ -2391,101 +2328,6 @@ directory</description> 
</usage>

</directivesynopsis>



<directivesynopsis>

<name>Require</name>

<description>Selects which authenticated users can access

a resource</description>

<syntax>Require <var>entity-name</var> [<var>entity-name</var>] ...</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>



<usage>

    <p>This directive selects which authenticated users can access a

    resource.  The restrictions are processed by authorization

    modules.  Some of the allowed syntaxes provided by

    <module>mod_authz_user</module> and

    <module>mod_authz_groupfile</module> are:</p>



    <dl>

      <dt><code>Require user <var>userid</var> [<var>userid</var>]

      ...</code></dt>

      <dd>Only the named users can access the resource.</dd>



      <dt><code>Require group <var>group-name</var> [<var>group-name</var>]

      ...</code></dt>

      <dd>Only users in the named groups can access the resource.</dd>



      <dt><code>Require valid-user</code></dt>

      <dd>All valid users can access the resource.</dd>

    </dl>



    <p>Other authorization modules that implement require options

    include <module>mod_authnz_ldap</module>,

    <module>mod_authz_dbm</module>, and

    <module>mod_authz_owner</module>.</p>



    <p><directive>Require</directive> must be accompanied by

    <directive module="core">AuthName</directive> and <directive

    module="core">AuthType</directive> directives, and directives such

    as <directive module="mod_authn_file">AuthUserFile</directive>

    and <directive module="mod_authz_groupfile">AuthGroupFile</directive> (to

    define users and groups) in order to work correctly. Example:</p>



    <example>

       AuthType Basic<br />

       AuthName "Restricted Resource"<br />

       AuthUserFile /web/users<br />

       AuthGroupFile /web/groups<br />

       Require group admin

    </example>



    <p>Access controls which are applied in this way are effective for

    <strong>all</strong> methods. <strong>This is what is normally

    desired.</strong> If you wish to apply access controls only to

    specific methods, while leaving other methods unprotected, then

    place the <directive>Require</directive> statement into a

    <directive module="core" type="section">Limit</directive>

    section.</p>

 

    <p>If <directive>Require</directive> is used together with 

    the <directive module="mod_authz_host">Allow</directive> or

    <directive module="mod_authz_host">Deny</directive> directives,

    then the interaction of these restrictions is controlled by

    the <directive module="core">Satisfy</directive> directive.</p>



    <note><title>Removing controls in subdirectories</title>

    <p>The following example shows how to use the <directive

    module="core">Satisfy</directive> directive to disable access

    controls in a subdirectory of a protected directory.  This

    technique should be used with caution, because it will also

    disable any access controls imposed by

    <module>mod_authz_host</module>.</p>

    <example>

      &lt;Directory /path/to/protected/&gt;<br />

        <indent>

        Require user david<br />

        </indent>

      &lt;/Directory&gt;<br />

      &lt;Directory /path/to/protected/unprotected&gt;<br />

        <indent>

        # All access controls and authentication are disabled<br />

        # in this directory<br />

        Satisfy Any<br />

        Allow from all<br />

        </indent>

      &lt;/Directory&gt;<br />

    </example>

    </note>

      

</usage>



<seealso><a href="../howto/auth.html">Authentication, Authorization,

    and Access Control</a></seealso> 

<seealso><directive module="core">Satisfy</directive></seealso>

<seealso><module>mod_authz_host</module></seealso>

</directivesynopsis>



<directivesynopsis>

<name>RLimitCPU</name>

<description>Limits the CPU consumption of processes launched
@@ -2593,55 +2435,6 @@ processes launched by Apache children</description> 
<seealso><directive module="core">RLimitCPU</directive></seealso>

</directivesynopsis>



<directivesynopsis>

<name>Satisfy</name>

<description>Interaction between host-level access control and

user authentication</description>

<syntax>Satisfy Any|All</syntax>

<default>Satisfy All</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<compatibility>Influenced by <directive module="core" type="section"

>Limit</directive> and <directive module="core"

type="section">LimitExcept</directive> in version 2.0.51 and

later</compatibility>



<usage>

    <p>Access policy if both <directive

    module="mod_authz_host">Allow</directive> and <directive

    module="core">Require</directive> used. The parameter can be

    either <code>All</code> or <code>Any</code>. This directive is only

    useful if access to a particular area is being restricted by both

    username/password <em>and</em> client host address. In this case

    the default behavior (<code>All</code>) is to require that the client

    passes the address access restriction <em>and</em> enters a valid

    username and password. With the <code>Any</code> option the client will be

    granted access if they either pass the host restriction or enter a

    valid username and password. This can be used to password restrict

    an area, but to let clients from particular addresses in without

    prompting for a password.</p>



    <p>For example, if you wanted to let people on your network have

    unrestricted access to a portion of your website, but require that

    people outside of your network provide a password, you could use a

    configuration similar to the following:</p>



    <example>

      Require valid-user<br />

      Allow from 192.168.1<br />

      Satisfy Any

    </example>



    <p>Since version 2.0.51 <directive>Satisfy</directive> directives can

    be restricted to particular methods by <directive module="core"

    type="section">Limit</directive> and <directive module="core" type="section"

    >LimitExcept</directive> sections.</p>

</usage>

   <seealso><directive module="mod_authz_host">Allow</directive></seealso>

   <seealso><directive module="core">Require</directive></seealso>

</directivesynopsis>



<directivesynopsis>

<name>ScriptInterpreterSource</name>

<description>Technique for locating the interpreter for CGI

docs/manual/mod/mod_authn_core.xml

0 → 100644
+103 −0
Original line number Diff line number Diff line 
<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>

<!-- $LastChangedRevision: 151408 $ -->



<!--

 Copyright 2002-2005 The Apache Software Foundation or its licensors, as

 applicable.



 Licensed under the Apache License, Version 2.0 (the "License");

 you may not use this file except in compliance with the License.

 You may obtain a copy of the License at



     http://www.apache.org/licenses/LICENSE-2.0



 Unless required by applicable law or agreed to in writing, software

 distributed under the License is distributed on an "AS IS" BASIS,

 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 See the License for the specific language governing permissions and

 limitations under the License.

-->



<modulesynopsis metafile="mod_authn_core.xml.meta">



<name>mod_authn_core</name> 

<description>Core Authentication</description>

<status>Base</status>

<sourcefile>mod_authn_core.c</sourcefile>

<identifier>authn_core_module</identifier>

<compatibility>Available in Apache 2.3 and later</compatibility>



<summary>

    <p>This module provides core authentication capabilities to 

    allow or deny access to portions of the web site. 

    <module>mod_authn_core</module> provides directives that are 

    common to all authentication providers.</p>

</summary>



<directivesynopsis>

<name>AuthName</name>

<description>Authorization realm for use in HTTP

authentication</description>

<syntax>AuthName <var>auth-domain</var></syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>



<usage>

    <p>This directive sets the name of the authorization realm for a

    directory. This realm is given to the client so that the user

    knows which username and password to send.

    <directive>AuthName</directive> takes a single argument; if the

    realm name contains spaces, it must be enclosed in quotation

    marks.  It must be accompanied by <directive

    module="mod_authn_core">AuthType</directive> and <directive

    module="mod_authz_core">Require</directive> directives, and directives such

    as <directive module="mod_authn_file">AuthUserFile</directive> and

    <directive module="mod_authz_groupfile">AuthGroupFile</directive> to

    work.</p>



   <p>For example:</p>



   <example>

     AuthName "Top Secret"

   </example>



    <p>The string provided for the <code>AuthName</code> is what will

    appear in the password dialog provided by most browsers.</p>

</usage>

<seealso><a

    href="../howto/auth.html">Authentication, Authorization, and

    Access Control</a></seealso>

</directivesynopsis>



<directivesynopsis>

<name>AuthType</name>

<description>Type of user authentication</description>

<syntax>AuthType Basic|Digest</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>



<usage>

    <p>This directive selects the type of user authentication for a

    directory. The authentication types available are

    <code>Basic</code> (implemented by

    <module>mod_auth_basic</module>) and <code>Digest</code>

    (implemented by <module>mod_auth_digest</module>).</p>



    <p>To implement authentication, you must also use the <directive

    module="mod_authn_core">AuthName</directive> and <directive

    module="mod_authz_core">Require</directive> directives.  In addition, the

    server must have an authentication-provider module such as

    <module>mod_authn_file</module> and an authorization module such

    as <module>mod_authz_user</module>.</p>

</usage> 



<seealso><a href="../howto/auth.html">Authentication, Authorization,

    and Access Control</a></seealso> 

</directivesynopsis>





</modulesynopsis>

docs/manual/mod/mod_authn_core.xml.meta

0 → 100644
+11 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8" ?>



<metafile>

  <basename>mod_authn_core</basename>

  <path>/mod/</path>

  <relpath>..</relpath>



  <variants>

    <variant>en</variant>

  </variants>

</metafile>

docs/manual/mod/mod_authz_core.xml

0 → 100644
+222 −0

File added.

Preview size limit exceeded, changes collapsed.