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="logic"><title>Authorization Containers</title>
46 <p>The authorization container directives
47 <directive module="mod_authz_core" type="section">RequireAll</directive>,
48 <directive module="mod_authz_core" type="section">RequireAny</directive>
50 <directive module="mod_authz_core" type="section">RequireNone</directive>
51 may be combined with each other and with the
52 <directive module="mod_authz_core">Require</directive>
53 directive to express complex authorization logic.</p>
55 <p>The example below expresses the following authorization logic.
56 In order to access the resource, the user must either be the
57 <code>superadmin</code> user, or belong to both the
58 <code>admins</code> group and the <code>Administrators</code> LDAP
59 group and either belong to the <code>sales</code> group or
60 have the LDAP <code>dept</code> attribute <code>sales</code>.
61 Furthermore, in order to access the resource, the user must
62 not belong to either the <code>temps</code> group or the
63 LDAP group <code>Temporary Employees</code>.</p>
65 <highlight language="config">
66 <Directory /www/mydocs>
69 Require user superadmin
72 Require ldap-group cn=Administrators,o=Airius
75 Require ldap-attribute dept="sales"
81 Require ldap-group cn=Temporary Employees,o=Airius
88 <section id="requiredirectives"><title>The Require Directives</title>
90 <p><module>mod_authz_core</module> provides some generic authorization
91 providers which can be used with the
92 <directive module="mod_authz_core">Require</directive> directive.</p>
94 <section id="reqenv"><title>Require env</title>
96 <p>The <code>env</code> provider allows access to the server
97 to be controlled based on the existence of an <a
98 href="../env.html">environment variable</a>. When <code>Require
99 env <var>env-variable</var></code> is specified, then the request is
100 allowed access if the environment variable <var>env-variable</var>
101 exists. The server provides the ability to set environment
102 variables in a flexible way based on characteristics of the client
103 request using the directives provided by
104 <module>mod_setenvif</module>. Therefore, this directive can be
105 used to allow access based on such factors as the clients
106 <code>User-Agent</code> (browser type), <code>Referer</code>, or
107 other HTTP request header fields.</p>
109 <highlight language="config">
110 SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
111 <Directory /docroot>
112 Require env let_me_in
116 <p>In this case, browsers with a user-agent string beginning
117 with <code>KnockKnock/2.0</code> will be allowed access, and all
118 others will be denied.</p>
122 <section id="reqall"><title>Require all</title>
124 <p>The <code>all</code> provider mimics the functionality the
125 was previously provided by the 'Allow from all' and 'Deny from all'
126 directives. This provider can take one of two arguments which are
127 'granted' or 'denied'. The following examples will grant or deny
128 access to all requests.</p>
130 <highlight language="config">
134 <highlight language="config">
140 <section id="reqmethod"><title>Require method</title>
142 <p>The <code>method</code> provider allows to use the HTTP method in
143 authorization decisions. The GET and HEAD methods are treated as
144 equivalent. The TRACE method is not available to this provider,
145 use <directive module="core">TraceEnable</directive> instead.</p>
147 <p>The following example will only allow GET, HEAD, POST, and OPTIONS
150 <highlight language="config">
151 Require method GET POST OPTIONS
154 <p>The following example will allow GET, HEAD, POST, and OPTIONS
155 requests without authentication, and require a valid user for all other
158 <highlight language="config">
160 Require method GET POST OPTIONS
161 Require valid-user
167 <section id="reqexpr"><title>Require expr</title>
169 <p>The <code>expr</code> provider allows to base authorization
170 decisions on arbitrary expressions.</p>
172 <highlight language="config">
173 Require expr "%{TIME_HOUR} -ge 9 && %{TIME_HOUR} -le 17"
176 <p>The syntax is described in the <a href="../expr.html">ap_expr</a>
179 <p>Normally, the expression is evaluated before authentication. However, if
180 the expression returns false and references the variable
181 <code>%{REMOTE_USER}</code>, authentication will be performed and
182 the expression will be re-evaluated.</p>
191 <section id="authzalias"><title>Creating Authorization Provider Aliases</title>
193 <p>Extended authorization providers can be created within the configuration
194 file and assigned an alias name. The alias providers can then be referenced
195 through the <directive module="mod_authz_core">Require</directive> directive
196 in the same way as a base authorization provider. Besides the ability to
197 create and alias an extended provider, it also allows the same extended
198 authorization provider to be reference by multiple locations.
201 <section id="example"><title>Example</title>
202 <p>The example below creates two different ldap authorization provider
203 aliases based on the ldap-group authorization provider. This example
204 allows a single authorization location to check group membership within
208 <highlight language="config">
209 <AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
210 AuthLDAPBindDN cn=youruser,o=ctx
211 AuthLDAPBindPassword yourpassword
212 AuthLDAPURL ldap://ldap.host/o=ctx
213 </AuthzProviderAlias>
215 <AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev>
216 AuthLDAPBindDN cn=yourotheruser,o=dev
217 AuthLDAPBindPassword yourotherpassword
218 AuthLDAPURL ldap://other.ldap.host/o=dev?cn
219 </AuthzProviderAlias>
221 Alias /secure /webpages/secure
222 <Directory /webpages/secure>
225 AuthBasicProvider file
228 AuthName LDAP_Protected_Place
230 #implied OR operation
231 Require ldap-group-alias1
232 Require ldap-group-alias2
244 <description>Tests whether an authenticated user is authorized by
245 an authorization provider.</description>
246 <syntax>Require [not] <var>entity-name</var>
247 [<var>entity-name</var>] ...</syntax>
248 <contextlist><context>directory</context><context>.htaccess</context>
250 <override>AuthConfig</override>
253 <p>This directive tests whether an authenticated user is authorized
254 according to a particular authorization provider and the specified
255 restrictions. <module>mod_authz_core</module> provides the following
256 generic authorization providers:</p>
259 <dt><code>Require all granted</code></dt>
260 <dd>Access is allowed unconditionally.</dd>
262 <dt><code>Require all denied</code></dt>
263 <dd>Access is denied unconditionally.</dd>
265 <dt><code>Require env <var>env-var</var> [<var>env-var</var>]
267 <dd>Access is allowed only if one of the given environment variables is
270 <dt><code>Require method <var>http-method</var> [<var>http-method</var>]
272 <dd>Access is allowed only for the given HTTP methods.</dd>
274 <dt><code>Require expr <var>expression</var> </code></dt>
275 <dd>Access is allowed if <var>expression</var> evaluates to true.</dd>
278 <p>Some of the allowed syntaxes provided by <module>mod_authz_user</module>,
279 <module>mod_authz_host</module>,
280 and <module>mod_authz_groupfile</module> are:</p>
283 <dt><code>Require user <var>userid</var> [<var>userid</var>]
285 <dd>Only the named users can access the resource.</dd>
287 <dt><code>Require group <var>group-name</var> [<var>group-name</var>]
289 <dd>Only users in the named groups can access the resource.</dd>
291 <dt><code>Require valid-user</code></dt>
292 <dd>All valid users can access the resource.</dd>
294 <dt><code>Require ip 10 172.20 192.168.2</code></dt>
295 <dd>Clients in the specified IP address ranges can access the
299 <p>Other authorization modules that implement require options
300 include <module>mod_authnz_ldap</module>,
301 <module>mod_authz_dbm</module>, <module>mod_authz_dbd</module>,
302 <module>mod_authz_owner</module> and <module>mod_ssl</module>.</p>
304 <p>In most cases, for a complete authentication and authorization
305 configuration, <directive>Require</directive> must be accompanied by
306 <directive module="mod_authn_core">AuthName</directive>, <directive
307 module="mod_authn_core">AuthType</directive> and
308 <directive module="mod_auth_basic">AuthBasicProvider</directive> or
309 <directive module="mod_auth_digest">AuthDigestProvider</directive>
310 directives, and directives such as
311 <directive module="mod_authn_file">AuthUserFile</directive>
312 and <directive module="mod_authz_groupfile">AuthGroupFile</directive> (to
313 define users and groups) in order to work correctly. Example:</p>
315 <highlight language="config">
317 AuthName "Restricted Resource"
318 AuthBasicProvider file
319 AuthUserFile /web/users
320 AuthGroupFile /web/groups
324 <p>Access controls which are applied in this way are effective for
325 <strong>all</strong> methods. <strong>This is what is normally
326 desired.</strong> If you wish to apply access controls only to
327 specific methods, while leaving other methods unprotected, then
328 place the <directive>Require</directive> statement into a
329 <directive module="core" type="section">Limit</directive>
332 <p>The result of the <directive>Require</directive> directive
333 may be negated through the use of the
334 <code>not</code> option. As with the other negated authorization
335 directive <directive type="section">RequireNone</directive>,
336 when the <directive>Require</directive> directive is negated it can
337 only fail or return a neutral result, and therefore may never
338 independently authorize a request.</p>
340 <p>In the following example, all users in the <code>alpha</code>
341 and <code>beta</code> groups are authorized, except for those who
342 are also in the <code>reject</code> group.</p>
344 <highlight language="config">
345 <Directory /www/docs>
347 Require group alpha beta
348 Require not group reject
353 <p>When multiple <directive>Require</directive> directives are
355 <a href="../sections.html#merging">configuration section</a>
356 and are not contained in another authorization directive like
357 <directive module="mod_authz_core" type="section">RequireAll</directive>,
358 they are implicitly contained within a
359 <directive module="mod_authz_core" type="section">RequireAny</directive>
360 directive. Thus the first one to authorize a user authorizes the
361 entire request, and subsequent <directive>Require</directive> directives
364 <note type="warning"><title>Security Warning</title>
365 <p>Exercise caution when setting authorization directives in
366 <directive module="core">Location</directive> sections
367 that overlap with content served out of the filesystem.
368 By default, these <a href="../sections.html#merging"
369 >configuration sections</a> overwrite authorization configuration
370 in <directive module="core">Directory</directive>,
371 and <directive module="core">Files</directive> sections.</p>
372 <p>The <directive module="mod_authz_core">AuthMerging</directive> directive
373 can be used to control how authorization configuration sections are
378 <seealso><a href="../howto/access.html">Access Control howto</a></seealso>
379 <seealso><a href="#logic">Authorization Containers</a></seealso>
380 <seealso><module>mod_authn_core</module></seealso>
381 <seealso><module>mod_authz_host</module></seealso>
384 <directivesynopsis type="section">
385 <name>RequireAll</name>
386 <description>Enclose a group of authorization directives of which none
387 must fail and at least one must succeed for the enclosing directive to
388 succeed.</description>
389 <syntax><RequireAll> ... </RequireAll></syntax>
390 <contextlist><context>directory</context><context>.htaccess</context>
392 <override>AuthConfig</override>
395 <p><directive type="section">RequireAll</directive> and
396 <code></RequireAll></code> are used to enclose a group of
397 authorization directives of which none must fail and at least one
398 must succeed in order for
399 the <directive type="section">RequireAll</directive> directive to
402 <p>If none of the directives contained within the
403 <directive type="section">RequireAll</directive> directive fails,
404 and at least one succeeds, then the
405 <directive type="section">RequireAll</directive> directive
406 succeeds. If none succeed and none fail, then it returns a
407 neutral result. In all other cases, it fails.</p>
410 <seealso><a href="#logic">Authorization Containers</a></seealso>
411 <seealso><a href="../howto/auth.html">Authentication, Authorization,
412 and Access Control</a></seealso>
416 <directivesynopsis type="section">
417 <name>RequireAny</name>
418 <description>Enclose a group of authorization directives of which one
419 must succeed for the enclosing directive to succeed.</description>
420 <syntax><RequireAny> ... </RequireAny></syntax>
421 <contextlist><context>directory</context><context>.htaccess</context>
423 <override>AuthConfig</override>
426 <p><directive type="section">RequireAny</directive> and
427 <code></RequireAny></code> are used to enclose a group of
428 authorization directives of which one must succeed in order for
429 the <directive type="section">RequireAny</directive> directive to
432 <p>If one or more of the directives contained within the
433 <directive type="section">RequireAny</directive> directive succeed,
434 then the <directive type="section">RequireAny</directive> directive
435 succeeds. If none succeed and none fail, then it returns a
436 neutral result. In all other cases, it fails.</p>
438 <note>Because negated authorization directives are unable to
439 return a successful result, they can not significantly influence
440 the result of a <directive type="section">RequireAny</directive>
441 directive. (At most they could cause the directive to fail in
442 the case where they failed and all other directives returned a
443 neutral value.) Therefore negated authorization directives
444 are not permitted within a <directive type="section">RequireAny</directive>
448 <seealso><a href="#logic">Authorization Containers</a></seealso>
449 <seealso><a href="../howto/auth.html">Authentication, Authorization,
450 and Access Control</a></seealso>
454 <directivesynopsis type="section">
455 <name>RequireNone</name>
456 <description>Enclose a group of authorization directives of which none
457 must succeed for the enclosing directive to not fail.</description>
458 <syntax><RequireNone> ... </RequireNone></syntax>
459 <contextlist><context>directory</context><context>.htaccess</context>
461 <override>AuthConfig</override>
464 <p><directive type="section">RequireNone</directive> and
465 <code></RequireNone></code> are used to enclose a group of
466 authorization directives of which none must succeed
468 <directive type="section">RequireNone</directive> directive to
471 <p>If one or more of the directives contained within the
472 <directive type="section">RequireNone</directive> directive succeed,
473 then the <directive type="section">RequireNone</directive> directive
474 fails. In all other cases, it returns a neutral result. Thus as with
475 the other negated authorization directive <code>Require not</code>,
476 it can never independently
477 authorize a request because it can never return a successful result.
478 It can be used, however, to restrict the set of users who are
479 authorized to access a resource.</p>
481 <note>Because negated authorization directives are unable to
482 return a successful result, they can not significantly influence
483 the result of a <directive type="section">RequireNone</directive>
484 directive. Therefore negated authorization directives
485 are not permitted within a
486 <directive type="section">RequireNone</directive> directive.</note>
489 <seealso><a href="#logic">Authorization Containers</a></seealso>
490 <seealso><a href="../howto/auth.html">Authentication, Authorization,
491 and Access Control</a></seealso>
496 <name>AuthMerging</name>
497 <description>Controls the manner in which each configuration section's
498 authorization logic is combined with that of preceding configuration
499 sections.</description>
500 <syntax>AuthMerging Off | And | Or</syntax>
501 <default>AuthMerging Off</default>
502 <contextlist><context>directory</context><context>.htaccess</context>
504 <override>AuthConfig</override>
507 <p>When authorization is enabled, it is normally inherited by each
508 subsequent <a href="../sections.html#merging">configuration section</a>,
509 unless a different set of authorization directives are specified.
510 This is the default action, which corresponds to an explicit setting
511 of <code>AuthMerging Off</code>.</p>
513 <p>However, there may be circumstances in which is it desirable
514 for a configuration section's authorization to be combined with
515 that of its predecessor while configuration sections are being
516 merged. Two options are available for this case, <code>And</code>
517 and <code>Or</code>.</p>
519 <p>When a configuration section contains <code>AuthMerging And</code>
520 or <code>AuthMerging Or</code>,
521 its authorization logic is combined with that of the nearest
522 predecessor (according to the overall order of configuration sections)
523 which also contains authorization logic as if the two sections
524 were jointly contained within a
525 <directive module="mod_authz_core" type="section">RequireAll</directive> or
526 <directive module="mod_authz_core" type="section">RequireAny</directive>
527 directive, respectively.</p>
529 <note>The setting of <directive>AuthMerging</directive> is not
530 inherited outside of the configuration section in which it appears.
531 In the following example, only users belonging to group <code>alpha</code>
532 may access <code>/www/docs</code>. Users belonging to either
533 groups <code>alpha</code> or <code>beta</code> may access
534 <code>/www/docs/ab</code>. However, the default <code>Off</code>
535 setting of <directive>AuthMerging</directive> applies to the
536 <directive type="section" module="core">Directory</directive>
537 configuration section for <code>/www/docs/ab/gamma</code>, so
538 that section's authorization directives override those of the
539 preceding sections. Thus only users belong to the group
540 <code>gamma</code> may access <code>/www/docs/ab/gamma</code>.</note>
542 <highlight language="config">
543 <Directory /www/docs>
546 AuthBasicProvider file
547 AuthUserFile /usr/local/apache/passwd/passwords
551 <Directory /www/docs/ab>
556 <Directory /www/docs/ab/gamma>
564 <directivesynopsis type="section">
565 <name>AuthzProviderAlias</name>
566 <description>Enclose a group of directives that represent an
567 extension of a base authorization provider and referenced by the specified
569 <syntax><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>>
570 ... </AuthzProviderAlias>
572 <contextlist><context>server config</context>
576 <p><directive type="section">AuthzProviderAlias</directive> and
577 <code></AuthzProviderAlias></code> are used to enclose a group of
578 authorization directives that can be referenced by the alias name using the
579 directive <directive module="mod_authz_core">Require</directive>.</p>
585 <name>AuthzSendForbiddenOnFailure</name>
586 <description>Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if
587 authentication succeeds but authorization fails
589 <syntax>AuthzSendForbiddenOnFailure On|Off</syntax>
590 <default>AuthzSendForbiddenOnFailure Off</default>
591 <contextlist><context>directory</context><context>.htaccess</context>
593 <compatibility>Available in Apache HTTPD 2.3.11 and later</compatibility>
596 <p>If authentication succeeds but authorization fails, Apache HTTPD will
597 respond with an HTTP response code of '401 UNAUTHORIZED' by default. This
598 usually causes browsers to display the password dialogue to the user
599 again, which is not wanted in all situations.
600 <directive>AuthzSendForbiddenOnFailure</directive> allows to change the
601 response code to '403 FORBIDDEN'.</p>
603 <note type="warning"><title>Security Warning</title>
604 <p>Modifying the response in case of missing authorization weakens the
605 security of the password, because it reveals to a possible attacker, that
606 his guessed password was right.</p>