2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
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
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <modulesynopsis metafile="mod_authz_core.xml.meta">
25 <name>mod_authz_core</name>
26 <description>Core Authorization</description>
28 <sourcefile>mod_authz_core.c</sourcefile>
29 <identifier>authz_core_module</identifier>
30 <compatibility>Available in Apache HTTPD 2.3 and later</compatibility>
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>
44 <section id="authzalias"><title>Creating Authorization Provider Aliases</title>
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.
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
61 <highlight language="config">
62 <AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
63 AuthLDAPBindDN cn=youruser,o=ctx
64 AuthLDAPBindPassword yourpassword
65 AuthLDAPURL ldap://ldap.host/o=ctx
66 </AuthzProviderAlias>
68 <AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev>
69 AuthLDAPBindDN cn=yourotheruser,o=dev
70 AuthLDAPBindPassword yourotherpassword
71 AuthLDAPURL ldap://other.ldap.host/o=dev?cn
72 </AuthzProviderAlias>
74 Alias /secure /webpages/secure
75 <Directory /webpages/secure>
78 AuthBasicProvider file
81 AuthName LDAP_Protected_Place
84 Require ldap-group-alias1
85 Require ldap-group-alias2
92 <section id="logic"><title>Authorization Containers</title>
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>
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>
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>
113 <highlight language="config">
114 <Directory /www/mydocs>
117 Require user superadmin
120 Require ldap-group cn=Administrators,o=Airius
123 Require ldap-attribute dept="sales"
129 Require ldap-group cn=Temporary Employees,o=Airius
136 <section id="requiredirectives"><title>The Require Directives</title>
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>
142 <section id="reqenv"><title>Require env</title>
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>
157 <highlight language="config">
158 SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
159 <Directory /docroot>
160 Require env let_me_in
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>
170 <section id="reqall"><title>Require all</title>
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>
178 <highlight language="config">
182 <highlight language="config">
188 <section id="reqmethod"><title>Require method</title>
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>
195 <p>The following example will only allow GET, HEAD, POST, and OPTIONS
198 <highlight language="config">
199 Require method GET POST OPTIONS
202 <p>The following example will allow GET, HEAD, POST, and OPTIONS
203 requests without authentication, and require a valid user for all other
206 <highlight language="config">
208 Require method GET POST OPTIONS
209 Require valid-user
215 <section id="reqexpr"><title>Require expr</title>
217 <p>The <code>expr</code> provider allows to base authorization
218 decisions on arbitrary expressions.</p>
220 <highlight language="config">
221 Require expr %{TIME_HOUR} -ge 9 && %{TIME_HOUR} -le 17
224 <p>The syntax is described in the <a href="../expr.html">ap_expr</a>
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>
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>
245 <override>AuthConfig</override>
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>
254 <dt><code>Require all granted</code></dt>
255 <dd>Access is allowed unconditionally.</dd>
257 <dt><code>Require all denied</code></dt>
258 <dd>Access is denied unconditionally.</dd>
260 <dt><code>Require env <var>env-var</var> [<var>env-var</var>]
262 <dd>Access is allowed only if one of the given environment variables is
265 <dt><code>Require method <var>http-method</var> [<var>http-method</var>]
267 <dd>Access is allowed only for the given HTTP methods.</dd>
269 <dt><code>Require expr <var>expression</var> </code></dt>
270 <dd>Access is allowed if <var>expression</var> evaluates to true.</dd>
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>
278 <dt><code>Require user <var>userid</var> [<var>userid</var>]
280 <dd>Only the named users can access the resource.</dd>
282 <dt><code>Require group <var>group-name</var> [<var>group-name</var>]
284 <dd>Only users in the named groups can access the resource.</dd>
286 <dt><code>Require valid-user</code></dt>
287 <dd>All valid users can access the resource.</dd>
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
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>
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>
310 <highlight language="config">
312 AuthName "Restricted Resource"
313 AuthBasicProvider file
314 AuthUserFile /web/users
315 AuthGroupFile /web/groups
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>
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>
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>
339 <highlight language="config">
340 <Directory /www/docs>
342 Require group alpha beta
343 Require not group reject
348 <p>When multiple <directive>Require</directive> directives are
350 <a href="../sections.html#merging">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
359 <note type="warning"><title>Security Warning</title>
360 <p>Exercise caution when setting authorization directives in
361 <directive module="core">Location</directive> sections
362 that overlap with content served out of the filesystem.
363 By default, these <a href="../sections.html#merging"
364 >configuration sections</a> overwrite authorization configuration
365 in <directive module="core">Directory</directive>,
366 and <directive module="core">Files</directive> sections.</p>
367 <p>The <directive module="mod_authz_core">AuthMerging</directive> directive
368 can be used to control how authorization configuration sections are
373 <seealso><a href="../howto/auth.html">Authentication, Authorization,
374 and Access Control</a></seealso>
375 <seealso><a href="#logic">Authorization Containers</a></seealso>
376 <seealso><module>mod_authn_core</module></seealso>
377 <seealso><module>mod_authz_host</module></seealso>
380 <directivesynopsis type="section">
381 <name>RequireAll</name>
382 <description>Enclose a group of authorization directives of which none
383 must fail and at least one must succeed for the enclosing directive to
384 succeed.</description>
385 <syntax><RequireAll> ... </RequireAll></syntax>
386 <contextlist><context>directory</context><context>.htaccess</context>
388 <override>AuthConfig</override>
391 <p><directive type="section">RequireAll</directive> and
392 <code></RequireAll></code> are used to enclose a group of
393 authorization directives of which none must fail and at least one
394 must succeed in order for
395 the <directive type="section">RequireAll</directive> directive to
398 <p>If none of the directives contained within the
399 <directive type="section">RequireAll</directive> directive fails,
400 and at least one succeeds, then the
401 <directive type="section">RequireAll</directive> directive
402 succeeds. If none succeed and none fail, then it returns a
403 neutral result. In all other cases, it fails.</p>
406 <seealso><a href="#logic">Authorization Containers</a></seealso>
407 <seealso><a href="../howto/auth.html">Authentication, Authorization,
408 and Access Control</a></seealso>
412 <directivesynopsis type="section">
413 <name>RequireAny</name>
414 <description>Enclose a group of authorization directives of which one
415 must succeed for the enclosing directive to succeed.</description>
416 <syntax><RequireAny> ... </RequireAny></syntax>
417 <contextlist><context>directory</context><context>.htaccess</context>
419 <override>AuthConfig</override>
422 <p><directive type="section">RequireAny</directive> and
423 <code></RequireAny></code> are used to enclose a group of
424 authorization directives of which one must succeed in order for
425 the <directive type="section">RequireAny</directive> directive to
428 <p>If one or more of the directives contained within the
429 <directive type="section">RequireAny</directive> directive succeed,
430 then the <directive type="section">RequireAny</directive> directive
431 succeeds. If none succeed and none fail, then it returns a
432 neutral result. In all other cases, it fails.</p>
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">RequireAny</directive>
437 directive. (At most they could cause the directive to fail in
438 the case where they failed and all other directives returned a
439 neutral value.) Therefore negated authorization directives
440 are not permitted within a <directive type="section">RequireAny</directive>
444 <seealso><a href="#logic">Authorization Containers</a></seealso>
445 <seealso><a href="../howto/auth.html">Authentication, Authorization,
446 and Access Control</a></seealso>
450 <directivesynopsis type="section">
451 <name>RequireNone</name>
452 <description>Enclose a group of authorization directives of which none
453 must succeed for the enclosing directive to not fail.</description>
454 <syntax><RequireNone> ... </RequireNone></syntax>
455 <contextlist><context>directory</context><context>.htaccess</context>
457 <override>AuthConfig</override>
460 <p><directive type="section">RequireNone</directive> and
461 <code></RequireNone></code> are used to enclose a group of
462 authorization directives of which none must succeed
464 <directive type="section">RequireNone</directive> directive to
467 <p>If one or more of the directives contained within the
468 <directive type="section">RequireNone</directive> directive succeed,
469 then the <directive type="section">RequireNone</directive> directive
470 fails. In all other cases, it returns a neutral result. Thus as with
471 the other negated authorization directive <code>Require not</code>,
472 it can never independently
473 authorize a request because it can never return a successful result.
474 It can be used, however, to restrict the set of users who are
475 authorized to access a resource.</p>
477 <note>Because negated authorization directives are unable to
478 return a successful result, they can not significantly influence
479 the result of a <directive type="section">RequireNone</directive>
480 directive. Therefore negated authorization directives
481 are not permitted within a
482 <directive type="section">RequireNone</directive> directive.</note>
485 <seealso><a href="#logic">Authorization Containers</a></seealso>
486 <seealso><a href="../howto/auth.html">Authentication, Authorization,
487 and Access Control</a></seealso>
492 <name>AuthMerging</name>
493 <description>Controls the manner in which each configuration section's
494 authorization logic is combined with that of preceding configuration
495 sections.</description>
496 <syntax>AuthMerging Off | And | Or</syntax>
497 <default>AuthMerging Off</default>
498 <contextlist><context>directory</context><context>.htaccess</context>
500 <override>AuthConfig</override>
503 <p>When authorization is enabled, it is normally inherited by each
504 subsequent <a href="../sections.html#mergin">configuration section</a>,
505 unless a different set of authorization directives are specified.
506 This is the default action, which corresponds to an explicit setting
507 of <code>AuthMerging Off</code>.</p>
509 <p>However, there may be circumstances in which is it desirable
510 for a configuration section's authorization to be combined with
511 that of its predecessor while configuration sections are being
512 merged. Two options are available for this case, <code>And</code>
513 and <code>Or</code>.</p>
515 <p>When a configuration section contains <code>AuthMerging And</code>
516 or <code>AuthMerging Or</code>,
517 its authorization logic is combined with that of the nearest
518 predecessor (according to the overall order of configuration sections)
519 which also contains authorization logic as if the two sections
520 were jointly contained within a
521 <directive module="mod_authz_core" type="section">RequireAll</directive> or
522 <directive module="mod_authz_core" type="section">RequireAny</directive>
523 directive, respectively.</p>
525 <note>The setting of <directive>AuthMerging</directive> is not
526 inherited outside of the configuration section in which it appears.
527 In the following example, only users belonging to group <code>alpha</code>
528 may access <code>/www/docs</code>. Users belonging to either
529 groups <code>alpha</code> or <code>beta</code> may access
530 <code>/www/docs/ab</code>. However, the default <code>Off</code>
531 setting of <directive>AuthMerging</directive> applies to the
532 <directive type="section" module="core">Directory</directive>
533 configuration section for <code>/www/docs/ab/gamma</code>, so
534 that section's authorization directives override those of the
535 preceding sections. Thus only users belong to the group
536 <code>gamma</code> may access <code>/www/docs/ab/gamma</code>.</note>
538 <highlight language="config">
539 <Directory /www/docs>
542 AuthBasicProvider file
543 AuthUserFile /usr/local/apache/passwd/passwords
547 <Directory /www/docs/ab>
552 <Directory /www/docs/ab/gamma>
560 <directivesynopsis type="section">
561 <name>AuthzProviderAlias</name>
562 <description>Enclose a group of directives that represent an
563 extension of a base authorization provider and referenced by the specified
565 <syntax><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>>
566 ... </AuthzProviderAlias>
568 <contextlist><context>server config</context>
572 <p><directive type="section">AuthzProviderAlias</directive> and
573 <code></AuthzProviderAlias></code> are used to enclose a group of
574 authorization directives that can be referenced by the alias name using the
575 directive <directive module="mod_authz_core">Require</directive>.</p>
581 <name>AuthzSendForbiddenOnFailure</name>
582 <description>Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if
583 authentication succeeds but authorization fails
585 <syntax>AuthzSendForbiddenOnFailure On|Off</syntax>
586 <default>AuthzSendForbiddenOnFailure Off</default>
587 <contextlist><context>directory</context><context>.htaccess</context>
589 <compatibility>Available in Apache HTTPD 2.3.11 and later</compatibility>
592 <p>If authentication succeeds but authorization fails, Apache HTTPD will
593 respond with an HTTP response code of '401 UNAUTHORIZED' by default. This
594 usually causes browsers to display the password dialogue to the user
595 again, which is not wanted in all situations.
596 <directive>AuthzSendForbiddenOnFailure</directive> allows to change the
597 response code to '403 FORBIDDEN'.</p>
599 <note type="warning"><title>Security Warning</title>
600 <p>Modifying the response in case of missing authorization weakens the
601 security of the password, because it reveals to a possible attacker, that
602 his guessed password was right.</p>