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} >= 9 && %{TIME_HOUR} <= 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#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
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>
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><RequireAll> ... </RequireAll></syntax>
373 <contextlist><context>directory</context><context>.htaccess</context>
375 <override>AuthConfig</override>
378 <p><directive type="section">RequireAll</directive> and
379 <code></RequireAll></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
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>
393 <seealso><a href="#logic">Authorization Containers</a></seealso>
394 <seealso><a href="../howto/auth.html">Authentication, Authorization,
395 and Access Control</a></seealso>
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><RequireAny> ... </RequireAny></syntax>
404 <contextlist><context>directory</context><context>.htaccess</context>
406 <override>AuthConfig</override>
409 <p><directive type="section">RequireAny</directive> and
410 <code></RequireAny></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
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>
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>
431 <seealso><a href="#logic">Authorization Containers</a></seealso>
432 <seealso><a href="../howto/auth.html">Authentication, Authorization,
433 and Access Control</a></seealso>
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><RequireNone> ... </RequireNone></syntax>
442 <contextlist><context>directory</context><context>.htaccess</context>
444 <override>AuthConfig</override>
447 <p><directive type="section">RequireNone</directive> and
448 <code></RequireNone></code> are used to enclose a group of
449 authorization directives of which none must succeed
451 <directive type="section">RequireNone</directive> directive to
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>
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>
472 <seealso><a href="#logic">Authorization Containers</a></seealso>
473 <seealso><a href="../howto/auth.html">Authentication, Authorization,
474 and Access Control</a></seealso>
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>
487 <override>AuthConfig</override>
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>
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>
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>
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>
525 <highlight language="config">
526 <Directory /www/docs>
529 AuthBasicProvider file
530 AuthUserFile /usr/local/apache/passwd/passwords
534 <Directory /www/docs/ab>
539 <Directory /www/docs/ab/gamma>
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
552 <syntax><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>>
553 ... </AuthzProviderAlias>
555 <contextlist><context>server config</context>
559 <p><directive type="section">AuthzProviderAlias</directive> and
560 <code></AuthzProviderAlias></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>
568 <name>AuthzSendForbiddenOnFailure</name>
569 <description>Send '403 FORBIDDEN' instead of '401 UNAUTHORIZED' if
570 authentication succeeds but authorization fails
572 <syntax>AuthzSendForbiddenOnFailure On|Off</syntax>
573 <default>AuthzSendForbiddenOnFailure Off</default>
574 <contextlist><context>directory</context><context>.htaccess</context>
576 <compatibility>Available in Apache HTTPD 2.3.11 and later</compatibility>
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>
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>