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 "AND" and "OR" logic to be applied to the 
    authorization processing.</p>
</summary>

<directivesynopsis>
<name>Require</name>
<description>Selects which authenticated users can access
a resource</description>
<syntax>Require <var>entity-name</var> [<var>entity-name</var>] ...</syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>This directive selects which authenticated users can access a
    resource.  The restrictions are processed by authorization
    modules.  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> 
    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>
 
</usage>

<seealso><a href="../howto/auth.html">Authentication, Authorization,
    and Access Control</a></seealso> 
<seealso><module>mod_authz_host</module></seealso>
</directivesynopsis>

<directivesynopsis>
<name>Reject</name>
<description>Rejects authenticated users or host based 
requests from accessing a resource</description>
<syntax>Reject <var>entity-name</var> [<var>entity-name</var>] ...</syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>This directive is similar to the 
    <directive module="mod_authz_core">Require</directive> directive however
    it rejects which authenticated users or host based requests from accessing a resource.  The 
    restrictions are processed by authorization modules.  See the 
    <directive module="mod_authz_core">Require</directive> directive for details 
    about usage.</p>
</usage>

<seealso><a href="../howto/auth.html">Authentication, Authorization,
    and Access Control</a></seealso> 
<seealso><module>mod_authz_host</module></seealso>
</directivesynopsis>

<directivesynopsis type="section">
<name>SatisfyAll</name>
<description>Enclose a group of authorization directives that must all
be satisfied in order to grant access to a resource.  This block allows
for 'AND' logic to be applied to various authorization providers.</description>
<syntax>&lt;SatisfyAll&gt;
... &lt;/SatisfyAll&gt;</syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p><directive type="section">SatisfyAll</directive> and
    <code>&lt;/SatisfyAll&gt;</code> are used to enclose a group of
    authorization directives that must all be satisfied in order to 
    grant access to a resource.</p>

    <p>The <directive module="mod_authz_core">
    &lt;SatisfyAll&gt;</directive> block as well as the 
    <directive module="mod_authz_core">&lt;SatisfyOne&gt;</directive> block 
    allow you to apply "AND" and "OR" logic to the authorization processing. 
    For example the following authorization block would apply the logic:</p>

    <example>
      # if ((user == "John") ||<br />
      # &nbsp;&nbsp; ((Group == "admin")<br />
      # &nbsp; &nbsp; &amp;&amp; (ldap-group &lt;ldap-object&gt; contains auth'ed_user)<br />
      # &nbsp; &nbsp; &amp;&amp; ((ldap-attribute dept == "sales")<br />
      # &nbsp; &nbsp; &nbsp; &nbsp; || (file-group contains auth'ed_user))))<br />
      # then<br />
      # &nbsp; auth_granted<br />
      # else<br />
      # &nbsp; auth_denied<br />
      #<br />
      &lt;Directory /www/mydocs&gt;<br />
      <indent>
        Authname ...<br />
        AuthBasicProvider ...<br />
        ...<br />
        Require user John<br />
        &lt;SatisfyAll&gt;<br />
        <indent>
          Require Group admins<br />
          Require ldap-group cn=mygroup,o=foo<br />
          &lt;SatisfyOne&gt;<br />
          <indent>
            Require ldap-attribute dept="sales"<br />
            Require file-group<br />
          </indent>
          &lt;/SatisfyOne&gt;<br />
        </indent>
        &lt;/SatisfyAll&gt;<br />
      </indent>
      &lt;/Directory&gt;
    </example>
</usage>

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

</directivesynopsis>

<directivesynopsis type="section">
<name>SatisfyOne</name>
<description>Enclose a group of authorization directives that must 
satisfy at least one in order to grant access to a resource.  This 
block allows for 'OR' logic to be applied to various authorization 
providers.</description>
<syntax>&lt;SatisfyOne&gt;
... &lt;/SatisfyOne&gt;</syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p><directive type="section">SatisfyOne</directive> and
    <code>&lt;/SatisfyOne&gt;</code> are used to enclose a group of
    authorization directives that must satisfy at least one in order to 
    grant access to a resource.</p>

    <p>See the <directive module="mod_authz_core">
    &lt;SatisfyAll&gt;</directive> directive for a usage example.</p>

</usage>

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

</directivesynopsis>

<directivesynopsis>
<name>AuthzMergeRules</name>
<description>Set to 'on' to allow the parent's &lt;Directory&gt; or &lt;Location&gt; 
authz rules to be merged into the current &lt;Directory&gt; or &lt;Location&gt;.  
Set to 'off' to disable merging. If set to 'off', only the authz rules defined in 
the current &lt;Directory&gt; or &lt;Location&gt; block will apply.</description>
<syntax>AuthMergeRules on | off</syntax>
<default>AuthMergeRules on</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>By default all of the authorization rules within a &lt;Directory&gt;
    &lt;Location&gt; hierarchy are merged together to form a single 
    logical authorization operation.  If AuthzMergeRules is set to 'off', then
    only the authorization rules that are contained with the current 
    &lt;Directory&gt; or &lt;Location&gt; block are considered. This
    allows the configuration to determine exactly how authorization will
    be determine without having to take into consideration the 
    authorization rules that may exist above it.</p>
</usage>

</directivesynopsis>

</modulesynopsis>