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 HTTPD 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> directive
  49     in the same way as a base authorization provider.  Besides the ability to
  50     create and alias an extended provider, it also allows the same extended
  51     authorization provider to be reference by multiple locations.
  52     </p>
  53
  54     <section id="example"><title>Example</title>
  55         <p>The example below creates two different ldap authorization provider
  56         aliases based on the ldap-group authorization provider.  This example
  57         allows a single authorization location to check group membership within
  58         multiple ldap hosts:
  59         </p>
  60
  61         <highlight language="config">
  62 &lt;AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx&gt;
  63     AuthLDAPBindDN cn=youruser,o=ctx
  64     AuthLDAPBindPassword yourpassword
  65     AuthLDAPURL ldap://ldap.host/o=ctx
  66 &lt;/AuthzProviderAlias&gt;
  67
  68 &lt;AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev&gt;
  69     AuthLDAPBindDN cn=yourotheruser,o=dev
  70     AuthLDAPBindPassword yourotherpassword
  71     AuthLDAPURL ldap://other.ldap.host/o=dev?cn
  72 &lt;/AuthzProviderAlias&gt;
  73
  74 Alias /secure /webpages/secure
  75 &lt;Directory /webpages/secure&gt;
  76     Require all granted
  77
  78     AuthBasicProvider file
  79
  80     AuthType Basic
  81     AuthName LDAP_Protected_Place
  82
  83     #implied OR operation
  84     Require ldap-group-alias1
  85     Require ldap-group-alias2
  86 &lt;/Directory&gt;
  87         </highlight>
  88     </section>
  89
  90 </section>
  91
  92 <section id="logic"><title>Authorization Containers</title>
  93
  94     <p>The authorization container directives
  95     <directive module="mod_authz_core" type="section">RequireAll</directive>,
  96     <directive module="mod_authz_core" type="section">RequireAny</directive>
  97     and
  98     <directive module="mod_authz_core" type="section">RequireNone</directive>
  99     may be combined with each other and with the
 100     <directive module="mod_authz_core">Require</directive>
 101     directive to express complex authorization logic.</p>
 102
 103     <p>The example below expresses the following authorization logic.
 104     In order to access the resource, the user must either be the
 105     <code>superadmin</code> user, or belong to both the
 106     <code>admins</code> group and the <code>Administrators</code> LDAP
 107     group and either belong to the <code>sales</code> group or
 108     have the LDAP <code>dept</code> attribute <code>sales</code>.
 109     Furthermore, in order to access the resource, the user must
 110     not belong to either the <code>temps</code> group or the
 111     LDAP group <code>Temporary Employees</code>.</p>
 112
 113     <highlight language="config">
 114 &lt;Directory /www/mydocs&gt;
 115     &lt;RequireAll&gt;
 116         &lt;RequireAny&gt;
 117             Require user superadmin
 118             &lt;RequireAll&gt;
 119                 Require group admins
 120                 Require ldap-group cn=Administrators,o=Airius
 121                 &lt;RequireAny&gt;
 122                     Require group sales
 123                     Require ldap-attribute dept="sales"
 124                 &lt;/RequireAny&gt;
 125             &lt;/RequireAll&gt;
 126         &lt;/RequireAny&gt;
 127         &lt;RequireNone&gt;
 128             Require group temps
 129             Require ldap-group cn=Temporary Employees,o=Airius
 130         &lt;/RequireNone&gt;
 131     &lt;/RequireAll&gt;
 132 &lt;/Directory&gt;
 133     </highlight>
 134 </section>
 135
 136 <section id="requiredirectives"><title>The Require Directives</title>
 137
 138   <p><module>mod_authz_core</module> provides some generic authorization
 139   providers which can be used with the
 140   <directive module="mod_authz_core">Require</directive> directive.</p>
 141
 142   <section id="reqenv"><title>Require env</title>
 143
 144     <p>The <code>env</code> provider allows access to the server
 145     to be controlled based on the existence of an <a
 146     href="../env.html">environment variable</a>. When <code>Require
 147     env <var>env-variable</var></code> is specified, then the request is
 148     allowed access if the environment variable <var>env-variable</var>
 149     exists. The server provides the ability to set environment
 150     variables in a flexible way based on characteristics of the client
 151     request using the directives provided by
 152     <module>mod_setenvif</module>. Therefore, this directive can be
 153     used to allow access based on such factors as the clients
 154     <code>User-Agent</code> (browser type), <code>Referer</code>, or
 155     other HTTP request header fields.</p>
 156
 157     <highlight language="config">
 158 SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
 159 &lt;Directory /docroot&gt;
 160     Require env let_me_in
 161 &lt;/Directory&gt;
 162     </highlight>
 163
 164     <p>In this case, browsers with a user-agent string beginning
 165     with <code>KnockKnock/2.0</code> will be allowed access, and all
 166     others will be denied.</p>
 167
 168   </section>
 169
 170   <section id="reqall"><title>Require all</title>
 171
 172     <p>The <code>all</code> provider mimics the functionality the
 173     was previously provided by the 'Allow from all' and 'Deny from all'
 174     directives.  This provider can take one of two arguments which are
 175     'granted' or 'denied'.  The following examples will grant or deny
 176     access to all requests.</p>
 177
 178     <highlight language="config">
 179     Require all granted
 180     </highlight>
 181
 182     <highlight language="config">
 183     Require all denied
 184     </highlight>
 185
 186   </section>
 187
 188   <section id="reqmethod"><title>Require method</title>
 189
 190     <p>The <code>method</code> provider allows to use the HTTP method in
 191     authorization decisions. The GET and HEAD methods are treated as
 192     equivalent. The TRACE method is not available to this provider,
 193     use <directive module="core">TraceEnable</directive> instead.</p>
 194
 195     <p>The following example will only allow GET, HEAD, POST, and OPTIONS
 196     requests:</p>
 197
 198     <highlight language="config">
 199         Require method GET POST OPTIONS
 200     </highlight>
 201
 202     <p>The following example will allow GET, HEAD, POST, and OPTIONS
 203     requests without authentication, and require a valid user for all other
 204     methods:</p>
 205
 206     <highlight language="config">
 207 &lt;RequireAny&gt;
 208     &nbsp;Require method GET POST OPTIONS
 209     &nbsp;Require valid-user
 210 &lt;/RequireAny&gt;
 211     </highlight>
 212
 213   </section>
 214
 215   <section id="reqexpr"><title>Require expr</title>
 216
 217   <p>The <code>expr</code> provider allows to base authorization
 218   decisions on arbitrary expressions.</p>
 219
 220     <highlight language="config">
 221         Require expr %{TIME_HOUR} &gt;= 9 &amp;&amp; %{TIME_HOUR} &lt;= 17
 222     </highlight>
 223
 224   <p>The syntax is described in the <a href="../expr.html">ap_expr</a>
 225   documentation.</p>
 226
 227   <p>Normally, the expression is evaluated before authentication. However, if
 228   the expression returns false and references the variable
 229   <code>%{REMOTE_USER}</code>, authentication will be performed and
 230   the expression will be re-evaluated.</p>
 231
 232   </section>
 233
 234
 235 </section>
 236
 237 <directivesynopsis>
 238 <name>Require</name>
 239 <description>Tests whether an authenticated user is authorized by
 240 an authorization provider.</description>
 241 <syntax>Require [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 tests whether an authenticated user is authorized
 249     according to a particular authorization provider and the specified
 250     restrictions. <module>mod_authz_core</module> provides the following
 251     generic authorization providers:</p>
 252
 253     <dl>
 254       <dt><code>Require all granted</code></dt>
 255       <dd>Access is allowed unconditionally.</dd>
 256
 257       <dt><code>Require all denied</code></dt>
 258       <dd>Access is denied unconditionally.</dd>
 259
 260       <dt><code>Require env <var>env-var</var> [<var>env-var</var>]
 261       ...</code></dt>
 262       <dd>Access is allowed only if one of the given environment variables is
 263           set.</dd>
 264
 265       <dt><code>Require method <var>http-method</var> [<var>http-method</var>]
 266       ...</code></dt>
 267       <dd>Access is allowed only for the given HTTP methods.</dd>
 268
 269       <dt><code>Require expr <var>expression</var> </code></dt>
 270       <dd>Access is allowed if <var>expression</var> evaluates to true.</dd>
 271     </dl>
 272
 273     <p>Some of the allowed syntaxes provided by <module>mod_authz_user</module>,
 274        <module>mod_authz_host</module>,
 275        and <module>mod_authz_groupfile</module> are:</p>
 276
 277     <dl>
 278       <dt><code>Require user <var>userid</var> [<var>userid</var>]
 279       ...</code></dt>
 280       <dd>Only the named users can access the resource.</dd>
 281
 282       <dt><code>Require group <var>group-name</var> [<var>group-name</var>]
 283       ...</code></dt>
 284       <dd>Only users in the named groups can access the resource.</dd>
 285
 286       <dt><code>Require valid-user</code></dt>
 287       <dd>All valid users can access the resource.</dd>
 288
 289       <dt><code>Require ip 10 172.20 192.168.2</code></dt>
 290       <dd>Clients in the specified IP address ranges can access the
 291       resource.</dd>
 292     </dl>
 293
 294     <p>Other authorization modules that implement require options
 295     include <module>mod_authnz_ldap</module>,
 296     <module>mod_authz_dbm</module>, <module>mod_authz_dbd</module>,
 297     <module>mod_authz_owner</module> and <module>mod_ssl</module>.</p>
 298
 299     <p>In most cases, for a complete authentication and authorization
 300     configuration, <directive>Require</directive> must be accompanied by
 301     <directive module="mod_authn_core">AuthName</directive>, <directive
 302     module="mod_authn_core">AuthType</directive> and
 303     <directive module="mod_auth_basic">AuthBasicProvider</directive> or
 304     <directive module="mod_auth_digest">AuthDigestProvider</directive>
 305     directives, and directives such as
 306     <directive module="mod_authn_file">AuthUserFile</directive>
 307     and <directive module="mod_authz_groupfile">AuthGroupFile</directive> (to
 308     define users and groups) in order to work correctly. Example:</p>
 309
 310     <highlight language="config">
 311 AuthType Basic
 312 AuthName "Restricted Resource"
 313 AuthBasicProvider file
 314 AuthUserFile /web/users
 315 AuthGroupFile /web/groups
 316 Require group admin
 317     </highlight>
 318
 319     <p>Access controls which are applied in this way are effective for
 320     <strong>all</strong> methods. <strong>This is what is normally
 321     desired.</strong> If you wish to apply access controls only to
 322     specific methods, while leaving other methods unprotected, then
 323     place the <directive>Require</directive> statement into a
 324     <directive module="core" type="section">Limit</directive>
 325     section.</p>
 326
 327     <p>The result of the <directive>Require</directive> directive
 328     may be negated through the use of the
 329     <code>not</code> option.  As with the other negated authorization
 330     directive <directive type="section">RequireNone</directive>,
 331     when the <directive>Require</directive> directive is negated it can
 332     only fail or return a neutral result, and therefore may never
 333     independently authorize a request.</p>
 334
 335     <p>In the following example, all users in the <code>alpha</code>
 336     and <code>beta</code> groups are authorized, except for those who
 337     are also in the <code>reject</code> group.</p>
 338
 339     <highlight language="config">
 340 &lt;Directory /www/docs&gt;
 341     &lt;RequireAll&gt;
 342         Require group alpha beta
 343         Require not group reject
 344     &lt;/RequireAll&gt;
 345 &lt;/Directory&gt;
 346     </highlight>
 347
 348     <p>When multiple <directive>Require</directive> directives are
 349     used in a single
 350     <a href="../sections.html#mergin">configuration section</a>
 351     and are not contained in another authorization directive like
 352     <directive module="mod_authz_core" type="section">RequireAll</directive>,
 353     they are implicitly contained within a
 354     <directive module="mod_authz_core" type="section">RequireAny</directive>
 355     directive.  Thus the first one to authorize a user authorizes the
 356     entire request, and subsequent <directive>Require</directive> directives
 357     are ignored.</p>
 358 </usage>
 359
 360 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 361     and Access Control</a></seealso>
 362 <seealso><a href="#logic">Authorization Containers</a></seealso>
 363 <seealso><module>mod_authn_core</module></seealso>
 364 <seealso><module>mod_authz_host</module></seealso>
 365 </directivesynopsis>
 366
 367 <directivesynopsis type="section">
 368 <name>RequireAll</name>
 369 <description>Enclose a group of authorization directives of which none
 370 must fail and at least one must succeed for the enclosing directive to
 371 succeed.</description>
 372 <syntax>&lt;RequireAll&gt; ... &lt;/RequireAll&gt;</syntax>
 373 <contextlist><context>directory</context><context>.htaccess</context>
 374 </contextlist>
 375 <override>AuthConfig</override>
 376
 377 <usage>
 378     <p><directive type="section">RequireAll</directive> and
 379     <code>&lt;/RequireAll&gt;</code> are used to enclose a group of
 380     authorization directives of which none must fail and at least one
 381     must succeed in order for
 382     the <directive type="section">RequireAll</directive> directive to
 383     succeed.</p>
 384
 385     <p>If none of the directives contained within the
 386     <directive type="section">RequireAll</directive> directive fails,
 387     and at least one succeeds, then the
 388     <directive type="section">RequireAll</directive> directive
 389     succeeds.  If none succeed and none fail, then it returns a
 390     neutral result.  In all other cases, it fails.</p>
 391 </usage>
 392
 393 <seealso><a href="#logic">Authorization Containers</a></seealso>
 394 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 395     and Access Control</a></seealso>
 396
 397 </directivesynopsis>
 398
 399 <directivesynopsis type="section">
 400 <name>RequireAny</name>
 401 <description>Enclose a group of authorization directives of which one
 402 must succeed for the enclosing directive to succeed.</description>
 403 <syntax>&lt;RequireAny&gt; ... &lt;/RequireAny&gt;</syntax>
 404 <contextlist><context>directory</context><context>.htaccess</context>
 405 </contextlist>
 406 <override>AuthConfig</override>
 407
 408 <usage>
 409     <p><directive type="section">RequireAny</directive> and
 410     <code>&lt;/RequireAny&gt;</code> are used to enclose a group of
 411     authorization directives of which one must succeed in order for
 412     the <directive type="section">RequireAny</directive> directive to
 413     succeed.</p>
 414
 415     <p>If one or more of the directives contained within the
 416     <directive type="section">RequireAny</directive> directive succeed,
 417     then the <directive type="section">RequireAny</directive> directive
 418     succeeds.  If none succeed and none fail, then it returns a
 419     neutral result.  In all other cases, it fails.</p>
 420
 421     <note>Because negated authorization directives are unable to
 422     return a successful result, they can not significantly influence
 423     the result of a <directive type="section">RequireAny</directive>
 424     directive.  (At most they could cause the directive to fail in
 425     the case where they failed and all other directives returned a
 426     neutral value.)  Therefore negated authorization directives
 427     are not permitted within a <directive type="section">RequireAny</directive>
 428     directive.</note>
 429 </usage>
 430
 431 <seealso><a href="#logic">Authorization Containers</a></seealso>
 432 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 433     and Access Control</a></seealso>
 434
 435 </directivesynopsis>
 436
 437 <directivesynopsis type="section">
 438 <name>RequireNone</name>
 439 <description>Enclose a group of authorization directives of which none
 440 must succeed for the enclosing directive to not fail.</description>
 441 <syntax>&lt;RequireNone&gt; ... &lt;/RequireNone&gt;</syntax>
 442 <contextlist><context>directory</context><context>.htaccess</context>
 443 </contextlist>
 444 <override>AuthConfig</override>
 445
 446 <usage>
 447     <p><directive type="section">RequireNone</directive> and
 448     <code>&lt;/RequireNone&gt;</code> are used to enclose a group of
 449     authorization directives of which none must succeed
 450     in order for the
 451     <directive type="section">RequireNone</directive> directive to
 452     not fail.</p>
 453
 454     <p>If one or more of the directives contained within the
 455     <directive type="section">RequireNone</directive> directive succeed,
 456     then the <directive type="section">RequireNone</directive> directive
 457     fails.  In all other cases, it returns a neutral result.  Thus as with
 458     the other negated authorization directive <code>Require not</code>,
 459     it can never independently
 460     authorize a request because it can never return a successful result.
 461     It can be used, however, to restrict the set of users who are
 462     authorized to access a resource.</p>
 463
 464     <note>Because negated authorization directives are unable to
 465     return a successful result, they can not significantly influence
 466     the result of a <directive type="section">RequireNone</directive>
 467     directive.  Therefore negated authorization directives
 468     are not permitted within a
 469     <directive type="section">RequireNone</directive> directive.</note>
 470 </usage>
 471
 472 <seealso><a href="#logic">Authorization Containers</a></seealso>
 473 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 474     and Access Control</a></seealso>
 475
 476 </directivesynopsis>
 477
 478 <directivesynopsis>
 479 <name>AuthMerging</name>
 480 <description>Controls the manner in which each configuration section's
 481 authorization logic is combined with that of preceding configuration
 482 sections.</description>
 483 <syntax>AuthMerging Off | And | Or</syntax>
 484 <default>AuthMerging Off</default>
 485 <contextlist><context>directory</context><context>.htaccess</context>
 486 </contextlist>
 487 <override>AuthConfig</override>
 488
 489 <usage>
 490     <p>When authorization is enabled, it is normally inherited by each
 491     subsequent <a href="../sections.html#mergin">configuration section</a>,
 492     unless a different set of authorization directives are specified.
 493     This is the default action, which corresponds to an explicit setting
 494     of <code>AuthMerging Off</code>.</p>
 495
 496     <p>However, there may be circumstances in which is it desirable
 497     for a configuration section's authorization to be combined with
 498     that of its predecessor while configuration sections are being
 499     merged.  Two options are available for this case, <code>And</code>
 500     and <code>Or</code>.</p>
 501
 502     <p>When a configuration section contains <code>AuthMerging And</code>
 503     or <code>AuthMerging Or</code>,
 504     its authorization logic is combined with that of the nearest
 505     predecessor (according to the overall order of configuration sections)
 506     which also contains authorization logic as if the two sections
 507     were jointly contained within a
 508     <directive module="mod_authz_core" type="section">RequireAll</directive> or
 509     <directive module="mod_authz_core" type="section">RequireAny</directive>
 510     directive, respectively.</p>
 511
 512     <note>The setting of <directive>AuthMerging</directive> is not
 513     inherited outside of the configuration section in which it appears.
 514     In the following example, only users belonging to group <code>alpha</code>
 515     may access <code>/www/docs</code>.  Users belonging to either
 516     groups <code>alpha</code> or <code>beta</code> may access
 517     <code>/www/docs/ab</code>.  However, the default <code>Off</code>
 518     setting of <directive>AuthMerging</directive> applies to the
 519     <directive type="section" module="core">Directory</directive>
 520     configuration section for <code>/www/docs/ab/gamma</code>, so
 521     that section's authorization directives override those of the
 522     preceding sections.  Thus only users belong to the group
 523     <code>gamma</code> may access <code>/www/docs/ab/gamma</code>.</note>
 524
 525     <highlight language="config">
 526 &lt;Directory /www/docs&gt;
 527     AuthType Basic
 528     AuthName Documents
 529     AuthBasicProvider file
 530     AuthUserFile /usr/local/apache/passwd/passwords
 531     Require group alpha
 532 &lt;/Directory&gt;
 533
 534 &lt;Directory /www/docs/ab&gt;
 535     AuthMerging Or
 536     Require group beta
 537 &lt;/Directory&gt;
 538
 539 &lt;Directory /www/docs/ab/gamma&gt;
 540     Require group gamma
 541 &lt;/Directory&gt;
 542     </highlight>
 543 </usage>
 544
 545 </directivesynopsis>
 546
 547 <directivesynopsis type="section">
 548 <name>AuthzProviderAlias</name>
 549 <description>Enclose a group of directives that represent an
 550 extension of a base authorization provider and referenced by the specified
 551 alias</description>
 552 <syntax>&lt;AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>&gt;
 553 ... &lt;/AuthzProviderAlias&gt;
 554 </syntax>
 555 <contextlist><context>server config</context>
 556 </contextlist>
 557
 558 <usage>
 559     <p><directive type="section">AuthzProviderAlias</directive> and
 560     <code>&lt;/AuthzProviderAlias&gt;</code> are used to enclose a group of
 561     authorization directives that can be referenced by the alias name using the
 562     directive <directive module="mod_authz_core">Require</directive>.</p>
 563
 564 </usage>
 565 </directivesynopsis>
 566
 567 <directivesynopsis>
 568 <name>AuthzSendForbiddenOnFailure</name>
 569 <description>Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if
 570 authentication succeeds but authorization fails
 571 </description>
 572 <syntax>AuthzSendForbiddenOnFailure On|Off</syntax>
 573 <default>AuthzSendForbiddenOnFailure Off</default>
 574 <contextlist><context>directory</context><context>.htaccess</context>
 575 </contextlist>
 576 <compatibility>Available in Apache HTTPD 2.3.11 and later</compatibility>
 577
 578 <usage>
 579     <p>If authentication succeeds but authorization fails, Apache HTTPD will
 580     respond with an HTTP response code of '401 UNAUTHORIZED' by default. This
 581     usually causes browsers to display the password dialogue to the user
 582     again, which is not wanted in all situations.
 583     <directive>AuthzSendForbiddenOnFailure</directive> allows to change the
 584     response code to '403 FORBIDDEN'.</p>
 585
 586     <note type="warning"><title>Security Warning</title>
 587     <p>Modifying the response in case of missing authorization weakens the
 588     security of the password, because it reveals to a possible attacker, that
 589     his guessed password was right.</p>
 590     </note>
 591 </usage>
 592 </directivesynopsis>
 593
 594
 595 </modulesynopsis>