diff options
author | Chris Darroch <chrisd@apache.org> | 2008-11-02 04:28:02 +0000 |
---|---|---|
committer | Chris Darroch <chrisd@apache.org> | 2008-11-02 04:28:02 +0000 |
commit | 66b8ffda5e5426b671b838314d20cd93388f0593 (patch) | |
tree | 6802fd062bfe5cacca220b7e2ba3929a5d69f357 | |
parent | cf4e94f55e8a6434fee0fee2a8ee09beaf273591 (diff) | |
download | httpd-66b8ffda5e5426b671b838314d20cd93388f0593.tar.gz |
Documentation revisions for r709838 and r709839.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@709841 13f79535-47bb-0310-9956-ffa450edef68
-rw-r--r-- | docs/conf/httpd.conf.in | 11 | ||||
-rw-r--r-- | docs/manual/howto/auth.xml | 166 | ||||
-rw-r--r-- | docs/manual/mod/mod_access_compat.xml | 4 | ||||
-rw-r--r-- | docs/manual/mod/mod_auth_basic.xml | 5 | ||||
-rw-r--r-- | docs/manual/mod/mod_auth_digest.xml | 1 | ||||
-rw-r--r-- | docs/manual/mod/mod_auth_form.xml | 5 | ||||
-rw-r--r-- | docs/manual/mod/mod_authn_default.xml | 65 | ||||
-rw-r--r-- | docs/manual/mod/mod_authz_core.xml | 423 | ||||
-rw-r--r-- | docs/manual/mod/mod_authz_dbd.xml | 6 | ||||
-rw-r--r-- | docs/manual/mod/mod_authz_default.xml | 65 | ||||
-rw-r--r-- | docs/manual/mod/mod_authz_host.xml | 6 | ||||
-rw-r--r-- | docs/manual/new_features_2_4.xml | 21 |
12 files changed, 412 insertions, 366 deletions
diff --git a/docs/conf/httpd.conf.in b/docs/conf/httpd.conf.in index 1da6390bb1..5e65c7736d 100644 --- a/docs/conf/httpd.conf.in +++ b/docs/conf/httpd.conf.in @@ -154,17 +154,6 @@ DocumentRoot "@exp_htdocsdir@" # Controls who can get stuff from this server. # Require all granted - - # - # <Directory> and <Location> directives inherit their parent's authorization - # rules and applies them using AND logic instead of the previous OR logic of - # Apache 2.2 and before. To disable the merging of these rules use - # "AuthzMergeRules Off". - # - # This prevents the "Require all denied" rule in "<Directory />" above - # from being included in this directory's configuration. - # - AuthzMergeRules Off </Directory> # diff --git a/docs/manual/howto/auth.xml b/docs/manual/howto/auth.xml index fcf68aa703..2ec189bb57 100644 --- a/docs/manual/howto/auth.xml +++ b/docs/manual/howto/auth.xml @@ -54,7 +54,6 @@ module from each group.</p> <li><module>mod_authn_anon</module></li> <li><module>mod_authn_dbd</module></li> <li><module>mod_authn_dbm</module></li> - <li><module>mod_authn_default</module></li> <li><module>mod_authn_file</module></li> <li><module>mod_authnz_ldap</module></li> </ul> @@ -65,7 +64,6 @@ module from each group.</p> <li><module>mod_authnz_ldap</module></li> <li><module>mod_authz_dbd</module></li> <li><module>mod_authz_dbm</module></li> - <li><module>mod_authz_default</module></li> <li><module>mod_authz_groupfile</module></li> <li><module>mod_authz_host</module></li> <li><module>mod_authz_owner</module></li> @@ -430,12 +428,14 @@ person in</title> </Directory> </example> - <p>To take authorization a little further, the directives - <directive module="mod_authz_core"><SatisfyAll></directive> and - <directive module="mod_authz_core"><SatisfyOne></directive> allow - 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> + <p>To take authorization a little further, authorization container + directives such as + <directive module="mod_authz_core" type="section">MatchAll</directive> and + <directive module="mod_authz_core" type="section">MatchAny</directive> + allow logic to be applied so that the order in which authorization + is handled can be completely controled through the configuration. + See <a href="../mod/mod_authz_core.html#logic">Authorization + Containers</a> for an example of they may be applied.</p> </section> @@ -445,75 +445,61 @@ person in</title> 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> + <section id="authandororder"><title>Applying 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 + 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 + that the <directive module="mod_authz_core">Require</directive> and + <directive module="mod_authz_core">Match</directive> directives + not only specify which authorization methods should be used, they also specifies the order in which they are called. Multiple authorization 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"><SatisfyAll></directive> and - <directive module="mod_authz_core"><SatisfyOne></directive>, the - configuration also has control over when the + <directive module="mod_authz_core">Require</directive> + or <directive module="mod_authz_core">Match</directive> directives + appear in the configuration.</p> + + <p>With the introduction of authorization container directives + such as + <directive module="mod_authz_core" type="section">MatchAll</directive> + and + <directive module="mod_authz_core" type="section">MatchAny</directive>, + the 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> - - <example> - # if ((user == "John") ||<br /> - # ((Group == "admins")<br /> - # && (ldap-group <ldap-object> contains auth'ed_user)<br /> - # && ((ldap-attribute dept == "sales")<br /> - # || (file-group contains auth'ed_user))))<br /> - # then<br /> - # auth_granted<br /> - # else<br /> - # auth_denied<br /> - #<br /> - <Directory /www/mydocs><br /> - <indent> - Authname ...<br /> - AuthBasicProvider ...<br /> - ...<br /> - Require user John<br /> - <SatisfyAll><br /> - <indent> - Require Group admins<br /> - Require ldap-group cn=mygroup,o=foo<br /> - <SatisfyOne><br /> - <indent> - Require ldap-attribute dept="sales"<br /> - Require file-group<br /> - </indent> - </SatisfyOne><br /> - </indent> - </SatisfyAll><br /> - </indent> - </Directory> - </example> - - <p>By default all <directive module="mod_authz_core">Require</directive> - directives are handled through an OR operation. In other words, if + access is granted. See + <a href="../mod/mod_authz_core.html#logic">Authorization Containers</a> + for an example of how they may be used to express complex + authorization logic.</p> + + <p>By default all + <directive module="mod_authz_core">Require</directive> + directives are handled as though contained within a + <directive module="mod_authz_core" type="section">MatchAny</directive> + container directive. 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"><SatisfyAll></directive> block, - the processing switches to an AND operation which requires all authorization - methods to succeed before authorization is granted.</p> + is granted.</p> + + <p>In contrast, by default all + <directive module="mod_authz_core">Match</directive> directives + are handled as though contained within a + <directive module="mod_authz_core" type="section">MatchAll</directive> + container directive (unless they are explicitly contained within + a different authorization container directive). + This permits + <directive module="mod_authz_core">Match</directive> directives + to be usefully mixed with negated + <code>Match not</code> directives. To authorize the request, + none of the negated directives can match their parameters, + while all of the positive directives must match their + parameters (or else return a neutral result).</p> </section> - <section id="reqaccessctrl"><title>Using 'Require' or 'Reject' for access control</title> + <section id="reqaccessctrl"><title>Using authorization providers for access control</title> <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 @@ -526,10 +512,10 @@ person in</title> 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. + <directive module="mod_authz_core">Match</directive> directives. These directives register the authorization providers that will be called during the authorization stage of the request processing. For example:</p> @@ -554,7 +540,7 @@ person in</title> following:</p> <example> - Reject ip 10.252.46.165 + Match not ip 10.252.46.165 </example> <p>Visitors coming from that address will not be able to see @@ -562,30 +548,33 @@ person in</title> machine name, rather than an IP address, you can use that.</p> <example> - Reject host <var>host.example.com</var> + Match not 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> - <SatisfyAll><br /> + Match all granted<br /> + <MatchNotAny> <indent> - Reject ip <var>192.168.205</var><br /> - Reject host <var>phishers.example.com</var> <var>moreidiots.example</var><br /> Reject host ke<br /> + Match ip 192.168.205<br /> + Match host phishers.example.com moreidiots.example<br /> + Match host ke </indent> - </SatisfyAll> + </MatchNotAny> </example> - <p>Using the <directive module="mod_authz_host">Reject</directive> directive - inside of a <directive module="mod_authz_core"><SatisfyAll></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"> - <SatisfyAll></directive> block to make sure that all of the - <directive module="mod_authz_host">Reject</directive> directives are - satisfied before granting access. </p> + <p>The above example uses the <directive module="mod_authz_core" + type="section">MatchNotAny</directive> container directive + to make sure that none of the + <directive module="mod_authz_host">Match</directive> directives + match their parameters before granting access. Note that + the <code>Match all granted</code> directive and the + <directive module="mod_authz_core" + type="section">MatchNotAny</directive> are implicitly contained + within a <directive module="mod_authz_core" + type="section">MatchAll</directive> directive.</p> </section> @@ -598,23 +587,6 @@ person in</title> <directive module="mod_access_compat">Satisfy</directive> are no longer needed. However to provide backwards compatibility for older configurations, these directives have been moved to the <module>mod_access_compat</module> module.</p> - - <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> diff --git a/docs/manual/mod/mod_access_compat.xml b/docs/manual/mod/mod_access_compat.xml index 98e54ad5b3..de03558e86 100644 --- a/docs/manual/mod/mod_access_compat.xml +++ b/docs/manual/mod/mod_access_compat.xml @@ -60,9 +60,7 @@ have been deprecated by the new authz refactoring. Please see <note type="warning"><title>Note</title> <p>The directives provided by <module>mod_access_compat</module> have been deprecated by the new authz refactoring. Please see - <module>mod_authz_host</module>. The module - <module>mod_authz_default</module> must also be loaded to provide for - default authorization handling.</p> + <module>mod_authz_host</module>.</p> </note> <p>In general, access restriction directives apply to all diff --git a/docs/manual/mod/mod_auth_basic.xml b/docs/manual/mod/mod_auth_basic.xml index bbfd596f07..4c86d3adff 100644 --- a/docs/manual/mod/mod_auth_basic.xml +++ b/docs/manual/mod/mod_auth_basic.xml @@ -41,10 +41,7 @@ <seealso><directive module="mod_authn_core">AuthName</directive></seealso> <seealso><directive module="mod_authn_core">AuthType</directive></seealso> <seealso><directive module="mod_authz_core">Require</directive></seealso> -<seealso><directive module="mod_authz_core">Reject</directive></seealso> -<seealso><directive module="mod_access_compat">Satisfy</directive> (Deprecated)</seealso> -<seealso><directive module="mod_authz_core"><SatisfyAll></directive></seealso> -<seealso><directive module="mod_authz_core"><SatisfyOne></directive></seealso> +<seealso><directive module="mod_authz_core">Match</directive></seealso> <seealso><a href="../howto/auth.html">Authentication howto</a></seealso> <directivesynopsis> diff --git a/docs/manual/mod/mod_auth_digest.xml b/docs/manual/mod/mod_auth_digest.xml index 4a854f63b6..b05983cd45 100644 --- a/docs/manual/mod/mod_auth_digest.xml +++ b/docs/manual/mod/mod_auth_digest.xml @@ -38,6 +38,7 @@ <seealso><directive module="mod_authn_core">AuthName</directive></seealso> <seealso><directive module="mod_authn_core">AuthType</directive></seealso> <seealso><directive module="mod_authz_core">Require</directive></seealso> +<seealso><directive module="mod_authz_core">Match</directive></seealso> <seealso><a href="../howto/auth.html">Authentication howto</a></seealso> <section id="using"><title>Using Digest Authentication</title> diff --git a/docs/manual/mod/mod_auth_form.xml b/docs/manual/mod/mod_auth_form.xml index 64d8d4c7ad..da47390522 100644 --- a/docs/manual/mod/mod_auth_form.xml +++ b/docs/manual/mod/mod_auth_form.xml @@ -60,10 +60,7 @@ <seealso><directive module="mod_authn_core">AuthName</directive></seealso> <seealso><directive module="mod_authn_core">AuthType</directive></seealso> <seealso><directive module="mod_authz_core">Require</directive></seealso> -<seealso><directive module="mod_authz_core">Reject</directive></seealso> -<seealso><directive module="mod_access_compat">Satisfy</directive> (Deprecated)</seealso> -<seealso><directive module="mod_authz_core"><SatisfyAll></directive></seealso> -<seealso><directive module="mod_authz_core"><SatisfyOne></directive></seealso> +<seealso><directive module="mod_authz_core">Match</directive></seealso> <seealso><a href="../howto/auth.html">Authentication howto</a></seealso> <section id="basicconfig"><title>Basic Configuration</title> diff --git a/docs/manual/mod/mod_authn_default.xml b/docs/manual/mod/mod_authn_default.xml deleted file mode 100644 index 03c526679e..0000000000 --- a/docs/manual/mod/mod_authn_default.xml +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> -<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> -<!-- $LastChangedRevision$ --> - -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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_default.xml.meta"> - -<name>mod_authn_default</name> -<description>Authentication fallback module</description> -<status>Base</status> -<sourcefile>mod_authn_default.c</sourcefile> -<identifier>authn_default_module</identifier> -<compatibility>Available in Apache 2.1 and later</compatibility> - -<summary> - <p>This module is designed to be the fallback module, if you don't - have configured an authentication module like - <module>mod_auth_basic</module>. It simply rejects any - credentials supplied by the user.</p> -</summary> - -<directivesynopsis> -<name>AuthDefaultAuthoritative</name> -<description>Sets whether authentication is passed to lower level -modules</description> -<syntax>AuthDefaultAuthoritative On|Off</syntax> -<default>AuthDefaultAuthoritative On</default> -<contextlist><context>directory</context><context>.htaccess</context> -</contextlist> -<override>AuthConfig</override> - -<usage> - <p>Setting the <directive>AuthDefaultAuthoritative</directive> directive - explicitly to <code>Off</code> allows for authentication to be passed on - to lower level modules (as defined in the <code>modules.c</code> - files).</p> - - <note><title>Note</title> - <p>Normally there are no lower level modules, since - <module>mod_authn_default</module> is defined to be already on - a <em>very low</em> level. Therefore you should leave the value of - <directive>AuthDefaultAuthoritative</directive> as default - (<code>On</code>).</p> - </note> -</usage> -</directivesynopsis> - -</modulesynopsis> diff --git a/docs/manual/mod/mod_authz_core.xml b/docs/manual/mod/mod_authz_core.xml index f71a8f5854..3c0e7008ff 100644 --- a/docs/manual/mod/mod_authz_core.xml +++ b/docs/manual/mod/mod_authz_core.xml @@ -37,7 +37,7 @@ 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 + also allows for advanced logic to be applied to the authorization processing.</p> </summary> @@ -45,7 +45,8 @@ <p>Extended authorization providers can be created within the configuration file and assigned an alias name. The alias providers can then be referenced - through the <directive module="mod_authz_core">Require</directive> directive + through the <directive module="mod_authz_core">Require</directive> and + <directive module="mod_authz_core">Match</directive> directives in the same way as a base authorization provider. Besides the ability to create and alias an extended provider, it also allows the same extended authorization provider to be reference by multiple locations. @@ -59,13 +60,13 @@ </p> <example><title>Example</title> - <RequireAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx><br /> + <AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx><br /> <indent> AuthLDAPBindDN cn=youruser,o=ctx<br /> AuthLDAPBindPassword yourpassword<br /> AuthLDAPURL ldap://ldap.host/o=ctx<br /> </indent> - </RequireAlias><br /><br /> + </AuthzProviderAlias><br /><br /> <AuthnProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev><br /> <indent> @@ -73,7 +74,7 @@ AuthLDAPBindPassword yourotherpassword<br /> AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br /> </indent> - </RequireAlias><br /><br /> + </AuthzProviderAlias><br /><br /> Alias /secure /webpages/secure<br /> <Directory /webpages/secure><br /> @@ -95,19 +96,72 @@ </section> +<section id="logic"><title>Authorization Containers</title> + + <p>The authorization container directives + <directive module="mod_authz_core" type="section">MatchAll</directive>, + <directive module="mod_authz_core" type="section">MatchAny</directive>, + <directive module="mod_authz_core" type="section">MatchNotAll</directive> + and + <directive module="mod_authz_core" type="section">MatchNotAny</directive> + may be combined with each other and with the + <directive module="mod_authz_core">Match</directive> + directive to express complex authorization logic.</p> + + <p>The example below expresses the following authorization logic. + In order to access the resource, the user must either be the + <code>superadmin</code> user, or belong to both the + <code>admins</code> group and the <code>Administrators</code> LDAP + group and either belong to the <code>sales</code> group or + have the LDAP <code>dept</code> attribute <code>sales</code>. + Furthermore, in order to access the resource, the user must + not belong to either the <code>temps</code> group or the + LDAP group <code>Temporary Employees</code>.</p> + + <example> + <Directory /www/mydocs> + <indent> + <MatchAny> + <indent> + Match user superadmin<br /> + <MatchAll> + <indent> + Match group admins<br /> + Match ldap-group cn=Administrators,o=Airius<br /> + <MatchAny> + <indent> + Match group sales<br /> + Match ldap-attribute dept="sales" + </indent> + </MatchAny> + </indent> + </MatchAll> + </indent> + </MatchAny><br /> + <MatchNotAny> + <indent> + Match group temps<br /> + Match ldap-group cn=Temporary Employees,o=Airius + </indent> + </MatchNotAny> + </indent> + </Directory> + </example> +</section> + <directivesynopsis> <name>Require</name> -<description>Selects which authenticated users can access -a resource</description> +<description>Tests whether an authenticated user is authorized by +an authorization provider.</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 + <p>This directive tests whether an authenticated user is authorized + according to a particular authorization provider and the specified + restrictions. Some of the allowed syntaxes provided by <module>mod_authz_user</module> and <module>mod_authz_groupfile</module> are:</p> @@ -156,168 +210,331 @@ a resource</description> place the <directive>Require</directive> statement into a <directive module="core" type="section">Limit</directive> section.</p> - + + <p>When multiple <directive>Require</directive> directives are + used in a single + <a href="../sections.html#mergin">configuration section</a>, + the first one to authorize a user authorizes the entire request, + and subsequent <directive>Require</directive> directives are + ignored. In other words, all <directive>Require</directive> directives + are enclosed in an implied <directive module="mod_authz_core" + type="section">MatchAny</directive> directive.</p> + + <note><directive>Require</directive> directives may not be combined + with the <directive module="mod_authz_core">Match</directive> directive + or any authorization container directives, such as + <directive module="mod_authz_core" + type="section">MatchAll</directive>.</note> </usage> <seealso><a href="../howto/auth.html">Authentication, Authorization, and Access Control</a></seealso> +<seealso><module>mod_authn_core</module></seealso> <seealso><module>mod_authz_host</module></seealso> </directivesynopsis> <directivesynopsis> -<name>Reject</name> -<description>Rejects authenticated users or host based -requests from accessing a resource</description> -<syntax>Reject <var>entity-name</var> [<var>entity-name</var>] ...</syntax> +<name>Match</name> +<description>Tests whether an authenticated user is authorized by +an authorization provider.</description> +<syntax>Match [not] <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 or host based requests from accessing a resource. The - restrictions are processed by authorization modules. See the - <directive module="mod_authz_core">Require</directive> directive for details - about usage.</p> + <p>This directive is similar to the + <directive module="mod_authz_core">Require</directive> directive; + it tests whether an authenticated user is authorized according to + a particular authorization provider and the specified restrictions.</p> + + <p>Unlike the <directive module="mod_authz_core">Require</directive> + directive, it may be used with and inside authorization container + directives such as + <directive module="mod_authz_core" type="section">MatchAll</directive>.</p> + + <p>Furthermore, its result may be negated through the use of the + <code>not</code> option. As with other negated authorization directives, + in this case the <directive>Match</directive> directive may only + either fail or return a neutral result, and can therefore never + independently authorize a request.</p> + + <p>In the following example, all users in the <code>alpha</code> + and <code>beta</code> groups are authorized, except for those who + are also in the <code>reject</code> group.</p> + + <example> + <Directory /www/docs> + <indent> + Match group alpha beta<br /> + Match not group reject + </indent> + </Directory> + </example> + + <p>When multiple <directive>Match</directive> directives are + used in a single + <a href="../sections.html#mergin">configuration section</a> + and are not contained in another authorization directive like + <directive module="mod_authz_core" type="section">MatchAny</directive>, + they are implicitly contained within a + <directive module="mod_authz_core" type="section">MatchAll</directive> + directive. Thus for the user to be authorized, all such + <directive>Match</directive> directives must not fail, and + at least one must be successful.</p> + + <note><directive>Match</directive> directives may not be combined + with the <directive module="mod_authz_core">Require</directive> + directive.</note> </usage> +<seealso><directive module="mod_authz_core">Require</directive></seealso> +<seealso><a href="#logic">Authorization Containers</a></seealso> <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>SatisfyAll</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><SatisfyAll> -... </SatisfyAll></syntax> +<name>MatchAll</name> +<description>Enclose a group of authorization directives of which none +must fail and at least one must succeed for the enclosing directive to +succeed.</description> +<syntax><MatchAll> +... </MatchAll></syntax> <contextlist><context>directory</context><context>.htaccess</context> </contextlist> <override>AuthConfig</override> <usage> - <p><directive type="section">SatisfyAll</directive> and - <code></SatisfyAll></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><directive type="section">MatchAll</directive> and + <code></MatchAll></code> are used to enclose a group of + authorization directives of which none must fail and at least one + must succeed in order for + the <directive type="section">MatchAll</directive> directive to + succeed.</p> + + <p>If none of the directives contained within the + <directive type="section">MatchAll</directive> directive fails, + and at least one succeeds, then the + <directive type="section">MatchAll</directive> directive + succeeds. If none succeed and none fail, then it returns a + neutral result. In all other cases, it fails.</p> +</usage> - <p>The <directive module="mod_authz_core"> - <SatisfyAll></directive> block as well as the - <directive module="mod_authz_core"><SatisfyOne></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> +<seealso><a href="#logic">Authorization Containers</a></seealso> +<seealso><a href="../howto/auth.html">Authentication, Authorization, + and Access Control</a></seealso> - <example> - # if ((user == "John") ||<br /> - # ((Group == "admin")<br /> - # && (ldap-group <ldap-object> contains auth'ed_user)<br /> - # && ((ldap-attribute dept == "sales")<br /> - # || (file-group contains auth'ed_user))))<br /> - # then<br /> - # auth_granted<br /> - # else<br /> - # auth_denied<br /> - #<br /> - <Directory /www/mydocs><br /> - <indent> - Authname ...<br /> - AuthBasicProvider ...<br /> - ...<br /> - Require user John<br /> - <SatisfyAll><br /> - <indent> - Require Group admins<br /> - Require ldap-group cn=mygroup,o=foo<br /> - <SatisfyOne><br /> - <indent> - Require ldap-attribute dept="sales"<br /> - Require file-group<br /> - </indent> - </SatisfyOne><br /> - </indent> - </SatisfyAll><br /> - </indent> - </Directory> - </example> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>MatchAny</name> +<description>Enclose a group of authorization directives of which one +must succeed for the enclosing directive to succeed.</description> +<syntax><MatchAny> +... </MatchAny></syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p><directive type="section">MatchAny</directive> and + <code></MatchAny></code> are used to enclose a group of + authorization directives of which one must succeed in order for + the <directive type="section">MatchAny</directive> directive to + succeed.</p> + + <p>If one or more of the directives contained within the + <directive type="section">MatchAny</directive> directive succeed, + then the <directive type="section">MatchAny</directive> directive + succeeds. If none succeed and none fail, then it returns a + neutral result. In all other cases, it fails.</p> + + <note>Because negated authorization directives are unable to + return a successful result, they can not significantly influence + the result of a <directive type="section">MatchAny</directive> + directive. (At most they could cause the directive to fail in + the case where they failed and all other directives returned a + neutral value.) Therefore negated authorization directives + are not permitted within a <directive type="section">MatchAny</directive> + directive.</note> </usage> +<seealso><a href="#logic">Authorization Containers</a></seealso> <seealso><a href="../howto/auth.html">Authentication, Authorization, and Access Control</a></seealso> </directivesynopsis> <directivesynopsis type="section"> -<name>SatisfyOne</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><SatisfyOne> -... </SatisfyOne></syntax> +<name>MatchNotAll</name> +<description>Enclose a group of authorization directives of which some +must fail or none must succeed for the enclosing directive to +not fail.</description> +<syntax><MatchNotAll> +... </MatchNotAll></syntax> <contextlist><context>directory</context><context>.htaccess</context> </contextlist> <override>AuthConfig</override> <usage> - <p><directive type="section">SatisfyOne</directive> and - <code></SatisfyOne></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><directive type="section">MatchNotAll</directive> and + <code></MatchNotAll></code> are used to enclose a group of + authorization directives of which some must fail or none must succeed + in order for the + <directive type="section">MatchNotAll</directive> directive to + not fail.</p> + + <p>If none of the directives contained within the + <directive type="section">MatchNotAll</directive> directive + fail, and one or more succeed, then the + <directive type="section">MatchNotAll</directive> directive fails. + In all other cases, it returns a neutral result. Thus as with + the other negated authorization directives, it can never independently + authorize a request because it can never return a successful result. + It can be used, however, to restrict the set of users who are + authorized to access a resource.</p> +</usage> - <p>See the <directive module="mod_authz_core"> - <SatisfyAll></directive> directive for a usage example.</p> +<seealso><a href="#logic">Authorization Containers</a></seealso> +<seealso><a href="../howto/auth.html">Authentication, Authorization, + and Access Control</a></seealso> + +</directivesynopsis> +<directivesynopsis type="section"> +<name>MatchNotAny</name> +<description>Enclose a group of authorization directives of which none +none must succeed for the enclosing directive to not fail.</description> +<syntax><MatchNotAny> +... </MatchNotAny></syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p><directive type="section">MatchNotAny</directive> and + <code></MatchNotAny></code> are used to enclose a group of + authorization directives of which none must succeed + in order for the + <directive type="section">MatchNotAny</directive> directive to + not fail.</p> + + <p>If one or more of the directives contained within the + <directive type="section">MatchNotAny</directive> directive succeed, + then the <directive type="section">MatchNotAny</directive> directive + fails. In all other cases, it returns a neutral result. Thus as with + the other negated authorization directives, it can never independently + authorize a request because it can never return a successful result. + It can be used, however, to restrict the set of users who are + authorized to access a resource.</p> + + <note>Because negated authorization directives are unable to + return a successful result, they can not significantly influence + the result of a <directive type="section">MatchNotAny</directive> + directive. Therefore negated authorization directives + are not permitted within a + <directive type="section">MatchNotAny</directive> directive.</note> </usage> +<seealso><a href="#logic">Authorization Containers</a></seealso> <seealso><a href="../howto/auth.html">Authentication, Authorization, and Access Control</a></seealso> </directivesynopsis> <directivesynopsis> -<name>AuthzMergeRules</name> -<description>Set to 'on' to allow the parent's <Directory> or <Location> -authz rules to be merged into the current <Directory> or <Location>. -Set to 'off' to disable merging. If set to 'off', only the authz rules defined in -the current <Directory> or <Location> block will apply.</description> -<syntax>AuthzMergeRules on | off</syntax> -<default>AuthzMergeRules on</default> +<name>MergeAuthz</name> +<description>Controls the manner in which each configuration section's +authorization logic is combined with that of preceding configuration +sections.</description> +<syntax>MergeAuthz Off | MatchAll | MatchAny</syntax> +<default>MergeAuthz Off</default> <contextlist><context>directory</context><context>.htaccess</context> </contextlist> <override>AuthConfig</override> <usage> - <p>By default all of the authorization rules within a <Directory> - <Location> hierarchy are merged together to form a single - logical authorization operation. If AuthzMergeRules is set to 'off', then - only the authorization rules that are contained with the current - <Directory> or <Location> block are considered. This - allows the configuration to determine exactly how authorization will - be determined without having to take into consideration the - authorization rules that may exist above it.</p> + <p>When authorization is enabled, it is normally inherited by each + subsequent <a href="../sections.html#mergin">configuration section</a>, + unless a different set of authorization directives are specified. + This is the default action, which corresponds to an explicit setting + of <code>MergeAuthz Off</code>.</p> + + <p>However, there may be circumstances in which is it desirable + for a configuration section's authorization to be combined with + that of its predecessor while configuration sections are being + merged. Two options are available for this case, <code>MatchAll</code> + and <code>MatchAny</code>.</p> + + <p>When a configuration section contains <code>AuthzMerge MatchAll</code> + or <code>AuthzMerge MatchAny</code>, + its authorization logic is combined with that of the nearest + predecessor (according to the overall order of configuration sections) + which also contains authorization logic as if the two sections + were jointly contained within a + <directive module="mod_authz_core" type="section">MatchAll</directive> or + <directive module="mod_authz_core" type="section">MatchAny</directive> + directive, respectively.</p> + + <note>The setting of <directive>AuthzMerge</directive> is not + inherited outside of the configuration section in which it appears. + In the following example, only users belonging to group <code>alpha</code> + may access <code>/www/docs</code>. Users belonging to either + groups <code>alpha</code> or <code>beta</code> may access + <code>/www/docs/ab</code>. However, the default <code>Off</code> + setting of <directive>AuthzMerge</directive> applies to the + <directive type="section" module="core">Directory</directive> + configuration section for <code>/www/docs/ab/gamma</code>, so + that section's authorization directives override those of the + preceding sections. Thus only users belong to the group + <code>gamma</code> may access <code>/www/docs/ab/gamma</code>.</note> + + <example> + <Directory /www/docs> + <indent> + AuthType Basic<br /> + AuthName Documents<br /> + AuthBasicProvider file<br /> + AuthUserFile /usr/local/apache/passwd/passwords<br /> + Match group alpha + </indent> + </Directory><br /> + <br /> + <Directory /www/docs/ab> + <indent> + AuthzMerge MatchAny<br /> + Match group beta + </indent> + </Directory><br /> + <br /> + <Directory /www/docs/ab/gamma> + <indent> + Match group gamma + </indent> + </Directory> + </example> </usage> </directivesynopsis> <directivesynopsis type="section"> -<name>RequireAlias</name> +<name>AuthzProviderAlias</name> <description>Enclose a group of directives that represent an extension of a base authorization provider and referenced by the specified alias</description> -<syntax><RequireAlias <var>baseProvider Alias Require-Parameters</var>> -... </RequireAlias> +<syntax><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>> +... </AuthzProviderAlias> </syntax> <contextlist><context>server config</context> </contextlist> <usage> - <p><directive type="section">RequireAlias</directive> and - <code></RequireAlias></code> are used to enclose a group of + <p><directive type="section">AuthzProviderAlias</directive> and + <code></AuthzProviderAlias></code> are used to enclose a group of authorization directives that can be referenced by the alias name using the - directive <directive module="mod_authz_core"> Require</directive>.</p> + directive <directive module="mod_authz_core">Require</directive>.</p> </usage> </directivesynopsis> diff --git a/docs/manual/mod/mod_authz_dbd.xml b/docs/manual/mod/mod_authz_dbd.xml index 3cdff7fb4b..3cfdf5b5d4 100644 --- a/docs/manual/mod/mod_authz_dbd.xml +++ b/docs/manual/mod/mod_authz_dbd.xml @@ -47,9 +47,6 @@ <seealso><directive module="mod_authz_core">Require</directive></seealso> <seealso> - <directive module="mod_authz_core">AuthzMergeRules</directive> -</seealso> -<seealso> <directive module="mod_authn_dbd">AuthDBDUserPWQuery</directive> </seealso> <seealso><directive module="mod_dbd">DBDriver</directive></seealso> @@ -106,7 +103,6 @@ DBDExptime 300 "SELECT password FROM authn WHERE user = %s AND login = 'true'" # mod_authz_core configuration for mod_authz_dbd - AuthzMergeRules Off Require dbd-group team # mod_authz_dbd configuration @@ -123,7 +119,6 @@ DBDExptime 300 "SELECT password FROM authn WHERE user = %s" # dbd-login action executes a statement to log user in - AuthzMergeRules Off Require dbd-login AuthzDBDQuery \ "UPDATE authn SET login = 'true' WHERE user = %s" @@ -135,7 +130,6 @@ DBDExptime 300 <Files logout.html> # dbd-logout action executes a statement to log user out - AuthzMergeRules Off Require dbd-logout AuthzDBDQuery \ "UPDATE authn SET login = 'false' WHERE user = %s" diff --git a/docs/manual/mod/mod_authz_default.xml b/docs/manual/mod/mod_authz_default.xml deleted file mode 100644 index 5bebc02836..0000000000 --- a/docs/manual/mod/mod_authz_default.xml +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> -<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> -<!-- $LastChangedRevision$ --> - -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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_default.xml.meta"> - -<name>mod_authz_default</name> -<description>Authorization fallback module</description> -<status>Base</status> -<sourcefile>mod_authz_default.c</sourcefile> -<identifier>authz_default_module</identifier> -<compatibility>Available in Apache 2.1 and later</compatibility> - -<summary> - <p>This module is designed to be the fallback module, if you don't - have configured an authorization module like - <module>mod_authz_user</module> or <module>mod_authz_groupfile</module>. - It simply rejects any authorization request.</p> -</summary> - -<directivesynopsis> -<name>AuthzDefaultAuthoritative</name> -<description>Sets whether authorization is passed to lower level -modules</description> -<syntax>AuthzDefaultAuthoritative On|Off</syntax> -<default>AuthzDefaultAuthoritative On</default> -<contextlist><context>directory</context><context>.htaccess</context> -</contextlist> -<override>AuthConfig</override> - -<usage> - <p>Setting the <directive>AuthzDefaultAuthoritative</directive> directive - explicitly to <code>Off</code> allows for authorization to be passed on - to lower level modules (as defined in the <code>modules.c</code> - files).</p> - - <note><title>Note</title> - <p>Normally there are no lower level modules, since - <module>mod_authz_default</module> is defined to be already on - a <em>very low</em> level. Therefore you should leave the value of - <directive>AuthzDefaultAuthoritative</directive> as default - (<code>On</code>).</p> - </note> -</usage> -</directivesynopsis> - -</modulesynopsis> diff --git a/docs/manual/mod/mod_authz_host.xml b/docs/manual/mod/mod_authz_host.xml index fc6e5621e1..743cf2334d 100644 --- a/docs/manual/mod/mod_authz_host.xml +++ b/docs/manual/mod/mod_authz_host.xml @@ -33,7 +33,7 @@ address)</description> <summary> <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 + <directive module="mod_authz_core">Match</directive> directives. These directives can be referenced within a <directive module="core" type="section">Directory</directive>, <directive module="core" type="section">Files</directive>, @@ -55,12 +55,12 @@ address)</description> <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> +<seealso><directive module="mod_authz_core">Match</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 + <directive module="mod_authz_core">Match</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>, diff --git a/docs/manual/new_features_2_4.xml b/docs/manual/new_features_2_4.xml index 2a7abaa0e6..f515f345b9 100644 --- a/docs/manual/new_features_2_4.xml +++ b/docs/manual/new_features_2_4.xml @@ -64,11 +64,22 @@ console. The user can thus be alerted to misconfiguration problems before the core <code>open_logs</code> hook function redirects console output to the error log.</dd> - <dt>Expression Parser Added</dt> - <dd>We now have a general-purpose expression parser, whose API is - exposed in <var>ap_expr.h</var>. This is adapted from the - expression parser previously implemented in - <module>mod_include</module>.</dd> + + <dt>Expression Parser Added</dt> + + <dd>We now have a general-purpose expression parser, whose API is + exposed in <var>ap_expr.h</var>. This is adapted from the + expression parser previously implemented in + <module>mod_include</module>.</dd> + + <dt>Authorization Logic Containers</dt> + + <dd>Advanced authorization logic may now be specified using the + <directive module="mod_authz_core">Match</directive> directive + and the related container directives, such as + <directive module="mod_authz_core" + type="section">MatchAll</directive>, all + provided by the <module>mod_authz_core</module> module.</dd> </dl> </section> </manualpage> |