Apache Module mod_authz_core

AuthMerging Directive

When authorization is enabled, it is normally inherited by each subsequent configuration section, unless a different set of authorization directives is 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.

<Directory "/www/docs">
    AuthType Basic
    AuthName Documents
    AuthBasicProvider file
    AuthUserFile "/usr/local/apache/passwd/passwords"
    Require group alpha
</Directory>

<Directory "/www/docs/ab">
    AuthMerging Or
    Require group beta
</Directory>

<Directory "/www/docs/ab/gamma">
    Require group gamma
</Directory>

<AuthzProviderAlias> Directive

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

If several parameters are needed in Require-Parameters, they must be enclosed in quotation marks. Otherwise, only the first one is taken into account.

# In this example, for both addresses to be taken into account, they MUST be enclosed
# between quotation marks
<AuthzProviderAlias ip reject-ips "XXX.XXX.XXX.XXX YYY.YYY.YYY.YYY">
</AuthzProviderAlias>

<Directory "/path/to/dir">
    <RequireAll>
        Require not reject-ips
        Require all granted
    </RequireAll>
</Directory>

AuthzSendForbiddenOnFailure Directive

If authentication succeeds but authorization fails, Apache HTTPD 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. AuthzSendForbiddenOnFailure allows to change the response code to '403 FORBIDDEN'.

Require Directive

This directive tests whether an authenticated user is authorized according to a particular authorization provider and the specified restrictions. mod_authz_core provides the following generic authorization providers:

Require all granted

Access is allowed unconditionally.

Require all denied

Access is denied unconditionally.

Require env env-var [env-var] ...

Access is allowed only if one of the given environment variables is set.

Require method http-method [http-method] ...

Access is allowed only for the given HTTP methods.

Require expr expression

Access is allowed if expression evaluates to true.

Some of the allowed syntaxes provided by mod_authz_user, mod_authz_host, and mod_authz_groupfile are:

Require user userid [userid] ...

Only the named users can access the resource.

Require group group-name [group-name] ...

Only users in the named groups can access the resource.

Require valid-user

All valid users can access the resource.

Require ip 10 172.20 192.168.2

Clients in the specified IP address ranges can access the resource.

Require forward-dns dynamic.example.org

A client the IP of which is resolved from the name dynamic.example.org will be granted access.

Other authorization modules that implement require options include mod_authnz_ldap, mod_authz_dbm, mod_authz_dbd, mod_authz_owner and mod_ssl.

In most cases, for a complete authentication and authorization configuration, Require must be accompanied by AuthName, AuthType and AuthBasicProvider or AuthDigestProvider directives, and directives such as AuthUserFile and AuthGroupFile (to define users and groups) in order to work correctly. Example:

AuthType Basic
AuthName "Restricted Resource"
AuthBasicProvider file
AuthUserFile "/web/users"
AuthGroupFile "/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 wish to apply access controls only to specific methods, while leaving other methods unprotected, then place the Require statement into a <Limit> section.

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 <RequireAny> directive. Thus the first one to authorize a user authorizes the entire request, and subsequent Require directives are ignored.

See also

• Access Control howto
• Authorization Containers
• mod_authn_core
• mod_authz_host

<RequireAll> Directive

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

See also

• Authorization Containers
• Authentication, Authorization, and Access Control

<RequireAny> Directive

<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 one or more of the directives contained within the <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.

See also

• Authorization Containers
• Authentication, Authorization, and Access Control

<RequireNone> Directive

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

See also

• Authorization Containers
• Authentication, Authorization, and Access Control