Apache Module mod_authz_core

Summary

This module provides core authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site.mod_authz_core provides the functionality to register various authorization providers. It is usually used in conjunction with an authentication provider module such asmod_authn_file and an authorization module such asmod_authz_user. It also allows for advanced logic to be applied to the authorization processing.

Topics

• Authorization Containers
• The Require Directives
• Creating Authorization Provider Aliases

Directives

• AuthMerging
• <AuthzProviderAlias>
• AuthzSendForbiddenOnFailure
• Require
• <RequireAll>
• <RequireAny>
• <RequireNone>

Bugfix checklist

• httpd changelog
• Known issues
• Report a bug

See also

• Comments

Authorization Containers

The authorization container directives<RequireAll>,<RequireAny> and<RequireNone> may be combined with each other and with theRequire 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 thesuperadmin user, or belong to both theadmins group and theAdministrators LDAP group and either belong to thesales group or have the LDAPdept attributesales. Furthermore, in order to access the resource, the user must not belong to either thetemps group or the LDAP groupTemporary Employees.

<Directory "/www/mydocs">    <RequireAll>        <RequireAny>            Require user superadmin            <RequireAll>                Require group admins                Require ldap-group "cn=Administrators,o=Airius"                <RequireAny>                    Require group sales                    Require ldap-attribute dept="sales"                </RequireAny>            </RequireAll>        </RequireAny>        <RequireNone>            Require group temps            Require ldap-group "cn=Temporary Employees,o=Airius"        </RequireNone>    </RequireAll></Directory>

The Require Directives

mod_authz_core provides some generic authorization providers which can be used with theRequire directive.

Require env

Theenv provider allows access to the server to be controlled based on the existence of anenvironment variable. WhenRequire envenv-variable is specified, then the request is allowed access if the environment variableenv-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 bymod_setenvif. Therefore, this directive can be used to allow access based on such factors as the clientsUser-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 withKnockKnock/2.0 will be allowed access, and all others will be denied.

When the server looks up a path via an internalsubrequest such as looking for aDirectoryIndex or generating a directory listing withmod_autoindex, per-request environment variables arenot inherited in the subrequest. Additionally,SetEnvIf directives are not separately evaluated in the subrequest due to the API phasesmod_setenvif takes action in.

Require all

Theall provider mimics the functionality that 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

Themethod provider allows using the HTTP method in authorization decisions. The GET and HEAD methods are treated as equivalent. The TRACE method is not available to this provider, useTraceEnable instead.

The following example will only allow GET, HEAD, POST, and OPTIONS requests:

Require method GET POST OPTIONS

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

Theexpr 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 { '/example.cgi', '/other.cgi' }"</RequireAll>

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

The syntax is described in theap_expr documentation. Before httpd 2.4.16, the surrounding double-quotes MUST be omitted.

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.

Creating Authorization Provider Aliases

Extended authorization providers can be created within the configuration file and assigned an alias name. The alias providers can then be referenced through theRequire 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 referenced by multiple locations.

Example

The example below creates two different ldap authorization provider aliases based on the ldap-group authorization provider. This example allows a single authorization location to check group membership within multiple ldap hosts:

<AuthzProviderAlias ldap-group ldap-group-alias1 "cn=my-group,o=ctx">    AuthLDAPBindDN "cn=youruser,o=ctx"    AuthLDAPBindPassword yourpassword    AuthLDAPUrl "ldap://ldap.host/o=ctx"</AuthzProviderAlias><AuthzProviderAlias ldap-group ldap-group-alias2 "cn=my-other-group,o=dev">    AuthLDAPBindDN "cn=yourotheruser,o=dev"    AuthLDAPBindPassword yourotherpassword    AuthLDAPUrl "ldap://other.ldap.host/o=dev?cn"</AuthzProviderAlias>Alias "/secure" "/webpages/secure"<Directory "/webpages/secure">    Require all granted    AuthBasicProvider file    AuthType Basic    AuthName LDAP_Protected_Place    #implied OR operation    Require ldap-group-alias1    Require ldap-group-alias2</Directory>

AuthMergingDirective

When authorization is enabled, it is normally inherited by each subsequentconfiguration section, unless a different set of authorization directives is specified. This is the default action, which corresponds to an explicit setting ofAuthMerging 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 andOr.

When a configuration section containsAuthMerging And orAuthMerging 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 directiveRequire.

If several parameters are needed inRequire-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>

AuthzSendForbiddenOnFailureDirective

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

RequireDirective

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 envenv-var [env-var] ...

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

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

Access is allowed only for the given HTTP methods.

Require exprexpression

Access is allowed ifexpression evaluates to true.

Some of the allowed syntaxes provided bymod_authz_user,mod_authz_host, andmod_authz_groupfile are:

Require useruserid [userid] ...

Only the named users can access the resource.

Require groupgroup-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 includemod_authnz_ldap,mod_authz_dbm,mod_authz_dbd,mod_authz_owner andmod_ssl.

In most cases, for a complete authentication and authorization configuration,Require must be accompanied byAuthName,AuthType andAuthBasicProvider orAuthDigestProvider directives, and directives such asAuthUserFile andAuthGroupFile (to define users and groups) in order to work correctly. Example:

AuthType BasicAuthName "Restricted Resource"AuthBasicProvider fileAuthUserFile "/web/users"AuthGroupFile "/web/groups"Require group admin

Access controls which are applied in this way are effective forall 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 theRequire statement into a<Limit> section.

The result of theRequire directive may be negated through the use of thenot option. As with the other negated authorization directive<RequireNone>, when theRequire 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 thealpha andbeta groups are authorized, except for those who are also in thereject group.

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

When multipleRequire directives are used in a singleconfiguration 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 subsequentRequire 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 directiveRequire 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