apache/docs/manual/mod/mod_authz_core.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<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 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="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>
    
        <example><title>Example</title>
          &lt;AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx&gt;<br />
          <indent>
             AuthLDAPBindDN cn=youruser,o=ctx<br />
             AuthLDAPBindPassword yourpassword<br />
             AuthLDAPURL ldap://ldap.host/o=ctx<br />
          </indent> 
          &lt;/AuthzProviderAlias&gt;<br /><br /> 
          &lt;AuthzProviderAlias ldap-group ldap-group-alias2
           cn=my-other-group,o=dev&gt;<br />
          <indent>
             AuthLDAPBindDN cn=yourotheruser,o=dev<br />
             AuthLDAPBindPassword yourotherpassword<br />
             AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br />
          </indent> 
          &lt;/AuthzProviderAlias&gt;<br /><br />
    
          Alias /secure /webpages/secure<br />
          &lt;Directory /webpages/secure&gt;<br />
          <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 />
          </indent> &lt;/Directory&gt;<br />
        </example>
    </section>

</section>

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

    <example>
        &lt;Directory /www/mydocs&gt;
        <indent>
            &lt;RequireAll&gt;
            <indent>
                &lt;RequireAny&gt;
                <indent>
                    Require user superadmin<br />
                    &lt;RequireAll&gt;
                    <indent>
                        Require group admins<br />
                        Require ldap-group cn=Administrators,o=Airius<br />
                        &lt;RequireAny&gt;
                        <indent>
                            Require group sales<br />
                            Require ldap-attribute dept="sales"
                        </indent>
                        &lt;/RequireAny&gt;
                    </indent>
                    &lt;/RequireAll&gt;
                </indent>
                &lt;/RequireAny&gt;<br />
                &lt;RequireNone&gt;
                <indent>
                    Require group temps<br />
                    Require ldap-group cn=Temporary Employees,o=Airius
                </indent>
                &lt;/RequireNone&gt;
            </indent>
            &lt;/RequireAll&gt;
        </indent>      
        &lt;/Directory&gt;
    </example>
</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.  Some of the allowed syntaxes provided by
    <module>mod_authz_user</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>
    </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_host</module>, and
    <module>mod_authz_owner</module>.</p>

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

    <example>
       AuthType Basic<br />
       AuthName "Restricted Resource"<br />
       AuthBasicProvider file<br />
       AuthUserFile /web/users<br />
       AuthGroupFile /web/groups<br />
       Require group admin
    </example>

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

    <example>
        &lt;Directory /www/docs&gt;
        <indent>
            &lt;RequireAll&gt;
            <indent>
                Require group alpha beta<br />
                Require not group reject
            </indent>
            &lt;/RequireAll&gt;
        </indent>
        &lt;/Directory&gt;
    </example>

    <p>When multiple <directive>Require</directive> directives are
    used in a single
    <a href="../sections.html#mergin">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>
</usage>

<seealso><a href="../howto/auth.html">Authentication, Authorization,
    and Access Control</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#mergin">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>

    <example>
        &lt;Directory /www/docs&gt;
        <indent>
            AuthType Basic<br />
            AuthName Documents<br />
            AuthBasicProvider file<br />
            AuthUserFile /usr/local/apache/passwd/passwords<br />
            Require group alpha
        </indent>
        &lt;/Directory&gt;<br />
        <br />
        &lt;Directory /www/docs/ab&gt;
        <indent>
            AuthMerging Or<br />
            Require group beta
        </indent>
        &lt;/Directory&gt;<br />
        <br />
        &lt;Directory /www/docs/ab/gamma&gt;
        <indent>
            Require group gamma
        </indent>
        &lt;/Directory&gt;
    </example>
</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>

</modulesynopsis>