<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_authz_core.xml.meta">

<name>mod_authz_core</name>

<description>Core Authorization</description>

<status>Base</status>

<sourcefile>mod_authz_core.c</sourcefile>

<identifier>authz_core_module</identifier>

<compatibility>Available in Apache HTTPD 2.3 and later</compatibility>

<summary>

<p>This module provides core authorization capabilities so that

authenticated users can be allowed or denied access to portions

of the web site. <module>mod_authz_core</module> provides the

functionality to register various authorization providers. It is

usually used in conjunction with an authentication

provider module such as <module>mod_authn_file</module> and an

authorization module such as <module>mod_authz_user</module>. It

also allows for advanced logic to be applied to the

authorization processing.</p>

</summary>

<section id="logic"><title>Authorization Containers</title>

<p>The authorization container directives

<directive module="mod_authz_core" type="section">RequireAll</directive>,

<directive module="mod_authz_core" type="section">RequireAny</directive>

and

<directive module="mod_authz_core" type="section">RequireNone</directive>

may be combined with each other and with the

<directive module="mod_authz_core">Require</directive>

directive to express complex authorization logic.</p>

<p>The example below expresses the following authorization logic.

In order to access the resource, the user must either be the

<code>superadmin</code> user, or belong to both the

<code>admins</code> group and the <code>Administrators</code> LDAP

group and either belong to the <code>sales</code> group or

have the LDAP <code>dept</code> attribute <code>sales</code>.

Furthermore, in order to access the resource, the user must

not belong to either the <code>temps</code> group or the

LDAP group <code>Temporary Employees</code>.</p>

<highlight language="config">

&lt;Directory /www/mydocs&gt;

&lt;RequireAll&gt;

&lt;RequireAny&gt;

Require user superadmin

&lt;RequireAll&gt;

Require group admins

Require ldap-group cn=Administrators,o=Airius

&lt;RequireAny&gt;

Require group sales

Require ldap-attribute dept="sales"

&lt;/RequireAny&gt;

&lt;/RequireAll&gt;

&lt;/RequireAny&gt;

&lt;RequireNone&gt;

Require group temps

Require ldap-group cn=Temporary Employees,o=Airius

&lt;/RequireNone&gt;

&lt;/RequireAll&gt;

&lt;/Directory&gt;

</highlight>

</section>

<section id="requiredirectives"><title>The Require Directives</title>

<p><module>mod_authz_core</module> provides some generic authorization

providers which can be used with the

<directive module="mod_authz_core">Require</directive> directive.</p>

<section id="reqenv"><title>Require env</title>

<p>The <code>env</code> provider allows access to the server

to be controlled based on the existence of an <a

href="/env.html">environment variable</a>. When <code>Require

env <var>env-variable</var></code> is specified, then the request is

allowed access if the environment variable <var>env-variable</var>

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

<module>mod_setenvif</module>. Therefore, this directive can be

used to allow access based on such factors as the clients

<code>User-Agent</code> (browser type), <code>Referer</code>, or

other HTTP request header fields.</p>

<highlight language="config">

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

&lt;Directory /docroot&gt;

Require env let_me_in

&lt;/Directory&gt;

</highlight>

<p>In this case, browsers with a user-agent string beginning

with <code>KnockKnock/2.0</code> will be allowed access, and all

others will be denied.</p>

<p>When the server looks up a path via an internal

<glossary ref="subrequest">subrequest</glossary> such as looking

for a <directive module="mod_dir" >DirectoryIndex</directive>

or generating a directory listing with <module>mod_autoindex</module>,

per-request environment variables are <em>not</em> inherited in the

subrequest. Additionally,

<directive module="mod_setenvif">SetEnvIf</directive> directives

are not separately evaluated in the subrequest due to the API phases

<module>mod_setenvif</module>.</p>

<p>When the server looks up a path via an internal subrequest,

such as looking for a <directive module="mod_dir"

>DirectoryIndex</directive> or generating a directory listing with

<module>mod_autoindex</module>, per-request environment variables are

<em>not</em> inherited in the subrequest. Additionally, environment

<directive module="mod_setenvif">SetEnvIf</directive> directives

are not separately evaluated in the subrequest due to the API phases

<module>mod_setenvif</module> takes action in.</p>

</section>

<section id="reqall"><title>Require all</title>

<p>The <code>all</code> 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.</p>

<highlight language="config">

Require all granted

</highlight>

<highlight language="config">

Require all denied

</highlight>

</section>

<section id="reqmethod"><title>Require method</title>

<p>The <code>method</code> provider allows to use the HTTP method in

authorization decisions. The GET and HEAD methods are treated as

equivalent. The TRACE method is not available to this provider,

use <directive module="core">TraceEnable</directive> instead.</p>

<p>The following example will only allow GET, HEAD, POST, and OPTIONS

requests:</p>

<highlight language="config">

Require method GET POST OPTIONS

</highlight>

<p>The following example will allow GET, HEAD, POST, and OPTIONS

requests without authentication, and require a valid user for all other

methods:</p>

<highlight language="config">

&lt;RequireAny&gt;

&nbsp;Require method GET POST OPTIONS

&nbsp;Require valid-user

&lt;/RequireAny&gt;

</highlight>

</section>

<section id="reqexpr"><title>Require expr</title>

<p>The <code>expr</code> provider allows to base authorization

decisions on arbitrary expressions.</p>

<highlight language="config">

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

</highlight>

<p>The syntax is described in the <a href="/expr.html">ap_expr</a>

documentation.</p>

<p>Normally, the expression is evaluated before authentication. However, if

the expression returns false and references the variable

<code>%{REMOTE_USER}</code>, authentication will be performed and

the expression will be re-evaluated.</p>

</section>

</section>

<section id="authzalias"><title>Creating Authorization Provider Aliases</title>

<p>Extended authorization providers can be created within the configuration

file and assigned an alias name. The alias providers can then be referenced

through the <directive module="mod_authz_core">Require</directive> 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.

</p>

<section id="example"><title>Example</title>

<p>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:

</p>

<highlight language="config">

&lt;AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx&gt;

AuthLDAPBindDN cn=youruser,o=ctx

AuthLDAPBindPassword yourpassword

AuthLDAPURL ldap://ldap.host/o=ctx

&lt;/AuthzProviderAlias&gt;

&lt;AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev&gt;

AuthLDAPBindDN cn=yourotheruser,o=dev

AuthLDAPBindPassword yourotherpassword

AuthLDAPURL ldap://other.ldap.host/o=dev?cn

&lt;/AuthzProviderAlias&gt;

Alias /secure /webpages/secure

&lt;Directory /webpages/secure&gt;

Require all granted

AuthBasicProvider file

AuthType Basic

AuthName LDAP_Protected_Place

#implied OR operation

Require ldap-group-alias1

Require ldap-group-alias2

&lt;/Directory&gt;

</highlight>

</section>

</section>

<directivesynopsis>

<name>Require</name>

<description>Tests whether an authenticated user is authorized by

an authorization provider.</description>

<syntax>Require [not] <var>entity-name</var>

[<var>entity-name</var>] ...</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>This directive tests whether an authenticated user is authorized

according to a particular authorization provider and the specified

restrictions. <module>mod_authz_core</module> provides the following

generic authorization providers:</p>

<dl>

<dt><code>Require all granted</code></dt>

<dd>Access is allowed unconditionally.</dd>

<dt><code>Require all denied</code></dt>

<dd>Access is denied unconditionally.</dd>

<dt><code>Require env <var>env-var</var> [<var>env-var</var>]

...</code></dt>

<dd>Access is allowed only if one of the given environment variables is

set.</dd>

<dt><code>Require method <var>http-method</var> [<var>http-method</var>]

...</code></dt>

<dd>Access is allowed only for the given HTTP methods.</dd>

<dt><code>Require expr <var>expression</var> </code></dt>

<dd>Access is allowed if <var>expression</var> evaluates to true.</dd>

</dl>

<p>Some of the allowed syntaxes provided by <module>mod_authz_user</module>,

<module>mod_authz_host</module>,

and <module>mod_authz_groupfile</module> are:</p>

<dl>

<dt><code>Require user <var>userid</var> [<var>userid</var>]

...</code></dt>

<dd>Only the named users can access the resource.</dd>

<dt><code>Require group <var>group-name</var> [<var>group-name</var>]

...</code></dt>

<dd>Only users in the named groups can access the resource.</dd>

<dt><code>Require valid-user</code></dt>

<dd>All valid users can access the resource.</dd>

<dt><code>Require ip 10 172.20 192.168.2</code></dt>

<dd>Clients in the specified IP address ranges can access the

resource.</dd>

</dl>

<p>Other authorization modules that implement require options

include <module>mod_authnz_ldap</module>,

<module>mod_authz_dbm</module>, <module>mod_authz_dbd</module>,

<module>mod_authz_owner</module> and <module>mod_ssl</module>.</p>

<p>In most cases, for a complete authentication and authorization

configuration, <directive>Require</directive> must be accompanied by

<directive module="mod_authn_core">AuthName</directive>, <directive

module="mod_authn_core">AuthType</directive> and

<directive module="mod_auth_basic">AuthBasicProvider</directive> or

<directive module="mod_auth_digest">AuthDigestProvider</directive>

directives, and directives such as

<directive module="mod_authn_file">AuthUserFile</directive>

and <directive module="mod_authz_groupfile">AuthGroupFile</directive> (to

define users and groups) in order to work correctly. Example:</p>

<highlight language="config">

AuthType Basic

AuthName "Restricted Resource"

AuthBasicProvider file

AuthUserFile /web/users

AuthGroupFile /web/groups

Require group admin

</highlight>

<p>Access controls which are applied in this way are effective for

<strong>all</strong> methods. <strong>This is what is normally

desired.</strong> If you wish to apply access controls only to

specific methods, while leaving other methods unprotected, then

place the <directive>Require</directive> statement into a

<directive module="core" type="section">Limit</directive>

section.</p>

<p>The result of the <directive>Require</directive> directive

may be negated through the use of the

<code>not</code> option. As with the other negated authorization

directive <directive type="section">RequireNone</directive>,

when the <directive>Require</directive> directive is negated it can

only fail or return a neutral result, and therefore may never

independently authorize a request.</p>

<p>In the following example, all users in the <code>alpha</code>

and <code>beta</code> groups are authorized, except for those who

are also in the <code>reject</code> group.</p>

<highlight language="config">

&lt;Directory /www/docs&gt;

&lt;RequireAll&gt;

Require group alpha beta

Require not group reject

&lt;/RequireAll&gt;

&lt;/Directory&gt;

</highlight>

<p>When multiple <directive>Require</directive> directives are

used in a single

<a href="/sections.html#merging">configuration section</a>

and are not contained in another authorization directive like

<directive module="mod_authz_core" type="section">RequireAll</directive>,

they are implicitly contained within a

<directive module="mod_authz_core" type="section">RequireAny</directive>

directive. Thus the first one to authorize a user authorizes the

entire request, and subsequent <directive>Require</directive> directives

are ignored.</p>

<note type="warning"><title>Security Warning</title>

<p>Exercise caution when setting authorization directives in

<directive module="core">Location</directive> sections

that overlap with content served out of the filesystem.

By default, these <a href="/sections.html#merging"

>configuration sections</a> overwrite authorization configuration

in <directive module="core">Directory</directive>,

and <directive module="core">Files</directive> sections.</p>

<p>The <directive module="mod_authz_core">AuthMerging</directive> directive

can be used to control how authorization configuration sections are

merged.</p>

</note>

</usage>

<seealso><a href="/howto/access.html">Access Control howto</a></seealso>

<seealso><a href="#logic">Authorization Containers</a></seealso>

<seealso><module>mod_authn_core</module></seealso>

<seealso><module>mod_authz_host</module></seealso>

</directivesynopsis>

<directivesynopsis type="section">

<name>RequireAll</name>

<description>Enclose a group of authorization directives of which none

must fail and at least one must succeed for the enclosing directive to

succeed.</description>

<syntax>&lt;RequireAll&gt; ... &lt;/RequireAll&gt;</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p><directive type="section">RequireAll</directive> and

<code>&lt;/RequireAll&gt;</code> are used to enclose a group of

authorization directives of which none must fail and at least one

must succeed in order for

the <directive type="section">RequireAll</directive> directive to

succeed.</p>

<p>If none of the directives contained within the

<directive type="section">RequireAll</directive> directive fails,

and at least one succeeds, then the

<directive type="section">RequireAll</directive> directive

succeeds. If none succeed and none fail, then it returns a

neutral result. In all other cases, it fails.</p>

</usage>

<seealso><a href="#logic">Authorization Containers</a></seealso>

<seealso><a href="/howto/auth.html">Authentication, Authorization,

and Access Control</a></seealso>

</directivesynopsis>

<directivesynopsis type="section">

<name>RequireAny</name>

<description>Enclose a group of authorization directives of which one

must succeed for the enclosing directive to succeed.</description>

<syntax>&lt;RequireAny&gt; ... &lt;/RequireAny&gt;</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p><directive type="section">RequireAny</directive> and

<code>&lt;/RequireAny&gt;</code> are used to enclose a group of

authorization directives of which one must succeed in order for

the <directive type="section">RequireAny</directive> directive to

succeed.</p>

<p>If one or more of the directives contained within the

<directive type="section">RequireAny</directive> directive succeed,

then the <directive type="section">RequireAny</directive> directive

succeeds. If none succeed and none fail, then it returns a

neutral result. In all other cases, it fails.</p>

<note>Because negated authorization directives are unable to

return a successful result, they can not significantly influence

the result of a <directive type="section">RequireAny</directive>

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 <directive type="section">RequireAny</directive>

directive.</note>

</usage>

<seealso><a href="#logic">Authorization Containers</a></seealso>

<seealso><a href="/howto/auth.html">Authentication, Authorization,

and Access Control</a></seealso>

</directivesynopsis>

<directivesynopsis type="section">

<name>RequireNone</name>

<description>Enclose a group of authorization directives of which none

must succeed for the enclosing directive to not fail.</description>

<syntax>&lt;RequireNone&gt; ... &lt;/RequireNone&gt;</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p><directive type="section">RequireNone</directive> and

<code>&lt;/RequireNone&gt;</code> are used to enclose a group of

authorization directives of which none must succeed

in order for the

<directive type="section">RequireNone</directive> directive to

not fail.</p>

<p>If one or more of the directives contained within the

<directive type="section">RequireNone</directive> directive succeed,

then the <directive type="section">RequireNone</directive> directive

fails. In all other cases, it returns a neutral result. Thus as with

the other negated authorization directive <code>Require not</code>,

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

<note>Because negated authorization directives are unable to

return a successful result, they can not significantly influence

the result of a <directive type="section">RequireNone</directive>

directive. Therefore negated authorization directives

are not permitted within a

<directive type="section">RequireNone</directive> directive.</note>

</usage>

<seealso><a href="#logic">Authorization Containers</a></seealso>

<seealso><a href="/howto/auth.html">Authentication, Authorization,

and Access Control</a></seealso>

</directivesynopsis>

<directivesynopsis>

<name>AuthMerging</name>

<description>Controls the manner in which each configuration section's

authorization logic is combined with that of preceding configuration

sections.</description>

<syntax>AuthMerging Off | And | Or</syntax>

<default>AuthMerging Off</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>When authorization is enabled, it is normally inherited by each

subsequent <a href="/sections.html#merging">configuration section</a>,

unless a different set of authorization directives are specified.

This is the default action, which corresponds to an explicit setting

of <code>AuthMerging Off</code>.</p>

<p>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, <code>And</code>

and <code>Or</code>.</p>

<p>When a configuration section contains <code>AuthMerging And</code>

or <code>AuthMerging Or</code>,

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

<directive module="mod_authz_core" type="section">RequireAll</directive> or

<directive module="mod_authz_core" type="section">RequireAny</directive>

directive, respectively.</p>

<note>The setting of <directive>AuthMerging</directive> is not

inherited outside of the configuration section in which it appears.

In the following example, only users belonging to group <code>alpha</code>

may access <code>/www/docs</code>. Users belonging to either

groups <code>alpha</code> or <code>beta</code> may access

<code>/www/docs/ab</code>. However, the default <code>Off</code>

setting of <directive>AuthMerging</directive> applies to the

<directive type="section" module="core">Directory</directive>

configuration section for <code>/www/docs/ab/gamma</code>, so

that section's authorization directives override those of the

preceding sections. Thus only users belong to the group

<code>gamma</code> may access <code>/www/docs/ab/gamma</code>.</note>

<highlight language="config">

&lt;Directory /www/docs&gt;

AuthType Basic

AuthName Documents

AuthBasicProvider file

AuthUserFile /usr/local/apache/passwd/passwords

Require group alpha

&lt;/Directory&gt;

&lt;Directory /www/docs/ab&gt;

AuthMerging Or

Require group beta

&lt;/Directory&gt;

&lt;Directory /www/docs/ab/gamma&gt;

Require group gamma

&lt;/Directory&gt;

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis type="section">

<name>AuthzProviderAlias</name>

<description>Enclose a group of directives that represent an

extension of a base authorization provider and referenced by the specified

alias</description>

<syntax>&lt;AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>&gt;

... &lt;/AuthzProviderAlias&gt;

</syntax>

<contextlist><context>server config</context>

</contextlist>

<usage>

<p><directive type="section">AuthzProviderAlias</directive> and

<code>&lt;/AuthzProviderAlias&gt;</code> are used to enclose a group of

authorization directives that can be referenced by the alias name using the

directive <directive module="mod_authz_core">Require</directive>.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthzSendForbiddenOnFailure</name>

<description>Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if

authentication succeeds but authorization fails

</description>

<syntax>AuthzSendForbiddenOnFailure On|Off</syntax>

<default>AuthzSendForbiddenOnFailure Off</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<compatibility>Available in Apache HTTPD 2.3.11 and later</compatibility>

<usage>

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

<directive>AuthzSendForbiddenOnFailure</directive> allows to change the

response code to '403 FORBIDDEN'.</p>

<note type="warning"><title>Security Warning</title>

<p>Modifying the response in case of missing authorization weakens the

security of the password, because it reveals to a possible attacker, that

his guessed password was right.</p>

</note>

</usage>

</directivesynopsis>

</modulesynopsis>