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 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> and
49 <directive module="mod_authz_core">Match</directive> directives
50 in the same way as a base authorization provider. Besides the ability to
51 create and alias an extended provider, it also allows the same extended
52 authorization provider to be reference by multiple locations.
55 <section id="example"><title>Example</title>
56 <p>The example below creates two different ldap authorization provider
57 aliases based on the ldap-group authorization provider. This example
58 allows a single authorization location to check group membership within
62 <example><title>Example</title>
63 <AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx><br />
65 AuthLDAPBindDN cn=youruser,o=ctx<br />
66 AuthLDAPBindPassword yourpassword<br />
67 AuthLDAPURL ldap://ldap.host/o=ctx<br />
69 </AuthzProviderAlias><br /><br />
70 <AuthzProviderAlias ldap-group ldap-group-alias2
71 cn=my-other-group,o=dev><br />
73 AuthLDAPBindDN cn=yourotheruser,o=dev<br />
74 AuthLDAPBindPassword yourotherpassword<br />
75 AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br />
77 </AuthzProviderAlias><br /><br />
79 Alias /secure /webpages/secure<br />
80 <Directory /webpages/secure><br />
82 Order deny,allow<br />
83 Allow from all<br /><br />
85 AuthBasicProvider file<br /><br />
88 AuthName LDAP_Protected_Place<br /><br />
90 #implied OR operation<br />
91 Require alias1-ldap-group<br />
92 Require alias2-ldap-group<br />
93 </indent> </Directory><br />
99 <section id="logic"><title>Authorization Containers</title>
101 <p>The authorization container directives
102 <directive module="mod_authz_core" type="section">MatchAll</directive>,
103 <directive module="mod_authz_core" type="section">MatchAny</directive>,
104 <directive module="mod_authz_core" type="section">MatchNotAll</directive>
106 <directive module="mod_authz_core" type="section">MatchNotAny</directive>
107 may be combined with each other and with the
108 <directive module="mod_authz_core">Match</directive>
109 directive to express complex authorization logic.</p>
111 <p>The example below expresses the following authorization logic.
112 In order to access the resource, the user must either be the
113 <code>superadmin</code> user, or belong to both the
114 <code>admins</code> group and the <code>Administrators</code> LDAP
115 group and either belong to the <code>sales</code> group or
116 have the LDAP <code>dept</code> attribute <code>sales</code>.
117 Furthermore, in order to access the resource, the user must
118 not belong to either the <code>temps</code> group or the
119 LDAP group <code>Temporary Employees</code>.</p>
122 <Directory /www/mydocs>
126 Match user superadmin<br />
129 Match group admins<br />
130 Match ldap-group cn=Administrators,o=Airius<br />
133 Match group sales<br />
134 Match ldap-attribute dept="sales"
140 </MatchAny><br />
143 Match group temps<br />
144 Match ldap-group cn=Temporary Employees,o=Airius
154 <description>Tests whether an authenticated user is authorized by
155 an authorization provider.</description>
156 <syntax>Require <var>entity-name</var> [<var>entity-name</var>] ...</syntax>
157 <contextlist><context>directory</context><context>.htaccess</context>
159 <override>AuthConfig</override>
162 <p>This directive tests whether an authenticated user is authorized
163 according to a particular authorization provider and the specified
164 restrictions. Some of the allowed syntaxes provided by
165 <module>mod_authz_user</module> and
166 <module>mod_authz_groupfile</module> are:</p>
169 <dt><code>Require user <var>userid</var> [<var>userid</var>]
171 <dd>Only the named users can access the resource.</dd>
173 <dt><code>Require group <var>group-name</var> [<var>group-name</var>]
175 <dd>Only users in the named groups can access the resource.</dd>
177 <dt><code>Require valid-user</code></dt>
178 <dd>All valid users can access the resource.</dd>
181 <p>Other authorization modules that implement require options
182 include <module>mod_authnz_ldap</module>,
183 <module>mod_authz_dbm</module>, <module>mod_authz_dbd</module>,
184 <module>mod_authz_host</module>, and
185 <module>mod_authz_owner</module>.</p>
187 <p>For a complete authentication and authorization configuration,
188 <directive>Require</directive> must be accompanied by
189 <directive module="mod_authn_core">AuthName</directive>, <directive
190 module="mod_authn_core">AuthType</directive> and
191 <directive module="mod_auth_basic">AuthBasicProvider</directive> or
192 <directive module="mod_auth_digest">AuthDigestProvider</directive>
193 directives, and directives such as
194 <directive module="mod_authn_file">AuthUserFile</directive>
195 and <directive module="mod_authz_groupfile">AuthGroupFile</directive> (to
196 define users and groups) in order to work correctly. Example:</p>
200 AuthName "Restricted Resource"<br />
201 AuthBasicProvider file<br />
202 AuthUserFile /web/users<br />
203 AuthGroupFile /web/groups<br />
207 <p>Access controls which are applied in this way are effective for
208 <strong>all</strong> methods. <strong>This is what is normally
209 desired.</strong> If you wish to apply access controls only to
210 specific methods, while leaving other methods unprotected, then
211 place the <directive>Require</directive> statement into a
212 <directive module="core" type="section">Limit</directive>
215 <p>When multiple <directive>Require</directive> directives are
217 <a href="../sections.html#mergin">configuration section</a>,
218 the first one to authorize a user authorizes the entire request,
219 and subsequent <directive>Require</directive> directives are
220 ignored. In other words, all <directive>Require</directive> directives
221 are enclosed in an implied <directive module="mod_authz_core"
222 type="section">MatchAny</directive> directive.</p>
224 <note><directive>Require</directive> directives may not be combined
225 with the <directive module="mod_authz_core">Match</directive> directive
226 or any authorization container directives, such as
227 <directive module="mod_authz_core"
228 type="section">MatchAll</directive>.</note>
231 <seealso><a href="../howto/auth.html">Authentication, Authorization,
232 and Access Control</a></seealso>
233 <seealso><module>mod_authn_core</module></seealso>
234 <seealso><module>mod_authz_host</module></seealso>
239 <description>Tests whether an authenticated user is authorized by
240 an authorization provider.</description>
241 <syntax>Match [not] <var>entity-name</var>
242 [<var>entity-name</var>] ...</syntax>
243 <contextlist><context>directory</context><context>.htaccess</context>
245 <override>AuthConfig</override>
248 <p>This directive is similar to the
249 <directive module="mod_authz_core">Require</directive> directive;
250 it tests whether an authenticated user is authorized according to
251 a particular authorization provider and the specified restrictions.</p>
253 <p>Unlike the <directive module="mod_authz_core">Require</directive>
254 directive, it may be used with and inside authorization container
256 <directive module="mod_authz_core" type="section">MatchAll</directive>.</p>
258 <p>Furthermore, its result may be negated through the use of the
259 <code>not</code> option. As with other negated authorization directives,
260 in this case the <directive>Match</directive> directive may only
261 either fail or return a neutral result, and can therefore never
262 independently authorize a request.</p>
264 <p>In the following example, all users in the <code>alpha</code>
265 and <code>beta</code> groups are authorized, except for those who
266 are also in the <code>reject</code> group.</p>
269 <Directory /www/docs>
271 Match group alpha beta<br />
272 Match not group reject
277 <p>When multiple <directive>Match</directive> directives are
279 <a href="../sections.html#mergin">configuration section</a>
280 and are not contained in another authorization directive like
281 <directive module="mod_authz_core" type="section">MatchAny</directive>,
282 they are implicitly contained within a
283 <directive module="mod_authz_core" type="section">MatchAll</directive>
284 directive. Thus for the user to be authorized, all such
285 <directive>Match</directive> directives must not fail, and
286 at least one must be successful.</p>
288 <note><directive>Match</directive> directives may not be combined
289 with the <directive module="mod_authz_core">Require</directive>
293 <seealso><directive module="mod_authz_core">Require</directive></seealso>
294 <seealso><a href="#logic">Authorization Containers</a></seealso>
295 <seealso><a href="../howto/auth.html">Authentication, Authorization,
296 and Access Control</a></seealso>
299 <directivesynopsis type="section">
300 <name>MatchAll</name>
301 <description>Enclose a group of authorization directives of which none
302 must fail and at least one must succeed for the enclosing directive to
303 succeed.</description>
304 <syntax><MatchAll>
305 ... </MatchAll></syntax>
306 <contextlist><context>directory</context><context>.htaccess</context>
308 <override>AuthConfig</override>
311 <p><directive type="section">MatchAll</directive> and
312 <code></MatchAll></code> are used to enclose a group of
313 authorization directives of which none must fail and at least one
314 must succeed in order for
315 the <directive type="section">MatchAll</directive> directive to
318 <p>If none of the directives contained within the
319 <directive type="section">MatchAll</directive> directive fails,
320 and at least one succeeds, then the
321 <directive type="section">MatchAll</directive> directive
322 succeeds. If none succeed and none fail, then it returns a
323 neutral result. In all other cases, it fails.</p>
326 <seealso><a href="#logic">Authorization Containers</a></seealso>
327 <seealso><a href="../howto/auth.html">Authentication, Authorization,
328 and Access Control</a></seealso>
332 <directivesynopsis type="section">
333 <name>MatchAny</name>
334 <description>Enclose a group of authorization directives of which one
335 must succeed for the enclosing directive to succeed.</description>
336 <syntax><MatchAny>
337 ... </MatchAny></syntax>
338 <contextlist><context>directory</context><context>.htaccess</context>
340 <override>AuthConfig</override>
343 <p><directive type="section">MatchAny</directive> and
344 <code></MatchAny></code> are used to enclose a group of
345 authorization directives of which one must succeed in order for
346 the <directive type="section">MatchAny</directive> directive to
349 <p>If one or more of the directives contained within the
350 <directive type="section">MatchAny</directive> directive succeed,
351 then the <directive type="section">MatchAny</directive> directive
352 succeeds. If none succeed and none fail, then it returns a
353 neutral result. In all other cases, it fails.</p>
355 <note>Because negated authorization directives are unable to
356 return a successful result, they can not significantly influence
357 the result of a <directive type="section">MatchAny</directive>
358 directive. (At most they could cause the directive to fail in
359 the case where they failed and all other directives returned a
360 neutral value.) Therefore negated authorization directives
361 are not permitted within a <directive type="section">MatchAny</directive>
365 <seealso><a href="#logic">Authorization Containers</a></seealso>
366 <seealso><a href="../howto/auth.html">Authentication, Authorization,
367 and Access Control</a></seealso>
371 <directivesynopsis type="section">
372 <name>MatchNotAll</name>
373 <description>Enclose a group of authorization directives of which some
374 must fail or none must succeed for the enclosing directive to
375 not fail.</description>
376 <syntax><MatchNotAll>
377 ... </MatchNotAll></syntax>
378 <contextlist><context>directory</context><context>.htaccess</context>
380 <override>AuthConfig</override>
383 <p><directive type="section">MatchNotAll</directive> and
384 <code></MatchNotAll></code> are used to enclose a group of
385 authorization directives of which some must fail or none must succeed
387 <directive type="section">MatchNotAll</directive> directive to
390 <p>If none of the directives contained within the
391 <directive type="section">MatchNotAll</directive> directive
392 fail, and one or more succeed, then the
393 <directive type="section">MatchNotAll</directive> directive fails.
394 In all other cases, it returns a neutral result. Thus as with
395 the other negated authorization directives, it can never independently
396 authorize a request because it can never return a successful result.
397 It can be used, however, to restrict the set of users who are
398 authorized to access a resource.</p>
401 <seealso><a href="#logic">Authorization Containers</a></seealso>
402 <seealso><a href="../howto/auth.html">Authentication, Authorization,
403 and Access Control</a></seealso>
407 <directivesynopsis type="section">
408 <name>MatchNotAny</name>
409 <description>Enclose a group of authorization directives of which none
410 none must succeed for the enclosing directive to not fail.</description>
411 <syntax><MatchNotAny>
412 ... </MatchNotAny></syntax>
413 <contextlist><context>directory</context><context>.htaccess</context>
415 <override>AuthConfig</override>
418 <p><directive type="section">MatchNotAny</directive> and
419 <code></MatchNotAny></code> are used to enclose a group of
420 authorization directives of which none must succeed
422 <directive type="section">MatchNotAny</directive> directive to
425 <p>If one or more of the directives contained within the
426 <directive type="section">MatchNotAny</directive> directive succeed,
427 then the <directive type="section">MatchNotAny</directive> directive
428 fails. In all other cases, it returns a neutral result. Thus as with
429 the other negated authorization directives, it can never independently
430 authorize a request because it can never return a successful result.
431 It can be used, however, to restrict the set of users who are
432 authorized to access a resource.</p>
434 <note>Because negated authorization directives are unable to
435 return a successful result, they can not significantly influence
436 the result of a <directive type="section">MatchNotAny</directive>
437 directive. Therefore negated authorization directives
438 are not permitted within a
439 <directive type="section">MatchNotAny</directive> directive.</note>
442 <seealso><a href="#logic">Authorization Containers</a></seealso>
443 <seealso><a href="../howto/auth.html">Authentication, Authorization,
444 and Access Control</a></seealso>
449 <name>MergeAuthz</name>
450 <description>Controls the manner in which each configuration section's
451 authorization logic is combined with that of preceding configuration
452 sections.</description>
453 <syntax>MergeAuthz Off | MatchAll | MatchAny</syntax>
454 <default>MergeAuthz Off</default>
455 <contextlist><context>directory</context><context>.htaccess</context>
457 <override>AuthConfig</override>
460 <p>When authorization is enabled, it is normally inherited by each
461 subsequent <a href="../sections.html#mergin">configuration section</a>,
462 unless a different set of authorization directives are specified.
463 This is the default action, which corresponds to an explicit setting
464 of <code>MergeAuthz Off</code>.</p>
466 <p>However, there may be circumstances in which is it desirable
467 for a configuration section's authorization to be combined with
468 that of its predecessor while configuration sections are being
469 merged. Two options are available for this case, <code>MatchAll</code>
470 and <code>MatchAny</code>.</p>
472 <p>When a configuration section contains <code>AuthzMerge MatchAll</code>
473 or <code>AuthzMerge MatchAny</code>,
474 its authorization logic is combined with that of the nearest
475 predecessor (according to the overall order of configuration sections)
476 which also contains authorization logic as if the two sections
477 were jointly contained within a
478 <directive module="mod_authz_core" type="section">MatchAll</directive> or
479 <directive module="mod_authz_core" type="section">MatchAny</directive>
480 directive, respectively.</p>
482 <note>The setting of <directive>AuthzMerge</directive> is not
483 inherited outside of the configuration section in which it appears.
484 In the following example, only users belonging to group <code>alpha</code>
485 may access <code>/www/docs</code>. Users belonging to either
486 groups <code>alpha</code> or <code>beta</code> may access
487 <code>/www/docs/ab</code>. However, the default <code>Off</code>
488 setting of <directive>AuthzMerge</directive> applies to the
489 <directive type="section" module="core">Directory</directive>
490 configuration section for <code>/www/docs/ab/gamma</code>, so
491 that section's authorization directives override those of the
492 preceding sections. Thus only users belong to the group
493 <code>gamma</code> may access <code>/www/docs/ab/gamma</code>.</note>
496 <Directory /www/docs>
499 AuthName Documents<br />
500 AuthBasicProvider file<br />
501 AuthUserFile /usr/local/apache/passwd/passwords<br />
504 </Directory><br />
506 <Directory /www/docs/ab>
508 AuthzMerge MatchAny<br />
511 </Directory><br />
513 <Directory /www/docs/ab/gamma>
523 <directivesynopsis type="section">
524 <name>AuthzProviderAlias</name>
525 <description>Enclose a group of directives that represent an
526 extension of a base authorization provider and referenced by the specified
528 <syntax><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>>
529 ... </AuthzProviderAlias>
531 <contextlist><context>server config</context>
535 <p><directive type="section">AuthzProviderAlias</directive> and
536 <code></AuthzProviderAlias></code> are used to enclose a group of
537 authorization directives that can be referenced by the alias name using the
538 directive <directive module="mod_authz_core">Require</directive>.</p>