granicus.if.org Git - apache/blob - docs/manual/mod/mod_authz_core.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_authz_core.xml.meta">
  24
  25 <name>mod_authz_core</name>
  26 <description>Core Authorization</description>
  27 <status>Base</status>
  28 <sourcefile>mod_authz_core.c</sourcefile>
  29 <identifier>authz_core_module</identifier>
  30 <compatibility>Available in Apache 2.3 and later</compatibility>
  31
  32 <summary>
  33     <p>This module provides core authorization capabilities so that
  34     authenticated users can be allowed or denied access to portions
  35     of the web site. <module>mod_authz_core</module> provides the
  36     functionality to register various authorization providers. It is
  37     usually used in conjunction with an authentication
  38     provider module such as <module>mod_authn_file</module> and an
  39     authorization module such as <module>mod_authz_user</module>. It
  40     also allows for advanced logic to be applied to the
  41     authorization processing.</p>
  42 </summary>
  43
  44 <section id="authzalias"><title>Creating Authorization Provider Aliases</title>
  45
  46     <p>Extended authorization providers can be created within the configuration
  47     file and assigned an alias name.  The alias providers can then be referenced
  48     through the <directive module="mod_authz_core">Require</directive> and
  49     <directive module="mod_authz_core">Match</directive> directives
  50     in the same way as a base authorization provider.  Besides the ability to
  51     create and alias an extended provider, it also allows the same extended
  52     authorization provider to be reference by multiple locations.
  53     </p>
  54
  55     <section id="example"><title>Example</title>
  56         <p>The example below creates two different ldap authorization provider
  57         aliases based on the ldap-group authorization provider.  This example
  58         allows a single authorization location to check group membership within
  59         multiple ldap hosts:
  60         </p>
  61
  62         <example><title>Example</title>
  63           &lt;AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx&gt;<br />
  64           <indent>
  65              AuthLDAPBindDN cn=youruser,o=ctx<br />
  66              AuthLDAPBindPassword yourpassword<br />
  67              AuthLDAPURL ldap://ldap.host/o=ctx<br />
  68           </indent>
  69           &lt;/AuthzProviderAlias&gt;<br /><br />
  70           &lt;AuthzProviderAlias ldap-group ldap-group-alias2
  71            cn=my-other-group,o=dev&gt;<br />
  72           <indent>
  73              AuthLDAPBindDN cn=yourotheruser,o=dev<br />
  74              AuthLDAPBindPassword yourotherpassword<br />
  75              AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br />
  76           </indent>
  77           &lt;/AuthzProviderAlias&gt;<br /><br />
  78
  79           Alias /secure /webpages/secure<br />
  80           &lt;Directory /webpages/secure&gt;<br />
  81           <indent>
  82              Order deny,allow<br />
  83              Allow from all<br /><br />
  84
  85              AuthBasicProvider file<br /><br />
  86
  87              AuthType Basic<br />
  88              AuthName LDAP_Protected_Place<br /><br />
  89
  90              #implied OR operation<br />
  91              Require alias1-ldap-group<br />
  92              Require alias2-ldap-group<br />
  93           </indent> &lt;/Directory&gt;<br />
  94         </example>
  95     </section>
  96
  97 </section>
  98
  99 <section id="logic"><title>Authorization Containers</title>
 100
 101     <p>The authorization container directives
 102     <directive module="mod_authz_core" type="section">MatchAll</directive>,
 103     <directive module="mod_authz_core" type="section">MatchAny</directive>,
 104     <directive module="mod_authz_core" type="section">MatchNotAll</directive>
 105     and
 106     <directive module="mod_authz_core" type="section">MatchNotAny</directive>
 107     may be combined with each other and with the
 108     <directive module="mod_authz_core">Match</directive>
 109     directive to express complex authorization logic.</p>
 110
 111     <p>The example below expresses the following authorization logic.
 112     In order to access the resource, the user must either be the
 113     <code>superadmin</code> user, or belong to both the
 114     <code>admins</code> group and the <code>Administrators</code> LDAP
 115     group and either belong to the <code>sales</code> group or
 116     have the LDAP <code>dept</code> attribute <code>sales</code>.
 117     Furthermore, in order to access the resource, the user must
 118     not belong to either the <code>temps</code> group or the
 119     LDAP group <code>Temporary Employees</code>.</p>
 120
 121     <example>
 122         &lt;Directory /www/mydocs&gt;
 123         <indent>
 124             &lt;MatchAny&gt;
 125             <indent>
 126                 Match user superadmin<br />
 127                 &lt;MatchAll&gt;
 128                 <indent>
 129                     Match group admins<br />
 130                     Match ldap-group cn=Administrators,o=Airius<br />
 131                     &lt;MatchAny&gt;
 132                     <indent>
 133                         Match group sales<br />
 134                         Match ldap-attribute dept="sales"
 135                     </indent>
 136                     &lt;/MatchAny&gt;
 137                 </indent>
 138                 &lt;/MatchAll&gt;
 139             </indent>
 140             &lt;/MatchAny&gt;<br />
 141             &lt;MatchNotAny&gt;
 142             <indent>
 143                 Match group temps<br />
 144                 Match ldap-group cn=Temporary Employees,o=Airius
 145             </indent>
 146             &lt;/MatchNotAny&gt;
 147         </indent>
 148         &lt;/Directory&gt;
 149     </example>
 150 </section>
 151
 152 <directivesynopsis>
 153 <name>Require</name>
 154 <description>Tests whether an authenticated user is authorized by
 155 an authorization provider.</description>
 156 <syntax>Require <var>entity-name</var> [<var>entity-name</var>] ...</syntax>
 157 <contextlist><context>directory</context><context>.htaccess</context>
 158 </contextlist>
 159 <override>AuthConfig</override>
 160
 161 <usage>
 162     <p>This directive tests whether an authenticated user is authorized
 163     according to a particular authorization provider and the specified
 164     restrictions.  Some of the allowed syntaxes provided by
 165     <module>mod_authz_user</module> and
 166     <module>mod_authz_groupfile</module> are:</p>
 167
 168     <dl>
 169       <dt><code>Require user <var>userid</var> [<var>userid</var>]
 170       ...</code></dt>
 171       <dd>Only the named users can access the resource.</dd>
 172
 173       <dt><code>Require group <var>group-name</var> [<var>group-name</var>]
 174       ...</code></dt>
 175       <dd>Only users in the named groups can access the resource.</dd>
 176
 177       <dt><code>Require valid-user</code></dt>
 178       <dd>All valid users can access the resource.</dd>
 179     </dl>
 180
 181     <p>Other authorization modules that implement require options
 182     include <module>mod_authnz_ldap</module>,
 183     <module>mod_authz_dbm</module>, <module>mod_authz_dbd</module>,
 184     <module>mod_authz_host</module>, and
 185     <module>mod_authz_owner</module>.</p>
 186
 187     <p>For a complete authentication and authorization configuration,
 188     <directive>Require</directive> must be accompanied by
 189     <directive module="mod_authn_core">AuthName</directive>, <directive
 190     module="mod_authn_core">AuthType</directive> and
 191     <directive module="mod_auth_basic">AuthBasicProvider</directive> or
 192     <directive module="mod_auth_digest">AuthDigestProvider</directive>
 193     directives, and directives such as
 194     <directive module="mod_authn_file">AuthUserFile</directive>
 195     and <directive module="mod_authz_groupfile">AuthGroupFile</directive> (to
 196     define users and groups) in order to work correctly. Example:</p>
 197
 198     <example>
 199        AuthType Basic<br />
 200        AuthName "Restricted Resource"<br />
 201        AuthBasicProvider file<br />
 202        AuthUserFile /web/users<br />
 203        AuthGroupFile /web/groups<br />
 204        Require group admin
 205     </example>
 206
 207     <p>Access controls which are applied in this way are effective for
 208     <strong>all</strong> methods. <strong>This is what is normally
 209     desired.</strong> If you wish to apply access controls only to
 210     specific methods, while leaving other methods unprotected, then
 211     place the <directive>Require</directive> statement into a
 212     <directive module="core" type="section">Limit</directive>
 213     section.</p>
 214
 215     <p>When multiple <directive>Require</directive> directives are
 216     used in a single
 217     <a href="../sections.html#mergin">configuration section</a>,
 218     the first one to authorize a user authorizes the entire request,
 219     and subsequent <directive>Require</directive> directives are
 220     ignored.  In other words, all <directive>Require</directive> directives
 221     are enclosed in an implied <directive module="mod_authz_core"
 222     type="section">MatchAny</directive> directive.</p>
 223
 224     <note><directive>Require</directive> directives may not be combined
 225     with the <directive module="mod_authz_core">Match</directive> directive
 226     or any authorization container directives, such as
 227     <directive module="mod_authz_core"
 228     type="section">MatchAll</directive>.</note>
 229 </usage>
 230
 231 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 232     and Access Control</a></seealso>
 233 <seealso><module>mod_authn_core</module></seealso>
 234 <seealso><module>mod_authz_host</module></seealso>
 235 </directivesynopsis>
 236
 237 <directivesynopsis>
 238 <name>Match</name>
 239 <description>Tests whether an authenticated user is authorized by
 240 an authorization provider.</description>
 241 <syntax>Match [not] <var>entity-name</var>
 242 [<var>entity-name</var>] ...</syntax>
 243 <contextlist><context>directory</context><context>.htaccess</context>
 244 </contextlist>
 245 <override>AuthConfig</override>
 246
 247 <usage>
 248     <p>This directive is similar to the
 249     <directive module="mod_authz_core">Require</directive> directive;
 250     it tests whether an authenticated user is authorized according to
 251     a particular authorization provider and the specified restrictions.</p>
 252
 253     <p>Unlike the <directive module="mod_authz_core">Require</directive>
 254     directive, it may be used with and inside authorization container
 255     directives such as
 256     <directive module="mod_authz_core" type="section">MatchAll</directive>.</p>
 257
 258     <p>Furthermore, its result may be negated through the use of the
 259     <code>not</code> option.  As with other negated authorization directives,
 260     in this case the <directive>Match</directive> directive may only
 261     either fail or return a neutral result, and can therefore never
 262     independently authorize a request.</p>
 263
 264     <p>In the following example, all users in the <code>alpha</code>
 265     and <code>beta</code> groups are authorized, except for those who
 266     are also in the <code>reject</code> group.</p>
 267
 268     <example>
 269         &lt;Directory /www/docs&gt;
 270         <indent>
 271             Match group alpha beta<br />
 272             Match not group reject
 273         </indent>
 274         &lt;/Directory&gt;
 275     </example>
 276
 277     <p>When multiple <directive>Match</directive> directives are
 278     used in a single
 279     <a href="../sections.html#mergin">configuration section</a>
 280     and are not contained in another authorization directive like
 281     <directive module="mod_authz_core" type="section">MatchAny</directive>,
 282     they are implicitly contained within a
 283     <directive module="mod_authz_core" type="section">MatchAll</directive>
 284     directive.  Thus for the user to be authorized, all such
 285     <directive>Match</directive> directives must not fail, and
 286     at least one must be successful.</p>
 287
 288     <note><directive>Match</directive> directives may not be combined
 289     with the <directive module="mod_authz_core">Require</directive>
 290     directive.</note>
 291 </usage>
 292
 293 <seealso><directive module="mod_authz_core">Require</directive></seealso>
 294 <seealso><a href="#logic">Authorization Containers</a></seealso>
 295 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 296     and Access Control</a></seealso>
 297 </directivesynopsis>
 298
 299 <directivesynopsis type="section">
 300 <name>MatchAll</name>
 301 <description>Enclose a group of authorization directives of which none
 302 must fail and at least one must succeed for the enclosing directive to
 303 succeed.</description>
 304 <syntax>&lt;MatchAll&gt;
 305 ... &lt;/MatchAll&gt;</syntax>
 306 <contextlist><context>directory</context><context>.htaccess</context>
 307 </contextlist>
 308 <override>AuthConfig</override>
 309
 310 <usage>
 311     <p><directive type="section">MatchAll</directive> and
 312     <code>&lt;/MatchAll&gt;</code> are used to enclose a group of
 313     authorization directives of which none must fail and at least one
 314     must succeed in order for
 315     the <directive type="section">MatchAll</directive> directive to
 316     succeed.</p>
 317
 318     <p>If none of the directives contained within the
 319     <directive type="section">MatchAll</directive> directive fails,
 320     and at least one succeeds, then the
 321     <directive type="section">MatchAll</directive> directive
 322     succeeds.  If none succeed and none fail, then it returns a
 323     neutral result.  In all other cases, it fails.</p>
 324 </usage>
 325
 326 <seealso><a href="#logic">Authorization Containers</a></seealso>
 327 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 328     and Access Control</a></seealso>
 329
 330 </directivesynopsis>
 331
 332 <directivesynopsis type="section">
 333 <name>MatchAny</name>
 334 <description>Enclose a group of authorization directives of which one
 335 must succeed for the enclosing directive to succeed.</description>
 336 <syntax>&lt;MatchAny&gt;
 337 ... &lt;/MatchAny&gt;</syntax>
 338 <contextlist><context>directory</context><context>.htaccess</context>
 339 </contextlist>
 340 <override>AuthConfig</override>
 341
 342 <usage>
 343     <p><directive type="section">MatchAny</directive> and
 344     <code>&lt;/MatchAny&gt;</code> are used to enclose a group of
 345     authorization directives of which one must succeed in order for
 346     the <directive type="section">MatchAny</directive> directive to
 347     succeed.</p>
 348
 349     <p>If one or more of the directives contained within the
 350     <directive type="section">MatchAny</directive> directive succeed,
 351     then the <directive type="section">MatchAny</directive> directive
 352     succeeds.  If none succeed and none fail, then it returns a
 353     neutral result.  In all other cases, it fails.</p>
 354
 355     <note>Because negated authorization directives are unable to
 356     return a successful result, they can not significantly influence
 357     the result of a <directive type="section">MatchAny</directive>
 358     directive.  (At most they could cause the directive to fail in
 359     the case where they failed and all other directives returned a
 360     neutral value.)  Therefore negated authorization directives
 361     are not permitted within a <directive type="section">MatchAny</directive>
 362     directive.</note>
 363 </usage>
 364
 365 <seealso><a href="#logic">Authorization Containers</a></seealso>
 366 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 367     and Access Control</a></seealso>
 368
 369 </directivesynopsis>
 370
 371 <directivesynopsis type="section">
 372 <name>MatchNotAll</name>
 373 <description>Enclose a group of authorization directives of which some
 374 must fail or none must succeed for the enclosing directive to
 375 not fail.</description>
 376 <syntax>&lt;MatchNotAll&gt;
 377 ... &lt;/MatchNotAll&gt;</syntax>
 378 <contextlist><context>directory</context><context>.htaccess</context>
 379 </contextlist>
 380 <override>AuthConfig</override>
 381
 382 <usage>
 383     <p><directive type="section">MatchNotAll</directive> and
 384     <code>&lt;/MatchNotAll&gt;</code> are used to enclose a group of
 385     authorization directives of which some must fail or none must succeed
 386     in order for the
 387     <directive type="section">MatchNotAll</directive> directive to
 388     not fail.</p>
 389
 390     <p>If none of the directives contained within the
 391     <directive type="section">MatchNotAll</directive> directive
 392     fail, and one or more succeed, then the
 393     <directive type="section">MatchNotAll</directive> directive fails.
 394     In all other cases, it returns a neutral result.  Thus as with
 395     the other negated authorization directives, it can never independently
 396     authorize a request because it can never return a successful result.
 397     It can be used, however, to restrict the set of users who are
 398     authorized to access a resource.</p>
 399 </usage>
 400
 401 <seealso><a href="#logic">Authorization Containers</a></seealso>
 402 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 403     and Access Control</a></seealso>
 404
 405 </directivesynopsis>
 406
 407 <directivesynopsis type="section">
 408 <name>MatchNotAny</name>
 409 <description>Enclose a group of authorization directives of which none
 410 none must succeed for the enclosing directive to not fail.</description>
 411 <syntax>&lt;MatchNotAny&gt;
 412 ... &lt;/MatchNotAny&gt;</syntax>
 413 <contextlist><context>directory</context><context>.htaccess</context>
 414 </contextlist>
 415 <override>AuthConfig</override>
 416
 417 <usage>
 418     <p><directive type="section">MatchNotAny</directive> and
 419     <code>&lt;/MatchNotAny&gt;</code> are used to enclose a group of
 420     authorization directives of which none must succeed
 421     in order for the
 422     <directive type="section">MatchNotAny</directive> directive to
 423     not fail.</p>
 424
 425     <p>If one or more of the directives contained within the
 426     <directive type="section">MatchNotAny</directive> directive succeed,
 427     then the <directive type="section">MatchNotAny</directive> directive
 428     fails.  In all other cases, it returns a neutral result.  Thus as with
 429     the other negated authorization directives, it can never independently
 430     authorize a request because it can never return a successful result.
 431     It can be used, however, to restrict the set of users who are
 432     authorized to access a resource.</p>
 433
 434     <note>Because negated authorization directives are unable to
 435     return a successful result, they can not significantly influence
 436     the result of a <directive type="section">MatchNotAny</directive>
 437     directive.  Therefore negated authorization directives
 438     are not permitted within a
 439     <directive type="section">MatchNotAny</directive> directive.</note>
 440 </usage>
 441
 442 <seealso><a href="#logic">Authorization Containers</a></seealso>
 443 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 444     and Access Control</a></seealso>
 445
 446 </directivesynopsis>
 447
 448 <directivesynopsis>
 449 <name>MergeAuthz</name>
 450 <description>Controls the manner in which each configuration section's
 451 authorization logic is combined with that of preceding configuration
 452 sections.</description>
 453 <syntax>MergeAuthz Off | MatchAll | MatchAny</syntax>
 454 <default>MergeAuthz Off</default>
 455 <contextlist><context>directory</context><context>.htaccess</context>
 456 </contextlist>
 457 <override>AuthConfig</override>
 458
 459 <usage>
 460     <p>When authorization is enabled, it is normally inherited by each
 461     subsequent <a href="../sections.html#mergin">configuration section</a>,
 462     unless a different set of authorization directives are specified.
 463     This is the default action, which corresponds to an explicit setting
 464     of <code>MergeAuthz Off</code>.</p>
 465
 466     <p>However, there may be circumstances in which is it desirable
 467     for a configuration section's authorization to be combined with
 468     that of its predecessor while configuration sections are being
 469     merged.  Two options are available for this case, <code>MatchAll</code>
 470     and <code>MatchAny</code>.</p>
 471
 472     <p>When a configuration section contains <code>AuthzMerge MatchAll</code>
 473     or <code>AuthzMerge MatchAny</code>,
 474     its authorization logic is combined with that of the nearest
 475     predecessor (according to the overall order of configuration sections)
 476     which also contains authorization logic as if the two sections
 477     were jointly contained within a
 478     <directive module="mod_authz_core" type="section">MatchAll</directive> or
 479     <directive module="mod_authz_core" type="section">MatchAny</directive>
 480     directive, respectively.</p>
 481
 482     <note>The setting of <directive>AuthzMerge</directive> is not
 483     inherited outside of the configuration section in which it appears.
 484     In the following example, only users belonging to group <code>alpha</code>
 485     may access <code>/www/docs</code>.  Users belonging to either
 486     groups <code>alpha</code> or <code>beta</code> may access
 487     <code>/www/docs/ab</code>.  However, the default <code>Off</code>
 488     setting of <directive>AuthzMerge</directive> applies to the
 489     <directive type="section" module="core">Directory</directive>
 490     configuration section for <code>/www/docs/ab/gamma</code>, so
 491     that section's authorization directives override those of the
 492     preceding sections.  Thus only users belong to the group
 493     <code>gamma</code> may access <code>/www/docs/ab/gamma</code>.</note>
 494
 495     <example>
 496         &lt;Directory /www/docs&gt;
 497         <indent>
 498             AuthType Basic<br />
 499             AuthName Documents<br />
 500             AuthBasicProvider file<br />
 501             AuthUserFile /usr/local/apache/passwd/passwords<br />
 502             Match group alpha
 503         </indent>
 504         &lt;/Directory&gt;<br />
 505         <br />
 506         &lt;Directory /www/docs/ab&gt;
 507         <indent>
 508             AuthzMerge MatchAny<br />
 509             Match group beta
 510         </indent>
 511         &lt;/Directory&gt;<br />
 512         <br />
 513         &lt;Directory /www/docs/ab/gamma&gt;
 514         <indent>
 515             Match group gamma
 516         </indent>
 517         &lt;/Directory&gt;
 518     </example>
 519 </usage>
 520
 521 </directivesynopsis>
 522
 523 <directivesynopsis type="section">
 524 <name>AuthzProviderAlias</name>
 525 <description>Enclose a group of directives that represent an
 526 extension of a base authorization provider and referenced by the specified
 527 alias</description>
 528 <syntax>&lt;AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>&gt;
 529 ... &lt;/AuthzProviderAlias&gt;
 530 </syntax>
 531 <contextlist><context>server config</context>
 532 </contextlist>
 533
 534 <usage>
 535     <p><directive type="section">AuthzProviderAlias</directive> and
 536     <code>&lt;/AuthzProviderAlias&gt;</code> are used to enclose a group of
 537     authorization directives that can be referenced by the alias name using the
 538     directive <directive module="mod_authz_core">Require</directive>.</p>
 539
 540 </usage>
 541 </directivesynopsis>
 542
 543 </modulesynopsis>