From: Chris Darroch Date: Fri, 19 Dec 2008 19:57:02 +0000 (+0000) Subject: Documentation revisions for r726082. X-Git-Tag: 2.3.1~103 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=e884a2816280aaff4145b71b891ac607f4a3a2cb;p=apache Documentation revisions for r726082. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@728126 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/auth.xml b/docs/manual/howto/auth.xml index 49a8a09768..2d5500ab16 100644 --- a/docs/manual/howto/auth.xml +++ b/docs/manual/howto/auth.xml @@ -430,8 +430,9 @@ person in

To take authorization a little further, authorization container directives such as - MatchAll and - MatchAny + RequireAll + and + RequireAny allow logic to be applied so that the order in which authorization is handled can be completely controled through the configuration. See Authorization @@ -454,20 +455,18 @@ person in 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 Require and - Match directives - not only specify which authorization methods should be used, they also + that the Require directive + not only specifies which authorization methods should be used, it also specifies the order in which they are called. Multiple authorization - methods are called in the same order in which the - Require - or Match directives + methods are called in the same order in which the + Require directives appear in the configuration.

With the introduction of authorization container directives such as - MatchAll + RequireAll and - MatchAny, + RequireAny, the configuration also has control over when the authorization methods are called and what criteria determines when access is granted. See @@ -478,25 +477,11 @@ person in

By default all Require directives are handled as though contained within a - MatchAny + RequireAny container directive. In other words, if any of the specified authorization methods succeed, then authorization is granted.

-

In contrast, by default all - Match directives - are handled as though contained within a - MatchAll - container directive (unless they are explicitly contained within - a different authorization container directive). - This permits - Match directives - to be usefully mixed with negated - Match not 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).

-
Using authorization providers for access control @@ -514,9 +499,8 @@ person in a document.

The usage of these providers is specified through the - Require and - Match directives. - These directives register the authorization providers + Require directive. + This directive registers the authorization providers that will be called during the authorization stage of the request processing. For example:

@@ -540,7 +524,12 @@ person in following:

- Match not ip 10.252.46.165 + <RequireAll> + + Require all granted
+ Require not ip 10.252.46.165 + + </RequireAll>

Visitors coming from that address will not be able to see @@ -548,33 +537,38 @@ person in machine name, rather than an IP address, you can use that.

- Match not host host.example.com + <RequireAll> + + Require all granted
+ Require not host host.example.com + + </RequireAll>

And, if you'd like to block access from an entire domain, you can specify just part of an address or domain name:

- Match all granted
- <MatchNotAny> + <RequireAll> - Match ip 192.168.205
- Match host phishers.example.com moreidiots.example
- Match host ke + Require all granted
+ <RequireNone> + + Require ip 192.168.205
+ Require host phishers.example.com moreidiots.example
+ Require host ke + + </RequireNone> - </MatchNotAny> + </RequireAll>

The above example uses the MatchNotAny container directive + type="section">RequireNone directive to make sure that none of the - Match directives - match their parameters before granting access. Note that - the Match all granted directive and the - MatchNotAny are implicitly contained - within a MatchAll directive.

+ Require directives + contained within it + match their parameters before granting access.

diff --git a/docs/manual/mod/mod_authz_core.xml b/docs/manual/mod/mod_authz_core.xml index c23fed379a..2b740e5035 100644 --- a/docs/manual/mod/mod_authz_core.xml +++ b/docs/manual/mod/mod_authz_core.xml @@ -45,8 +45,7 @@

Extended authorization providers can be created within the configuration file and assigned an alias name. The alias providers can then be referenced - through the Require and - Match directives + through the Require directive 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. @@ -99,13 +98,12 @@

Authorization Containers

The authorization container directives - MatchAll, - MatchAny, - MatchNotAll + RequireAll, + RequireAny and - MatchNotAny + RequireNone may be combined with each other and with the - Match + Require directive to express complex authorization logic.

The example below expresses the following authorization logic. @@ -121,29 +119,33 @@ <Directory /www/mydocs> - <MatchAny> + <RequireAll> - Match user superadmin
- <MatchAll> + <RequireAny> - Match group admins
- Match ldap-group cn=Administrators,o=Airius
- <MatchAny> + Require user superadmin
+ <RequireAll> - Match group sales
- Match ldap-attribute dept="sales" + Require group admins
+ Require ldap-group cn=Administrators,o=Airius
+ <RequireAny> + + Require group sales
+ Require ldap-attribute dept="sales" + + </RequireAny> - </MatchAny> + </RequireAll> - </MatchAll> - - </MatchAny>
- <MatchNotAny> - - Match group temps
- Match ldap-group cn=Temporary Employees,o=Airius + </RequireAny>
+ <RequireNone> + + Require group temps
+ Require ldap-group cn=Temporary Employees,o=Airius + + </RequireNone> - </MatchNotAny> + </RequireAll> </Directory> @@ -153,7 +155,8 @@ Require Tests whether an authenticated user is authorized by an authorization provider. -Require entity-name [entity-name] ... +Require [not] entity-name + [entity-name] ... directory.htaccess AuthConfig @@ -212,53 +215,12 @@ an authorization provider. Limit section.

-

When multiple Require directives are - used in a single - configuration section, - the first one to authorize a user authorizes the entire request, - and subsequent Require directives are - ignored. In other words, all Require directives - are enclosed in an implied MatchAny directive.

- - Require directives may not be combined - with the Match directive - or any authorization container directives, such as - MatchAll. - - -Authentication, Authorization, - and Access Control -mod_authn_core -mod_authz_host - - - -Match -Tests whether an authenticated user is authorized by -an authorization provider. -Match [not] entity-name -[entity-name] ... -directory.htaccess - -AuthConfig - - -

This directive is similar to the - Require directive; - it tests whether an authenticated user is authorized according to - a particular authorization provider and the specified restrictions.

- -

Unlike the Require - directive, it may be used with and inside authorization container - directives such as - MatchAll.

- -

Furthermore, its result may be negated through the use of the - not option. As with other negated authorization directives, - in this case the Match directive may only - either fail or return a neutral result, and can therefore never +

The result of the Require directive + may be negated through the use of the + not option. As with the other negated authorization + directive RequireNone, + when the Require directive is negated it can + only fail or return a neutral result, and therefore may never independently authorize a request.

In the following example, all users in the alpha @@ -268,57 +230,57 @@ an authorization provider. <Directory /www/docs> - Match group alpha beta
- Match not group reject + <RequireAll> + + Require group alpha beta
+ Require not group reject + + </RequireAll> </Directory> -

When multiple Match directives are +

When multiple Require directives are used in a single configuration section and are not contained in another authorization directive like - MatchAny, + RequireAll, they are implicitly contained within a - MatchAll - directive. Thus for the user to be authorized, all such - Match directives must not fail, and - at least one must be successful.

- - Match directives may not be combined - with the Require - directive. + RequireAny + directive. Thus the first one to authorize a user authorizes the + entire request, and subsequent Require directives + are ignored.

 -Require -Authorization Containers Authentication, Authorization, and Access Control +Authorization Containers +mod_authn_core +mod_authz_host -MatchAll +RequireAll Enclose a group of authorization directives of which none must fail and at least one must succeed for the enclosing directive to succeed. -<MatchAll> -... </MatchAll> +<RequireAll> ... </RequireAll> directory.htaccess AuthConfig -

MatchAll and - </MatchAll> are used to enclose a group of +

RequireAll and + </RequireAll> are used to enclose a group of authorization directives of which none must fail and at least one must succeed in order for - the MatchAll directive to + the RequireAll directive to succeed.

If none of the directives contained within the - MatchAll directive fails, + RequireAll directive fails, and at least one succeeds, then the - MatchAll directive + RequireAll directive succeeds. If none succeed and none fail, then it returns a neutral result. In all other cases, it fails.

 @@ -330,35 +292,34 @@ succeed. -MatchAny +RequireAny Enclose a group of authorization directives of which one must succeed for the enclosing directive to succeed. -<MatchAny> -... </MatchAny> +<RequireAny> ... </RequireAny> directory.htaccess AuthConfig -

MatchAny and - </MatchAny> are used to enclose a group of +

RequireAny and + </RequireAny> are used to enclose a group of authorization directives of which one must succeed in order for - the MatchAny directive to + the RequireAny directive to succeed.

If one or more of the directives contained within the - MatchAny directive succeed, - then the MatchAny directive + RequireAny directive succeed, + then the RequireAny directive succeeds. If none succeed and none fail, then it returns a neutral result. In all other cases, it fails.

Because negated authorization directives are unable to return a successful result, they can not significantly influence - the result of a MatchAny + the result of a RequireAny 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 MatchAny + are not permitted within a RequireAny directive. @@ -369,74 +330,38 @@ must succeed for the enclosing directive to succeed. -MatchNotAll -Enclose a group of authorization directives of which some -must fail or none must succeed for the enclosing directive to -not fail. -<MatchNotAll> -... </MatchNotAll> -directory.htaccess - -AuthConfig - - -

MatchNotAll and - </MatchNotAll> are used to enclose a group of - authorization directives of which some must fail or none must succeed - in order for the - MatchNotAll directive to - not fail.

- -

If none of the directives contained within the - MatchNotAll directive - fail, and one or more succeed, then the - MatchNotAll 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.

- - -Authorization Containers -Authentication, Authorization, - and Access Control - - - - -MatchNotAny +RequireNone Enclose a group of authorization directives of which none -none must succeed for the enclosing directive to not fail. -<MatchNotAny> -... </MatchNotAny> +must succeed for the enclosing directive to not fail. +<RequireNone> ... </RequireNone> directory.htaccess AuthConfig -

MatchNotAny and - </MatchNotAny> are used to enclose a group of +

RequireNone and + </RequireNone> are used to enclose a group of authorization directives of which none must succeed in order for the - MatchNotAny directive to + RequireNone directive to not fail.

If one or more of the directives contained within the - MatchNotAny directive succeed, - then the MatchNotAny directive + RequireNone directive succeed, + then the RequireNone directive fails. In all other cases, it returns a neutral result. Thus as with - the other negated authorization directives, it can never independently + the other negated authorization directive Require not, + 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.

Because negated authorization directives are unable to return a successful result, they can not significantly influence - the result of a MatchNotAny + the result of a RequireNone directive. Therefore negated authorization directives are not permitted within a - MatchNotAny directive. + RequireNone directive. Authorization Containers @@ -446,12 +371,12 @@ none must succeed for the enclosing directive to not fail. -MergeAuthz +AuthMerging Controls the manner in which each configuration section's authorization logic is combined with that of preceding configuration sections. -MergeAuthz Off | MatchAll | MatchAny -MergeAuthz Off +AuthMerging Off | And | Or +AuthMerging Off directory.htaccess AuthConfig @@ -461,31 +386,31 @@ sections. subsequent configuration section, unless a different set of authorization directives are specified. This is the default action, which corresponds to an explicit setting - of MergeAuthz Off.

+ of AuthMerging Off.

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, MatchAll - and MatchAny.

+ merged. Two options are available for this case, And + and Or.

-

When a configuration section contains AuthzMerge MatchAll - or AuthzMerge MatchAny, +

When a configuration section contains AuthMerging And + or AuthMerging Or, 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 - MatchAll or - MatchAny + RequireAll or + RequireAny directive, respectively.

- The setting of AuthzMerge is not + The setting of AuthMerging is not inherited outside of the configuration section in which it appears. In the following example, only users belonging to group alpha may access /www/docs. Users belonging to either groups alpha or beta may access /www/docs/ab. However, the default Off - setting of AuthzMerge applies to the + setting of AuthMerging applies to the Directory configuration section for /www/docs/ab/gamma, so that section's authorization directives override those of the @@ -499,20 +424,20 @@ sections. AuthName Documents
AuthBasicProvider file
AuthUserFile /usr/local/apache/passwd/passwords
- Match group alpha + Require group alpha </Directory>

<Directory /www/docs/ab> - AuthzMerge MatchAny
- Match group beta + AuthMerging Or
+ Require group beta </Directory>

<Directory /www/docs/ab/gamma> - Match group gamma + Require group gamma </Directory> diff --git a/docs/manual/new_features_2_4.xml b/docs/manual/new_features_2_4.xml index f515f345b9..1d844c4834 100644 --- a/docs/manual/new_features_2_4.xml +++ b/docs/manual/new_features_2_4.xml @@ -75,10 +75,10 @@
Authorization Logic Containers
Advanced authorization logic may now be specified using the - Match directive + Require directive and the related container directives, such as MatchAll, all + type="section">RequireAll, all provided by the mod_authz_core module.