mod_authz_core.html.en revision bf7a66e941926dc62fd3e0a2b5ba3420ffdc2eb6
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>mod_authz_core - Apache HTTP Server</title>
<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<body>
<div id="page-header">
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
<p class="apache">Apache HTTP Server Version 2.3</p>
<div id="path">
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_authz_core</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="/en/mod/mod_authz_core.html" title="English"> en </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Core Authorization</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>authz_core_module</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTPD 2.3 and later</td></tr></table>
<h3>Summary</h3>
<p>This module provides core authorization capabilities so that
authenticated users can be allowed or denied access to portions
of the web site. <code class="module"><a href="/mod/mod_authz_core.html">mod_authz_core</a></code> provides the
functionality to register various authorization providers. It is
usually used in conjunction with an authentication
provider module such as <code class="module"><a href="/mod/mod_authn_file.html">mod_authn_file</a></code> and an
authorization module such as <code class="module"><a href="/mod/mod_authz_user.html">mod_authz_user</a></code>. It
also allows for advanced logic to be applied to the
authorization processing.</p>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="/images/down.gif" /> <a href="#authzprovideralias"><AuthzProviderAlias></a></li>
<li><img alt="" src="/images/down.gif" /> <a href="#authzsendforbiddenonfailure">AuthzSendForbiddenOnFailure</a></li>
</ul>
<h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="/images/down.gif" /> <a href="#authzalias">Creating Authorization Provider Aliases</a></li>
<li><img alt="" src="/images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
</ul></div>
<div class="section">
<h2><a name="authzalias" id="authzalias">Creating Authorization Provider Aliases</a></h2>
<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 <code class="directive"><a href="#require">Require</a></code> 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>
<h3><a name="example" id="example">Example</a></h3>
<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>
<div class="example"><h3>Example</h3><p><code>
<AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx><br />
<span class="indent">
AuthLDAPBindDN cn=youruser,o=ctx<br />
AuthLDAPBindPassword yourpassword<br />
AuthLDAPURL ldap://ldap.host/o=ctx<br />
</span>
</AuthzProviderAlias><br /><br />
<AuthzProviderAlias ldap-group ldap-group-alias2
cn=my-other-group,o=dev><br />
<span class="indent">
AuthLDAPBindDN cn=yourotheruser,o=dev<br />
AuthLDAPBindPassword yourotherpassword<br />
AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br />
</span>
</AuthzProviderAlias><br /><br />
<span class="indent">
Order deny,allow<br />
Allow from all<br /><br />
AuthBasicProvider file<br /><br />
AuthType Basic<br />
AuthName LDAP_Protected_Place<br /><br />
#implied OR operation<br />
Require ldap-group-alias1<br />
Require ldap-group-alias2<br />
</span> </Directory><br />
</code></p></div>
<div class="section">
<h2><a name="logic" id="logic">Authorization Containers</a></h2>
<p>The authorization container directives
<code class="directive"><a href="#requireall"><RequireAll></a></code>,
<code class="directive"><a href="#requireany"><RequireAny></a></code>
and
<code class="directive"><a href="#requirenone"><RequireNone></a></code>
may be combined with each other and with the
<code class="directive"><a href="#require">Require</a></code>
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>
<div class="example"><p><code>
<span class="indent">
<RequireAll>
<span class="indent">
<RequireAny>
<span class="indent">
Require user superadmin<br />
<RequireAll>
<span class="indent">
Require group admins<br />
Require ldap-group cn=Administrators,o=Airius<br />
<RequireAny>
<span class="indent">
Require group sales<br />
Require ldap-attribute dept="sales"
</span>
</RequireAny>
</span>
</RequireAll>
</span>
</RequireAny><br />
<RequireNone>
<span class="indent">
Require group temps<br />
Require ldap-group cn=Temporary Employees,o=Airius
</span>
</RequireNone>
</span>
</RequireAll>
</span>
</Directory>
</code></p></div>
<div class="section">
<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
<p><code class="module"><a href="/mod/mod_authz_core.html">mod_authz_core</a></code> provides some generic authorization
providers which can be used with the
<code class="directive"><a href="#require">Require</a></code> directive.</p>
<h3><a name="reqenv" id="reqenv">Require env</a></h3>
<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
<code class="module"><a href="/mod/mod_setenvif.html">mod_setenvif</a></code>. 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>
<div class="example"><h3>Example:</h3><p><code>
SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />
<Directory /docroot><br />
<span class="indent">
Require env let_me_in<br />
</span>
</Directory>
</code></p></div>
<p>In this case, browsers with a user-agent string beginning
others will be denied.</p>
<h3><a name="reqall" id="reqall">Require all</a></h3>
<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>
<div class="example"><p><code>
Require all granted<br />
</code></p></div>
<div class="example"><p><code>
Require all denied<br />
</code></p></div>
<h3><a name="reqmethod" id="reqmethod">Require method</a></h3>
<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 <code class="directive"><a href="/mod/core.html#traceenable">TraceEnable</a></code> instead.</p>
<p>The following example will only allow GET, HEAD, POST, and OPTIONS
requests:</p>
<div class="example"><p><code>
Require method GET POST OPTIONS<br />
</code></p></div>
<p>The following example will allow GET, HEAD, POST, and OPTIONS
requests without authentication, and require a valid user for all other
methods:</p>
<div class="example"><p><code>
<RequireAny><br />
Require method GET POST OPTIONS<br />
Require valid-user<br />
</RequireAny><br />
</code></p></div>
<h3><a name="reqexpr" id="reqexpr">Require expr</a></h3>
<p>The <code>expr</code> provider allows to base authorization
decisions on arbitrary expressions.</p>
<div class="example"><p><code>
Require expr %{TIME_HOUR} >= 9 & %{TIME_HOUR} <= 17 <br />
</code></p></div>
<p>TODO: Include a link to a description of the ap_expr syntax, once we have
such a description.</p>
</div>
<div class="directive-section"><h2><a name="AuthMerging" id="AuthMerging">AuthMerging</a> <a name="authmerging" id="authmerging">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls the manner in which each configuration section's
authorization logic is combined with that of preceding configuration
sections.</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthMerging Off | And | Or</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthMerging Off</code></td></tr>
</table>
<p>When authorization is enabled, it is normally inherited by each
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
<code class="directive"><a href="#requireall"><RequireAll></a></code> or
<code class="directive"><a href="#requireany"><RequireAny></a></code>
directive, respectively.</p>
<div class="note">The setting of <code class="directive">AuthMerging</code> is not
inherited outside of the configuration section in which it appears.
In the following example, only users belonging to group <code>alpha</code>
groups <code>alpha</code> or <code>beta</code> may access
setting of <code class="directive">AuthMerging</code> applies to the
that section's authorization directives override those of the
preceding sections. Thus only users belong to the group
<div class="example"><p><code>
<span class="indent">
AuthType Basic<br />
AuthName Documents<br />
AuthBasicProvider file<br />
Require group alpha
</span>
</Directory><br />
<br />
<span class="indent">
AuthMerging Or<br />
Require group beta
</span>
</Directory><br />
<br />
<span class="indent">
Require group gamma
</span>
</Directory>
</code></p></div>
</div>
<div class="directive-section"><h2><a name="AuthzProviderAlias" id="AuthzProviderAlias"><AuthzProviderAlias></a> <a name="authzprovideralias" id="authzprovideralias">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose a group of directives that represent an
extension of a base authorization provider and referenced by the specified
alias</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>>
... </AuthzProviderAlias>
</code></td></tr>
</table>
<p><code class="directive"><AuthzProviderAlias></code> and
<code></AuthzProviderAlias></code> are used to enclose a group of
authorization directives that can be referenced by the alias name using the
directive <code class="directive"><a href="#require">Require</a></code>.</p>
</div>
<div class="directive-section"><h2><a name="AuthzSendForbiddenOnFailure" id="AuthzSendForbiddenOnFailure">AuthzSendForbiddenOnFailure</a> <a name="authzsendforbiddenonfailure" id="authzsendforbiddenonfailure">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if
authentication succeeds but authorization fails
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzSendForbiddenOnFailure On|Off</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthzSendForbiddenOnFailure Off</code></td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTPD 2.3.11 and later</td></tr>
</table>
<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.
<code class="directive">AuthzSendForbiddenOnFailure</code> allows to change the
response code to '403 FORBIDDEN'.</p>
</div>
<div class="directive-section"><h2><a name="Require" id="Require">Require</a> <a name="require" id="require">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Tests whether an authenticated user is authorized by
an authorization provider.</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Require [not] <var>entity-name</var>
[<var>entity-name</var>] ...</code></td></tr>
</table>
<p>This directive tests whether an authenticated user is authorized
according to a particular authorization provider and the specified
restrictions. <code class="module"><a href="/mod/mod_authz_core.html">mod_authz_core</a></code> 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 <code class="module"><a href="/mod/mod_authz_user.html">mod_authz_user</a></code>
and <code class="module"><a href="/mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> 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>
</dl>
<p>Other authorization modules that implement require options
<code class="module"><a href="/mod/mod_authz_dbm.html">mod_authz_dbm</a></code>, <code class="module"><a href="/mod/mod_authz_dbd.html">mod_authz_dbd</a></code>,
<code class="module"><a href="/mod/mod_authz_owner.html">mod_authz_owner</a></code> and <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>.</p>
<p>In most cases, for a complete authentication and authorization
configuration, <code class="directive">Require</code> must be accompanied by
<code class="directive"><a href="/mod/mod_authn_core.html#authname">AuthName</a></code>, <code class="directive"><a href="/mod/mod_authn_core.html#authtype">AuthType</a></code> and
<code class="directive"><a href="/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or
<code class="directive"><a href="/mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code>
directives, and directives such as
and <code class="directive"><a href="/mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code> (to
define users and groups) in order to work correctly. Example:</p>
<div class="example"><p><code>
AuthType Basic<br />
AuthName "Restricted Resource"<br />
AuthBasicProvider file<br />
Require group admin
</code></p></div>
<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 <code class="directive">Require</code> statement into a
section.</p>
<p>The result of the <code class="directive">Require</code> directive
may be negated through the use of the
<code>not</code> option. As with the other negated authorization
directive <code class="directive"><RequireNone></code>,
when the <code class="directive">Require</code> 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>
<div class="example"><p><code>
<span class="indent">
<RequireAll>
<span class="indent">
Require group alpha beta<br />
Require not group reject
</span>
</RequireAll>
</span>
</Directory>
</code></p></div>
<p>When multiple <code class="directive">Require</code> directives are
used in a single
and are not contained in another authorization directive like
<code class="directive"><a href="#requireall"><RequireAll></a></code>,
they are implicitly contained within a
<code class="directive"><a href="#requireany"><RequireAny></a></code>
directive. Thus the first one to authorize a user authorizes the
entire request, and subsequent <code class="directive">Require</code> directives
are ignored.</p>
<h3>See also</h3>
<ul>
and Access Control</a></li>
<li><a href="#logic">Authorization Containers</a></li>
</ul>
</div>
<div class="directive-section"><h2><a name="RequireAll" id="RequireAll"><RequireAll></a> <a name="requireall" id="requireall">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose a group of authorization directives of which none
must fail and at least one must succeed for the enclosing directive to
succeed.</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><RequireAll> ... </RequireAll></code></td></tr>
</table>
<p><code class="directive"><RequireAll></code> and
<code></RequireAll></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 <code class="directive"><RequireAll></code> directive to
succeed.</p>
<p>If none of the directives contained within the
<code class="directive"><RequireAll></code> directive fails,
and at least one succeeds, then the
<code class="directive"><RequireAll></code> directive
succeeds. If none succeed and none fail, then it returns a
neutral result. In all other cases, it fails.</p>
<h3>See also</h3>
<ul>
<li><a href="#logic">Authorization Containers</a></li>
and Access Control</a></li>
</ul>
</div>
<div class="directive-section"><h2><a name="RequireAny" id="RequireAny"><RequireAny></a> <a name="requireany" id="requireany">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose a group of authorization directives of which one
must succeed for the enclosing directive to succeed.</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><RequireAny> ... </RequireAny></code></td></tr>
</table>
<p><code class="directive"><RequireAny></code> and
<code></RequireAny></code> are used to enclose a group of
authorization directives of which one must succeed in order for
the <code class="directive"><RequireAny></code> directive to
succeed.</p>
<p>If one or more of the directives contained within the
<code class="directive"><RequireAny></code> directive succeed,
then the <code class="directive"><RequireAny></code> directive
succeeds. If none succeed and none fail, then it returns a
neutral result. In all other cases, it fails.</p>
<div class="note">Because negated authorization directives are unable to
return a successful result, they can not significantly influence
the result of a <code class="directive"><RequireAny></code>
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 <code class="directive"><RequireAny></code>
directive.</div>
<h3>See also</h3>
<ul>
<li><a href="#logic">Authorization Containers</a></li>
and Access Control</a></li>
</ul>
</div>
<div class="directive-section"><h2><a name="RequireNone" id="RequireNone"><RequireNone></a> <a name="requirenone" id="requirenone">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enclose a group of authorization directives of which none
must succeed for the enclosing directive to not fail.</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code><RequireNone> ... </RequireNone></code></td></tr>
</table>
<p><code class="directive"><RequireNone></code> and
<code></RequireNone></code> are used to enclose a group of
authorization directives of which none must succeed
in order for the
<code class="directive"><RequireNone></code> directive to
not fail.</p>
<p>If one or more of the directives contained within the
<code class="directive"><RequireNone></code> directive succeed,
then the <code class="directive"><RequireNone></code> 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>
<div class="note">Because negated authorization directives are unable to
return a successful result, they can not significantly influence
the result of a <code class="directive"><RequireNone></code>
directive. Therefore negated authorization directives
are not permitted within a
<code class="directive"><RequireNone></code> directive.</div>
<h3>See also</h3>
<ul>
<li><a href="#logic">Authorization Containers</a></li>
and Access Control</a></li>
</ul>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/mod/mod_authz_core.html" title="English"> en </a></p>
</div><div id="footer">
<p class="apache">Copyright 2010 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>
</body></html>