Module mod_authz_core

The AuthMerging directive controls the manner in which each configuration section's authorization logic is combined with that of preceding configuration sections.

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 AuthMerging Off.

However, there may be circumstances in which it is 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, And and Or.

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 <RequireAll> or <RequireAny> directive, respectively.

Users belonging to either groups alpha or beta may access /www/docs/ab. However, the default Off setting of AuthMerging 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.

Example:

<Directory /www/docs>
   AuthType Basic
   AuthName "Restricted Directory"
   PasswdFile web/users
   GroupFile /web/groups
   Require group alpha
</Directory>
<Directory /www/docs>
   AuthMerging Or
   Require group beta
</Directory>
<Directory /www/docs/ab/gamma>
   Require group gamma
</Directory>

The AuthzSendForbiddenOnFailure directive sends '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if authentication succeeds but authorization fails.

Parameter: on | off

• When set to off, if authentication succeeds but authorization fails, HTTP Server will respond with an HTTP response code of '401 UNAUTHORIZED' by default. This usually causes browsers to display the password dialogue to the user again, which is not wanted in all situations.
• When set to on, if authentication succeeds but authorization fails, HTTP Server will respond with an HTTP response code of '403 FORBIDDEN' instead of '401 UNAUTHORIZED'.

Require all granted
Require group  admin
Require user  bob  carol  don
Require valid-user

This directive selects which authenticated users can access a directory.

Parameter: [not] entity-name [entity-name] ...

• If Require user userid [userid] ..., then only the named users can access the resource.
• If Require group group-name [group-name] ...,, then only users in the named groups can access the resource.
• If require valid-user, then all valid users can access the resource.
• If Require ip 10 172.20 192.168.2 , then clients in the specified IP address ranges can access
• If Require all granted, then access is allowed unconditionally.
• If Require all denied, then access is denied unconditionally.
• If Require env env-var [env-var] ..., then access is allowed only if one of the given environment variables is set.
• If Require method http-method [http-method] ..., then access is allowed only for the given HTTP methods.
• If Require expr expression, then access is allowed if expression evaluates to true.

Require env

The env provider allows access to the server to be controlled based on the existence of an environment variable. When Require env env-variable is specified, then the request is allowed access if the environment variable env-variable exists. The server provides the ability to set environment variables in a flexible way based on characteristics of the client request using the directives provided by mod_setenvif. Therefore, this directive can be used to allow access based on such factors as the clients User-Agent (browser type), Referer, or other HTTP request header fields.

SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in

<Directory /docroot>
  Require env let_me_in
</Directory>

In this case, browsers with a user-agent string beginning with KnockKnock/2.0 will be allowed access, and all others will be denied.

When the server looks up a path via an internal subrequest such as looking for a DirectoryIndex or generating a directory listing with mod_autoindex, per-request environment variables are not inherited in the subrequest. Additionally, SetEnvIf directives are not separately evaluated in the subrequest due to the API phases mod_setenvif takes action in.

Require all

The all 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.

Require all granted
Require all denied

Require method

The method provider allows using the HTTP method in authorization decisions. The GET and HEAD methods are treated as equivalent.

The following example will allow GET, HEAD, POST, and OPTIONS requests without authentication, and require a valid user for all other methods:

<RequireAny>
     Require method GET POST OPTIONS
     Require valid-user
</RequireAny>

Require expr

The expr provider allows basing authorization decisions on arbitrary expressions.

Require expr %{TIME_HOUR} -ge 9 && %{TIME_HOUR} -le 17

<RequireAll>
    Require expr "!(%{QUERY_STRING} =~ /secret/)"
    Require expr "%{REQUEST_URI} in { '/cgi-bin/example.pgm', 'cgi-bin/other.pgm' }" 
</RequireAll>

Require expr "!(%{QUERY_STRING} =~ /secret/) && %{REQUEST_URI} in { '/cgi-bin/example.pgm', '/cgi-bin/other.pgm' }"

Normally, the expression is evaluated before authentication. However, if the expression returns false and references the variable %{REMOTE_USER}, authentication will be performed and the expression will be re-evaluated.

In most cases, for a complete authentication and authorization configuration, Require must be accompanied by AuthName and AuthType directives, and directives such as PasswdFile and GroupFile (to define users and groups) in order to work correctly. For example:

AuthType Basic
AuthName "Restricted Directory"
PasswdFile web/users
GroupFile /web/groups
Require group admin

Access controls which are applied in this way are effective for all methods. This is what is normally desired. If you want to apply access controls only to specific methods, while leaving other methods unprotected, then place the require statement into a <Limit> section.

Access controls can be used in a named protection setup. To implement a named protection setup, place all of the access control directives in a file. Use the Include directive to include the file in your <Directory>, <Files>, <Location> context. This allows users that want to use the same type of protection setup within multiple contexts to add an include statement inside of each context.

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 and beta groups are authorized, except for those who are also in the reject group.

<Directory /www/docs>
   <RequireAll>
        Require group alpha beta
        Require not group reject
   </RequireAll>
</Directory>

When multiple Require directives are used in a single configuration section and are not contained in another authorization directive like <RequireAll>, they are implicitly contained within a directive. Thus the first one to authorize a user authorizes the entire request, and subsequent Require directives are ignored.

The AuthMerging directive can be used to control how authorization configuration sections are merged.

<RequireAll>
    Require group sales
    Require ip 192.168 
</RequireAll>

<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 <RequireAll> directive to succeed.

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

The example below expresses the following authorization logic. In order to access the resource, the user must belong to group admins and group operators at the same time.

<Directory /www/mydocs>
  <RequireAll>
    Require group admins
    Require group operators 
  </RequireAll>
</Directory>

<RequireAny>
    Require group sales
    Require group managers 
</RequireAny>

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

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

<RequireNone>
    Require group sales
    Require group managers 
</RequireNone>

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

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