Applying AND/OR logic and ordering

To take authorization a little further, the directives - <SatisfyAll> and - <SatisfyOne> 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.

To take authorization a little further, authorization container + directives such as + MatchAll and + MatchAny + allow logic to be applied so that the order in which authorization + is handled can be completely controled through the configuration. + See Authorization + Containers for an example of they may be applied.

Applying AND/OR logic and ordering +

Applying logic and ordering

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 Require directive - not only specifies which authorization methods should be used, it also + that the Require and + Match 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 - Require directives appear - in the configuration.

- -

With the introduction of the directives - <SatisfyAll> and - <SatisfyOne>, the - configuration also has control over when the + Require + or Match directives + appear in the configuration.

+ +

With the introduction of authorization container directives + such as + MatchAll + and + MatchAny, + 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:

- - - # if ((user == "John") ||
- # ((Group == "admins")
- # && (ldap-group <ldap-object> contains auth'ed_user)
- # && ((ldap-attribute dept == "sales")
- # || (file-group contains auth'ed_user))))
- # then
- # auth_granted
- # else
- # auth_denied
- #
- <Directory /www/mydocs>
- - Authname ...
- AuthBasicProvider ...
- ...
- Require user John
- <SatisfyAll>
- - Require Group admins
- Require ldap-group cn=mygroup,o=foo
- <SatisfyOne>
- - Require ldap-attribute dept="sales"
- Require file-group
- - </SatisfyOne>
- - </SatisfyAll>
- - </Directory> - - -

By default all Require - directives are handled through an OR operation. In other words, if + access is granted. See + Authorization Containers + for an example of how they may be used to express complex + authorization logic.

+ +

By default all + Require + directives are handled as though contained within a + MatchAny + container directive. In other words, if any of the specified authorization methods succeed, then authorization - is granted. By enclosing a set of - Require directives within - a <SatisfyAll> block, - the processing switches to an AND operation which requires all authorization - methods to succeed before authorization is granted.

+ 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 'Require' or 'Reject' for access control +

Using authorization providers for access control

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 @@ ip let you allow or deny access based other host based criteria such as host name or ip address of the machine requesting a document.

- +

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

@@ -554,7 +540,7 @@ following:

- Reject ip 10.252.46.165 + Match not ip 10.252.46.165

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

- Reject host host.example.com + Match not host host.example.com

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

- <SatisfyAll>
+ Match all granted
+ <MatchNotAny> - Reject ip 192.168.205
- Reject host phishers.example.com moreidiots.example
Reject host ke
+ Match ip 192.168.205
+ Match host phishers.example.com moreidiots.example
+ Match host ke - </SatisfyAll> + </MatchNotAny> -

Using the Reject directive - inside of a <SatisfyAll> - block, will let you be sure that you are actually restricting things to - only the group that you want to let in.

- -

The above example uses the - <SatisfyAll> block to make sure that all of the - Reject directives are - satisfied before granting access.

The above example uses the MatchNotAny container 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.

@@ -598,23 +587,6 @@ Satisfy are no longer needed. However to provide backwards compatibility for older configurations, these directives have been moved to the mod_access_compat module.

- -

One of the problems with these directives was that the line between - authorization and access control was very fuzzy. The - Satisfy 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 - mod_access_compat, mixing the new authorization directives - with the older access control directives becomes difficult. To address this - issue, the mod_authz_default module becomes very important and must - be loaded. The main purpose of the mod_authz_default 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 - mod_authz_default module has not been loaded.

In general, access restriction directives apply to all Modified: httpd/httpd/trunk/docs/manual/mod/mod_auth_basic.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_auth_basic.xml?rev=709841&r1=709840&r2=709841&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_auth_basic.xml (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_auth_basic.xml Sat Nov 1 21:28:02 2008 @@ -41,10 +41,7 @@ AuthName AuthType Require -Reject -Satisfy (Deprecated) -<SatisfyAll> -<SatisfyOne> +Match Authentication howto Modified: httpd/httpd/trunk/docs/manual/mod/mod_auth_digest.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_auth_digest.xml?rev=709841&r1=709840&r2=709841&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_auth_digest.xml (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_auth_digest.xml Sat Nov 1 21:28:02 2008 @@ -38,6 +38,7 @@ AuthName AuthType Require +Match Authentication howto

Using Digest Authentication Modified: httpd/httpd/trunk/docs/manual/mod/mod_auth_form.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_auth_form.xml?rev=709841&r1=709840&r2=709841&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_auth_form.xml (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_auth_form.xml Sat Nov 1 21:28:02 2008 @@ -60,10 +60,7 @@ AuthName AuthType Require -Reject -Satisfy (Deprecated) -<SatisfyAll> -<SatisfyOne> +Match Authentication howto

Basic Configuration Modified: httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml?rev=709841&r1=709840&r2=709841&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_authz_core.xml Sat Nov 1 21:28:02 2008 @@ -37,7 +37,7 @@ usually used in conjunction with an authentication provider module such as mod_authn_file and an authorization module such as mod_authz_user. 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.

@@ -45,7 +45,8 @@

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 directive + through the Require and + Match 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 @@

Example - <RequireAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
+ <AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
AuthLDAPBindDN cn=youruser,o=ctx
AuthLDAPBindPassword yourpassword
AuthLDAPURL ldap://ldap.host/o=ctx
- </RequireAlias>

+ </AuthzProviderAlias>

<AuthnProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev>
@@ -73,7 +74,7 @@ AuthLDAPBindPassword yourotherpassword
AuthLDAPURL ldap://other.ldap.host/o=dev?cn
- </RequireAlias>

+ </AuthzProviderAlias>

Alias /secure /webpages/secure
<Directory /webpages/secure>
@@ -95,19 +96,72 @@

Authorization Containers + +

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

+ +

The example below expresses the following authorization logic. + In order to access the resource, the user must either be the + superadmin user, or belong to both the + admins group and the Administrators LDAP + group and either belong to the sales group or + have the LDAP dept attribute sales. + Furthermore, in order to access the resource, the user must + not belong to either the temps group or the + LDAP group Temporary Employees.

+ + + <Directory /www/mydocs> + + <MatchAny> + + Match user superadmin
+ <MatchAll> + + Match group admins
+ Match ldap-group cn=Administrators,o=Airius
+ <MatchAny> + + Match group sales
+ Match ldap-attribute dept="sales" + + </MatchAny> + + </MatchAll> + + </MatchAny>
+ <MatchNotAny> + + Match group temps
+ Match ldap-group cn=Temporary Employees,o=Airius + + </MatchNotAny> + + </Directory> + +

+ Require -Selects which authenticated users can access -a resource +Tests whether an authenticated user is authorized by +an authorization provider. Require entity-name [entity-name] ... directory.htaccess AuthConfig -

This directive selects which authenticated users can access a - resource. The restrictions are processed by authorization - modules. Some of the allowed syntaxes provided by +

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 mod_authz_user and mod_authz_groupfile are:

@@ -156,168 +210,331 @@ place the Require statement into a 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 -Reject -Rejects authenticated users or host based -requests from accessing a resource -Reject entity-name [entity-name] ... +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 however - it rejects which authenticated users or host based requests from accessing a resource. The - restrictions are processed by authorization modules. See the - Require directive for details - about usage.

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 + independently authorize a request.

+ +

In the following example, all users in the alpha + and beta groups are authorized, except for those who + are also in the reject group.

+ + + <Directory /www/docs> + + Match group alpha beta
+ Match not group reject + + </Directory> + + +

When multiple Match directives are + used in a single + configuration section + and are not contained in another authorization directive like + MatchAny, + 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. +Require +Authorization Containers Authentication, Authorization, and Access Control -mod_authz_host -SatisfyAll -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. -<SatisfyAll> -... </SatisfyAll> +MatchAll +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> directory.htaccess AuthConfig -

SatisfyAll and - </SatisfyAll> are used to enclose a group of - authorization directives that must all be satisfied in order to - grant access to a resource.

- -

The - <SatisfyAll> block as well as the - <SatisfyOne> block - allow you to apply "AND" and "OR" logic to the authorization processing. - For example the following authorization block would apply the logic:

MatchAll and + </MatchAll> 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 + succeed.

+ +

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

+ - - # if ((user == "John") ||
- # ((Group == "admin")
- # && (ldap-group <ldap-object> contains auth'ed_user)
- # && ((ldap-attribute dept == "sales")
- # || (file-group contains auth'ed_user))))
- # then
- # auth_granted
- # else
- # auth_denied
- #
- <Directory /www/mydocs>
- - Authname ...
- AuthBasicProvider ...
- ...
- Require user John
- <SatisfyAll>
- - Require Group admins
- Require ldap-group cn=mygroup,o=foo
- <SatisfyOne>
- - Require ldap-attribute dept="sales"
- Require file-group
- - </SatisfyOne>
- - </SatisfyAll>
- - </Directory> - +Authorization Containers +Authentication, Authorization, + and Access Control + + + + +MatchAny +Enclose a group of authorization directives of which one +must succeed for the enclosing directive to succeed. +<MatchAny> +... </MatchAny> +directory.htaccess + +AuthConfig + + +

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

+ +

If one or more of the directives contained within the + MatchAny directive succeed, + then the MatchAny 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 + 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 + directive. +Authorization Containers Authentication, Authorization, and Access Control -SatisfyOne -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. -<SatisfyOne> -... </SatisfyOne> +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 -

SatisfyOne and - </SatisfyOne> are used to enclose a group of - authorization directives that must satisfy at least one in order to - grant access to a resource.

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.

+ -

See the - <SatisfyAll> directive for a usage example.

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

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

+ +

If one or more of the directives contained within the + MatchNotAny directive succeed, + then the MatchNotAny 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.

+ + Because negated authorization directives are unable to + return a successful result, they can not significantly influence + the result of a MatchNotAny + directive. Therefore negated authorization directives + are not permitted within a + MatchNotAny directive. +Authorization Containers Authentication, Authorization, and Access Control -AuthzMergeRules -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. -AuthzMergeRules on | off -AuthzMergeRules on +MergeAuthz +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 directory.htaccess AuthConfig -

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.

When authorization is enabled, it is normally inherited by each + 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.

+ +

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.

+ +

When a configuration section contains AuthzMerge MatchAll + or AuthzMerge MatchAny, + 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 + directive, respectively.

+ + The setting of AuthzMerge 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 + Directory + configuration section for /www/docs/ab/gamma, so + that section's authorization directives override those of the + preceding sections. Thus only users belong to the group + gamma may access /www/docs/ab/gamma. + + + <Directory /www/docs> + + AuthType Basic
+ AuthName Documents
+ AuthBasicProvider file
+ AuthUserFile /usr/local/apache/passwd/passwords
+ Match group alpha + + </Directory>
+
+ <Directory /www/docs/ab> + + AuthzMerge MatchAny
+ Match group beta + + </Directory>
+
+ <Directory /www/docs/ab/gamma> + + Match group gamma + + </Directory> + -RequireAlias +AuthzProviderAlias Enclose a group of directives that represent an extension of a base authorization provider and referenced by the specified alias -<RequireAlias baseProvider Alias Require-Parameters> -... </RequireAlias> +<AuthzProviderAlias baseProvider Alias Require-Parameters> +... </AuthzProviderAlias> server config -

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

AuthzProviderAlias and + </AuthzProviderAlias> are used to enclose a group of authorization directives that can be referenced by the alias name using the - directive Require.

+ directive Require.

Modified: httpd/httpd/trunk/docs/manual/mod/mod_authz_dbd.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_authz_dbd.xml?rev=709841&r1=709840&r2=709841&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_authz_dbd.xml (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_authz_dbd.xml Sat Nov 1 21:28:02 2008 @@ -47,9 +47,6 @@ Require - AuthzMergeRules - - AuthDBDUserPWQuery DBDriver @@ -106,7 +103,6 @@ "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 @@ "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 @@ <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" Modified: httpd/httpd/trunk/docs/manual/mod/mod_authz_host.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_authz_host.xml?rev=709841&r1=709840&r2=709841&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_authz_host.xml (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_authz_host.xml Sat Nov 1 21:28:02 2008 @@ -33,7 +33,7 @@

The authorization providers implemented by mod_authz_host are registered using the Require or - Reject directives. These + Match directives. These directives can be referenced within a Directory, Files, @@ -55,12 +55,12 @@ Authentication, Authorization, and Access Control Require -Reject +Match

The Require Directives

Apache's Require and - Reject directives are + Match 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 env, ip, Modified: httpd/httpd/trunk/docs/manual/new_features_2_4.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/new_features_2_4.xml?rev=709841&r1=709840&r2=709841&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/new_features_2_4.xml (original) +++ httpd/httpd/trunk/docs/manual/new_features_2_4.xml Sat Nov 1 21:28:02 2008 @@ -64,11 +64,22 @@ console. The user can thus be alerted to misconfiguration problems before the core open_logs hook function redirects console output to the error log. -

Expression Parser Added

We now have a general-purpose expression parser, whose API is - exposed in ap_expr.h. This is adapted from the - expression parser previously implemented in - mod_include.

+ +

Expression Parser Added

+ +

We now have a general-purpose expression parser, whose API is + exposed in ap_expr.h. This is adapted from the + expression parser previously implemented in + mod_include.

+ +

Authorization Logic Containers

+ +

Advanced authorization logic may now be specified using the + Match directive + and the related container directives, such as + MatchAll, all + provided by the mod_authz_core module.