You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by bn...@apache.org on 2005/12/30 09:21:13 UTC
svn commit: r360027 - in /httpd/httpd/branches/authz-dev/docs/manual:
howto/auth.xml mod/core.xml mod/mod_authn_core.xml
mod/mod_authn_core.xml.meta mod/mod_authz_core.xml
mod/mod_authz_core.xml.meta mod/mod_authz_host.xml
Author: bnicholes
Date: Fri Dec 30 00:21:06 2005
New Revision: 360027
URL: http://svn.apache.org/viewcvs?rev=360027&view=rev
Log:
Update the documentation to show the new provider based authorization
Added:
httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml
httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml.meta
httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml
httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml.meta
Modified:
httpd/httpd/branches/authz-dev/docs/manual/howto/auth.xml
httpd/httpd/branches/authz-dev/docs/manual/mod/core.xml
httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_host.xml
Modified: httpd/httpd/branches/authz-dev/docs/manual/howto/auth.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/authz-dev/docs/manual/howto/auth.xml?rev=360027&r1=360026&r2=360027&view=diff
==============================================================================
--- httpd/httpd/branches/authz-dev/docs/manual/howto/auth.xml (original)
+++ httpd/httpd/branches/authz-dev/docs/manual/howto/auth.xml Fri Dec 30 00:21:06 2005
@@ -50,6 +50,7 @@
<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 @@
</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 @@
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 @@
<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 @@
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 @@
<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 @@
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 @@
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
- </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>
-
- <example>
- Order deny,allow<br />
- Deny from all<br />
- Allow from <var>dev.example.com</var>
+ <RequireAll><br />
+ Reject ip <var>192.101.205</var><br />
+ Reject host <var>cyberthugs.com</var> <var>moreidiots.com</var><br />
+ Reject host ke<br />
+ </RequireAll>
+ </example>
+
+ <p>Using the <directive module="mod_authz_host">Reject</directive> directive
+ inside of a <directive module="mod_authz_core"><RequireAll></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">
+ <RequireAll></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">
+ <RequireAll></directive> block as well as the
+ <directive module="mod_authz_core"><RequireOne></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 />
+ ((Group == "admin") && (ldap-group <ldap-object> contains auth'ed_user) &&<br />
+ ((ldap-attribute dept == "sales") ||
+ (file-group contains contains auth'ed_user))))<br />
+ then<br />
+ auth_granted<br />
+ else<br />
+ auth_denied<br />
+ </var></p>
+
+ <example>
+ <Directory /www/mydocs><br />
+ Authname ...<br />
+ AuthBasicProvider ...<br />
+ ...<br />
+ Require user John<br />
+ <RequireAll><br />
+ Require Group admins<br />
+ Require ldap-group cn=mygroup,o=foo<br />
+ <RequireOne><br />
+ Require ldap-attribute dept="sales"<br />
+ Require file-group<br />
+ </RequireOne><br />
+ </RequireAll><br />
+ </Directory><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>
Modified: httpd/httpd/branches/authz-dev/docs/manual/mod/core.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/authz-dev/docs/manual/mod/core.xml?rev=360027&r1=360026&r2=360027&view=diff
==============================================================================
--- httpd/httpd/branches/authz-dev/docs/manual/mod/core.xml (original)
+++ httpd/httpd/branches/authz-dev/docs/manual/mod/core.xml Fri Dec 30 00:21:06 2005
@@ -470,69 +470,6 @@
</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
scripts</description>
@@ -2392,101 +2329,6 @@
</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>
- <Directory /path/to/protected/><br />
- <indent>
- Require user david<br />
- </indent>
- </Directory><br />
- <Directory /path/to/protected/unprotected><br />
- <indent>
- # All access controls and authentication are disabled<br />
- # in this directory<br />
- Satisfy Any<br />
- Allow from all<br />
- </indent>
- </Directory><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
by Apache children</description>
@@ -2591,55 +2433,6 @@
</usage>
<seealso><directive module="core">RLimitMEM</directive></seealso>
<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>
Added: httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml?rev=360027&view=auto
==============================================================================
--- httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml (added)
+++ httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml Fri Dec 30 00:21:06 2005
@@ -0,0 +1,103 @@
+<?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>
Added: httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml.meta
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml.meta?rev=360027&view=auto
==============================================================================
--- httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml.meta (added)
+++ httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authn_core.xml.meta Fri Dec 30 00:21:06 2005
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<metafile>
+ <basename>mod_authn_core</basename>
+ <path>/mod/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
Added: httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml?rev=360027&view=auto
==============================================================================
--- httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml (added)
+++ httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml Fri Dec 30 00:21:06 2005
@@ -0,0 +1,222 @@
+<?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_authz_core.xml.meta">
+
+<name>mod_authz_core</name>
+<description>Core Authorization</description>
+<status>Base</status>
+<sourcefile>mod_authz_core.c</sourcefile>
+<identifier>authz_core_module</identifier>
+<compatibility>Available in Apache 2.3 and later</compatibility>
+
+<summary>
+ <p>This module provides core authorization capabilities so that
+ authenticated users can be allowed or denied access to portions
+ of the web site. <module>mod_authz_core</module> provides the
+ functionality to register various authorization providers. It is
+ usually used in conjunction with an authentication
+ provider module such as <module>mod_authn_file</module> and an
+ authorization module such as <module>mod_authz_user</module>. It
+ also allows for "AND" and "OR" logic to be applied to the
+ authorization processing.</p>
+</summary>
+
+<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>, <module>mod_authz_dbd</module>,
+ <module>mod_authz_host</module>, and
+ <module>mod_authz_owner</module>.</p>
+
+ <p>For a complete authentication and authorization configuration,
+ <directive>Require</directive> must be accompanied by
+ <directive module="mod_authn_core">AuthName</directive>, <directive
+ module="mod_authn_core">AuthType</directive> and
+ <directive module="mod_auth_basic">AuthBasicProvider</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 />
+ AuthBasicProvider file<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>
+
+</usage>
+
+<seealso><a href="../howto/auth.html">Authentication, Authorization,
+ and Access Control</a></seealso>
+<seealso><module>mod_authz_host</module></seealso>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>Reject</name>
+<description>Rejects which authenticated users can access
+a resource</description>
+<syntax>Reject <var>entity-name</var> [<var>entity-name</var>] ...</syntax>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+ <p>This directive is similar to the
+ <directive module="mod_authz_core">Require</directive> directive however
+ it rejects which authenticated users can access a resource. The
+ restrictions are processed by authorization modules. See the
+ <directive module="mod_authz_core">Require</directive> directive for details
+ about usage.</p>
+</usage>
+
+<seealso><a href="../howto/auth.html">Authentication, Authorization,
+ and Access Control</a></seealso>
+<seealso><module>mod_authz_host</module></seealso>
+</directivesynopsis>
+
+<directivesynopsis type="section">
+<name>RequireAll</name>
+<description>Enclose a group of authorization directives that must all
+be satisfied in order to grant access to a resource. This block allows
+for 'AND' logic to be applied to various authorization providers.</description>
+<syntax><RequireAll>
+... </RequireAll></syntax>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+ <p><directive type="section">RequireAll</directive> and
+ <code></RequireAll></code> are used to enclose a group of
+ authorization directives that must all be satisfied in order to
+ grant access to a resource.</p>
+
+ <p>The <directive module="mod_authz_core">
+ <RequireAll></directive> block as well as the
+ <directive module="mod_authz_core"><RequireOne></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 />
+ ((Group == "admin") && (ldap-group <ldap-object> contains auth'ed_user) &&<br />
+ ((ldap-attribute dept == "sales") ||
+ (file-group contains contains auth'ed_user))))<br />
+ then<br />
+ auth_granted<br />
+ else<br />
+ auth_denied<br />
+ </var></p>
+
+ <example>
+ <Directory /www/mydocs><br />
+ Authname ...<br />
+ AuthBasicProvider ...<br />
+ ...<br />
+ Require user John<br />
+ <RequireAll><br />
+ Require Group admins<br />
+ Require ldap-group cn=mygroup,o=foo<br />
+ <RequireOne><br />
+ Require ldap-attribute dept="sales"<br />
+ Require file-group<br />
+ </RequireOne><br />
+ </RequireAll><br />
+ </Directory><br />
+ </example>
+
+</usage>
+
+<seealso><a href="../howto/auth.html">Authentication, Authorization,
+ and Access Control</a></seealso>
+
+</directivesynopsis>
+
+<directivesynopsis type="section">
+<name>RequireOne</name>
+<description>Enclose a group of authorization directives that must
+satisfy at least one in order to grant access to a resource. This
+block allows for 'OR' logic to be applied to various authorization
+providers.</description>
+<syntax><RequireOne>
+... </RequireOne></syntax>
+<contextlist><context>directory</context><context>.htaccess</context>
+</contextlist>
+<override>AuthConfig</override>
+
+<usage>
+ <p><directive type="section">RequireOne</directive> and
+ <code></RequireOne></code> are used to enclose a group of
+ authorization directives that must satisfy at least one in order to
+ grant access to a resource.</p>
+
+ <p>See the <directive module="mod_authz_core">
+ <RequireAll></directive> directive for a usage example.</p>
+
+</usage>
+
+<seealso><a href="../howto/auth.html">Authentication, Authorization,
+ and Access Control</a></seealso>
+
+</directivesynopsis>
+
+</modulesynopsis>
Added: httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml.meta
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml.meta?rev=360027&view=auto
==============================================================================
--- httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml.meta (added)
+++ httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_core.xml.meta Fri Dec 30 00:21:06 2005
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<metafile>
+ <basename>mod_authz_core</basename>
+ <path>/mod/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
Modified: httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_host.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_host.xml?rev=360027&r1=360026&r2=360027&view=diff
==============================================================================
--- httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_host.xml (original)
+++ httpd/httpd/branches/authz-dev/docs/manual/mod/mod_authz_host.xml Fri Dec 30 00:21:06 2005
@@ -28,31 +28,21 @@
<status>Base</status>
<sourcefile>mod_authz_host.c</sourcefile>
<identifier>authz_host_module</identifier>
-<compatibility>Available in Apache 2.1 and later</compatibility>
+<compatibility>Available in Apache 2.3 and later</compatibility>
<summary>
- <p>The directives provided by <module>mod_authz_host</module> are
- used in <directive module="core" type="section">Directory</directive>,
- <directive module="core" type="section">Files</directive>, and
- <directive module="core" type="section">Location</directive> sections
+ <p>The authorization providers implemented by <module>mod_authz_host</module> are
+ registered using the <directive module="mod_authz_core">Require</directive> or
+ <directive module="mod_authz_core">Reject</directive> directives. These
+ directives can be referenced within a
+ <directive module="core" type="section">Directory</directive>,
+ <directive module="core" type="section">Files</directive>,
+ or <directive module="core" type="section">Location</directive> section
as well as <code><a href="core.html#accessfilename">.htaccess</a>
</code> files to control access to particular parts of the server.
Access can be controlled based on the client hostname, IP address, or
other characteristics of the client request, as captured in <a
- href="../env.html">environment variables</a>. The <directive
- module="mod_authz_host">Allow</directive> and <directive
- module="mod_authz_host">Deny</directive> directives are used to
- specify which clients are or are not allowed access to the server,
- while the <directive module="mod_authz_host">Order</directive>
- directive sets the default access state, and configures how the
- <directive module="mod_authz_host">Allow</directive> and <directive
- module="mod_authz_host">Deny</directive> directives interact with each
- other.</p>
-
- <p>Both host-based access restrictions and password-based
- authentication may be implemented simultaneously. In that case,
- the <directive module="core">Satisfy</directive> directive is used
- to determine how the two sets of restrictions interact.</p>
+ href="../env.html">environment variables</a>.</p>
<p>In general, access restriction directives apply to all
access methods (<code>GET</code>, <code>PUT</code>,
@@ -62,111 +52,33 @@
in a <directive module="core" type="section">Limit</directive> section.</p>
</summary>
-<seealso><directive module="core">Satisfy</directive></seealso>
-<seealso><directive module="core">Require</directive></seealso>
+<seealso><a href="../howto/auth.html">Authentication, Authorization,
+ and Access Control</a></seealso>
+<seealso><directive module="mod_authz_core">Require</directive></seealso>
+<seealso><directive module="mod_authz_core">Reject</directive></seealso>
+
+<section id="requiredirectives"><title>The require Directives</title>
+
+ <p>Apache's <directive module="mod_authz_core">Require</directive> and
+ <directive module="mod_authz_core">Reject</directive> directives are
+ used during the authorization phase to ensure that a user is allowed or
+ denied access to a resource. mod_authz_host extends the
+ authorization types with <code>env</code>, <code>ip</code>,
+ <code>host</code> and <code>all</code>. Other authorization types may also be
+ used but may require that additional authorization modules be loaded.</p>
-<directivesynopsis>
-<name>Allow</name>
-<description>Controls which hosts can access an area of the
-server</description>
-<syntax> Allow from all|<var>host</var>|env=<var>env-variable</var>
-[<var>host</var>|env=<var>env-variable</var>] ...</syntax>
-<contextlist><context>directory</context><context>.htaccess</context>
-</contextlist>
-<override>Limit</override>
-
-<usage>
- <p>The <directive>Allow</directive> directive affects which hosts can
+ <p>These authorization providers affect which hosts can
access an area of the server. Access can be controlled by
hostname, IP Address, IP Address range, or by other
characteristics of the client request captured in environment
variables.</p>
- <p>The first argument to this directive is always
- <code>from</code>. The subsequent arguments can take three
- different forms. If <code>Allow from all</code> is specified, then
- all hosts are allowed access, subject to the configuration of the
- <directive module="mod_authz_host">Deny</directive> and <directive
- module="mod_authz_host">Order</directive> directives as discussed
- below. To allow only particular hosts or groups of hosts to access
- the server, the <em>host</em> can be specified in any of the
- following formats:</p>
-
- <dl>
- <dt>A (partial) domain-name</dt>
-
- <dd>
- <example><title>Example:</title>
- Allow from apache.org<br />
- Allow from .net example.edu
- </example>
- <p>Hosts whose names match, or end in, this string are allowed
- access. Only complete components are matched, so the above
- example will match <code>foo.apache.org</code> but it will not
- match <code>fooapache.org</code>. This configuration will cause
- Apache to perform a double reverse DNS lookup on the client IP
- address, regardless of the setting of the <directive
- module="core">HostnameLookups</directive> directive. It will do
- a reverse DNS lookup on the IP address to find the associated
- hostname, and then do a forward lookup on the hostname to assure
- that it matches the original IP address. Only if the forward
- and reverse DNS are consistent and the hostname matches will
- access be allowed.</p></dd>
-
- <dt>A full IP address</dt>
-
- <dd>
- <example><title>Example:</title>
- Allow from 10.1.2.3<br />
- Allow from 192.168.1.104 192.168.1.205
- </example>
- <p>An IP address of a host allowed access</p></dd>
-
- <dt>A partial IP address</dt>
-
- <dd>
- <example><title>Example:</title>
- Allow from 10.1<br />
- Allow from 10 172.20 192.168.2
- </example>
- <p>The first 1 to 3 bytes of an IP address, for subnet
- restriction.</p></dd>
-
- <dt>A network/netmask pair</dt>
-
- <dd>
- <example><title>Example:</title>
- Allow from 10.1.0.0/255.255.0.0
- </example>
- <p>A network a.b.c.d, and a netmask w.x.y.z. For more
- fine-grained subnet restriction.</p></dd>
-
- <dt>A network/nnn CIDR specification</dt>
-
- <dd>
- <example><title>Example:</title>
- Allow from 10.1.0.0/16
- </example>
- <p>Similar to the previous case, except the netmask consists of
- nnn high-order 1 bits.</p></dd>
- </dl>
-
- <p>Note that the last three examples above match exactly the
- same set of hosts.</p>
-
- <p>IPv6 addresses and IPv6 subnets can be specified as shown
- below:</p>
-
- <example>
- Allow from 2001:db8::a00:20ff:fea7:ccea<br />
- Allow from 2001:db8::a00:20ff:fea7:ccea/10
- </example>
+<section id="reqenv"><title>require env</title>
- <p>The third format of the arguments to the
- <directive>Allow</directive> directive allows access to the server
+ <p>The <code>env</code> provider allows access to the server
to be controlled based on the existence of an <a
- href="../env.html">environment variable</a>. When <code>Allow from
- env=<var>env-variable</var></code> is specified, then the request is
+ href="../env.html">environment variable</a>. When <code>Require
+ env <var>env-variable</var></code> is specified, then the request is
allowed access if the environment variable <var>env-variable</var>
exists. The server provides the ability to set environment
variables in a flexible way based on characteristics of the client
@@ -175,162 +87,126 @@
used to allow access based on such factors as the clients
<code>User-Agent</code> (browser type), <code>Referer</code>, or
other HTTP request header fields.</p>
-
+
<example><title>Example:</title>
SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />
<Directory /docroot><br />
<indent>
- Order Deny,Allow<br />
- Deny from all<br />
- Allow from env=let_me_in<br />
+ Require env let_me_in<br />
</indent>
</Directory>
</example>
-
+
<p>In this case, browsers with a user-agent string beginning
with <code>KnockKnock/2.0</code> will be allowed access, and all
others will be denied.</p>
-</usage>
-</directivesynopsis>
-<directivesynopsis>
-<name>Deny</name>
-<description>Controls which hosts are denied access to the
-server</description>
-<syntax> Deny from all|<var>host</var>|env=<var>env-variable</var>
-[<var>host</var>|env=<var>env-variable</var>] ...</syntax>
-<contextlist><context>directory</context><context>.htaccess</context>
-</contextlist>
-<override>Limit</override>
-
-<usage>
- <p>This directive allows access to the server to be restricted
- based on hostname, IP address, or environment variables. The
- arguments for the <directive>Deny</directive> directive are
- identical to the arguments for the <directive
- module="mod_authz_host">Allow</directive> directive.</p>
-</usage>
-</directivesynopsis>
-
-<directivesynopsis>
-<name>Order</name>
-<description>Controls the default access state and the order in which
-<directive>Allow</directive> and <directive>Deny</directive> are
-evaluated.</description>
-<syntax> Order <var>ordering</var></syntax>
-<default>Order Deny,Allow</default>
-<contextlist><context>directory</context><context>.htaccess</context>
-</contextlist>
-<override>Limit</override>
-
-<usage>
- <p>The <directive>Order</directive> directive controls the default
- access state and the order in which <directive
- module="mod_authz_host">Allow</directive> and <directive
- module="mod_authz_host">Deny</directive> directives are evaluated.
- <var>Ordering</var> is one of</p>
-
- <dl>
- <dt><code>Deny,Allow</code></dt>
-
- <dd>The <directive module="mod_authz_host">Deny</directive> directives
- are evaluated before the <directive
- module="mod_authz_host">Allow</directive> directives. Access is
- allowed by default. Any client which does not match a
- <directive module="mod_authz_host">Deny</directive> directive or does
- match an <directive module="mod_authz_host">Allow</directive>
- directive will be allowed access to the server.</dd>
-
- <dt><code>Allow,Deny</code></dt>
-
- <dd>The <directive module="mod_authz_host">Allow</directive>
- directives are evaluated before the <directive
- module="mod_authz_host">Deny</directive> directives. Access is denied
- by default. Any client which does not match an <directive
- module="mod_authz_host">Allow</directive> directive or does match a
- <directive module="mod_authz_host">Deny</directive> directive will be
- denied access to the server.</dd>
-
- <dt><code>Mutual-failure</code></dt>
-
- <dd>Only those hosts which appear on the <directive
- module="mod_authz_host">Allow</directive> list and do not appear on
- the <directive module="mod_authz_host">Deny</directive> list are
- granted access. This ordering has the same effect as <code>Order
- Allow,Deny</code> and is deprecated in favor of that
- configuration.</dd>
- </dl>
-
- <p>Keywords may only be separated by a comma; <em>no whitespace</em> is
- allowed between them. Note that in all cases every <directive
- module="mod_authz_host">Allow</directive> and <directive
- module="mod_authz_host">Deny</directive> statement is evaluated.</p>
+</section>
+
+<section id="reqip"><title>require ip</title>
- <p>In the following example, all hosts in the apache.org domain
- are allowed access; all other hosts are denied access.</p>
+ <p>The <code>ip</code> provider allows access to the server
+ to be controlled based on the IP address of the remote client.
+ When <code>Require ip <var>ip-address</var></code> is specified,
+ then the request is allowed access if the IP address matches.</p>
+ <p>A full IP address:</p>
+
<example>
- Order Deny,Allow<br />
- Deny from all<br />
- Allow from apache.org
+ Require ip 10.1.2.3<br />
+ Require ip 192.168.1.104 192.168.1.205
</example>
- <p>In the next example, all hosts in the apache.org domain are
- allowed access, except for the hosts which are in the
- foo.apache.org subdomain, who are denied access. All hosts not
- in the apache.org domain are denied access because the default
- state is to deny access to the server.</p>
+ <p>An IP address of a host allowed access</p>
+
+ <p>A partial IP address:</p>
+
+ <example>
+ Require ip 10.1<br />
+ Require ip 10 172.20 192.168.2
+ </example>
+ <p>The first 1 to 3 bytes of an IP address, for subnet
+ restriction.</p>
+
+ <p>A network/netmask pair:</p>
+
+ <example>
+ Require ip 10.1.0.0/255.255.0.0
+ </example>
+ <p>A network a.b.c.d, and a netmask w.x.y.z. For more
+ fine-grained subnet restriction.</p>
+
+ <p>A network/nnn CIDR specification:</p>
+
+ <example>
+ Require ip 10.1.0.0/16
+ </example>
+ <p>Similar to the previous case, except the netmask consists of
+ nnn high-order 1 bits.</p>
+
+ <p>Note that the last three examples above match exactly the
+ same set of hosts.</p>
+
+ <p>IPv6 addresses and IPv6 subnets can be specified as shown
+ below:</p>
+
+ <example>
+ Require ip 2001:db8::a00:20ff:fea7:ccea<br />
+ Require ip 2001:db8::a00:20ff:fea7:ccea/10
+ </example>
+
+
+</section>
+
+<section id="reqhost"><title>require host</title>
+ <p>The <code>host</code> provider allows access to the server
+ to be controlled based on the host name of the remote client.
+ When <code>Require host <var>host-name</var></code> is specified,
+ then the request is allowed access if the host name matches.</p>
+
+ <p>A (partial) domain-name</p>
+
<example>
- Order Allow,Deny<br />
- Allow from apache.org<br />
- Deny from foo.apache.org
+ Require host apache.org<br />
+ Require host .net example.edu
</example>
+
+ <p>Hosts whose names match, or end in, this string are allowed
+ access. Only complete components are matched, so the above
+ example will match <code>foo.apache.org</code> but it will not
+ match <code>fooapache.org</code>. This configuration will cause
+ Apache to perform a double reverse DNS lookup on the client IP
+ address, regardless of the setting of the <directive
+ module="core">HostnameLookups</directive> directive. It will do
+ a reverse DNS lookup on the IP address to find the associated
+ hostname, and then do a forward lookup on the hostname to assure
+ that it matches the original IP address. Only if the forward
+ and reverse DNS are consistent and the hostname matches will
+ access be allowed.</p>
+
+</section>
+
+<section id="reqall"><title>require all</title>
+
+ <p>The <code>all</code> provider mimics the functionality the
+ was previously provided by the 'Allow from all' and 'Deny from all'
+ directives. This provider can take one of two arguments which are
+ 'granted' or 'denied'. The following examples will grant or deny
+ access to all requests.</p>
- <p>On the other hand, if the <directive>Order</directive> in the last
- example is changed to <code>Deny,Allow</code>, all hosts will
- be allowed access. This happens because, regardless of the
- actual ordering of the directives in the configuration file,
- the <code>Allow from apache.org</code> will be evaluated last
- and will override the <code>Deny from foo.apache.org</code>.
- All hosts not in the <code>apache.org</code> domain will also
- be allowed access because the default state will change to
- <em>allow</em>.</p>
-
- <p>The presence of an <directive>Order</directive> directive can affect
- access to a part of the server even in the absence of accompanying
- <directive module="mod_authz_host">Allow</directive> and <directive
- module="mod_authz_host">Deny</directive> directives because of its effect
- on the default access state. For example,</p>
+ <example>
+ Require all granted<br />
+ </example>
<example>
- <Directory /www><br />
- <indent>
- Order Allow,Deny<br />
- </indent>
- </Directory>
+ Require all denied<br />
</example>
- <p>will deny all access to the <code>/www</code> directory
- because the default access state will be set to
- <em>deny</em>.</p>
-
- <p>The <directive>Order</directive> directive controls the order of access
- directive processing only within each phase of the server's
- configuration processing. This implies, for example, that an
- <directive module="mod_authz_host">Allow</directive> or <directive
- module="mod_authz_host">Deny</directive> directive occurring in a
- <directive module="core" type="section">Location</directive> section will
- always be evaluated after an <directive
- module="mod_authz_host">Allow</directive> or <directive
- module="mod_authz_host">Deny</directive> directive occurring in a
- <directive module="core" type="section">Directory</directive> section or
- <code>.htaccess</code> file, regardless of the setting of the
- <directive>Order</directive> directive. For details on the merging
- of configuration sections, see the documentation on <a
- href="../sections.html">How Directory, Location and Files sections
- work</a>.</p>
-</usage>
-</directivesynopsis>
+</section>
+
+
+</section>
+
</modulesynopsis>