| <?xml version='1.0' encoding='UTF-8' ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <manualpage metafile="access.xml.meta"> |
| <parentdocument href="./">How-To / Tutorials</parentdocument> |
| |
| <title>Access Control</title> |
| |
| <summary> |
| <p>Access control refers to any means of controlling access to any |
| resource. This is separate from <a |
| href="auth.html">authentication and authorization</a>.</p> |
| </summary> |
| |
| <section id="related"><title>Related Modules and Directives</title> |
| |
| <p>Access control can be done by several different modules. The most |
| important of these are <module>mod_authz_core</module> and |
| <module>mod_authz_host</module>. Also discussed in this document |
| is access control using <module>mod_rewrite</module>.</p> |
| |
| </section> |
| |
| <section id="host"><title>Access control by host</title> |
| <p> |
| If you wish to restrict access to portions of your site based on the |
| host address of your visitors, this is most easily done using |
| <module>mod_authz_host</module>. |
| </p> |
| |
| <p>The <directive module="mod_authz_core">Require</directive> |
| provides a variety of different ways to allow or deny access to |
| resources. In conjunction with the <directive |
| module="mod_authz_core">RequireAll</directive>, <directive |
| module="mod_authz_core">RequireAny</directive>, and <directive |
| module="mod_authz_core">RequireNone</directive> directives, these |
| requirements may be combined in arbitrarily complex ways, to enforce |
| whatever your access policy happens to be.</p> |
| |
| <note type="warning"><p> |
| The <directive module="mod_access_compat">Allow</directive>, |
| <directive module="mod_access_compat">Deny</directive>, and |
| <directive module="mod_access_compat">Order</directive> directives, |
| provided by <module>mod_access_compat</module>, are deprecated and |
| will go away in a future version. You should avoid using them, and |
| avoid outdated tutorials recommending their use. |
| </p></note> |
| |
| <p>The usage of these directives is:</p> |
| |
| <highlight language="config"> |
| Require host address |
| Require ip ip.address |
| </highlight> |
| |
| <p>In the first form, <var>address</var> is a fully qualified |
| domain name (or a partial domain name); you may provide multiple |
| addresses or domain names, if desired.</p> |
| |
| <p>In the second form, <var>ip.address</var> is an IP address, a |
| partial IP address, a network/netmask pair, or a network/nnn CIDR |
| specification. Either IPv4 or IPv6 addresses may be used.</p> |
| |
| <p>See <a href="../mod/mod_authz_host.html#requiredirectives">the |
| mod_authz_host documentation</a> for further examples of this |
| syntax.</p> |
| |
| <p>You can insert <code>not</code> to negate a particular requirement. |
| Note, that since a <code>not</code> is a negation of a value, it cannot |
| be used by itself to allow or deny a request, as <em>not true</em> |
| does not constitute <em>false</em>. Thus, to deny a visit using a negation, |
| the block must have one element that evaluates as true or false. |
| For example, if you have someone spamming your message |
| board, and you want to keep them out, you could do the |
| following:</p> |
| |
| <highlight language="config"> |
| <RequireAll> |
| Require all granted |
| Require not ip 10.252.46.165 |
| </RequireAll> |
| </highlight> |
| |
| <p>Visitors coming from that address (<code>10.252.46.165</code>) |
| will not be able to see the content covered by this directive. If, |
| instead, you have a machine name, rather than an IP address, you |
| can use that.</p> |
| |
| <highlight language="config"> |
| Require not host <var>host.example.com</var> |
| </highlight> |
| |
| <p>And, if you'd like to block access from an entire domain, |
| you can specify just part of an address or domain name:</p> |
| |
| <highlight language="config"> |
| Require not ip 192.168.205 |
| Require not host phishers.example.com moreidiots.example |
| Require not host gov |
| </highlight> |
| |
| <p>Use of the <directive |
| module="mod_authz_core">RequireAll</directive>, <directive |
| module="mod_authz_core">RequireAny</directive>, and <directive |
| module="mod_authz_core">RequireNone</directive> directives may be |
| used to enforce more complex sets of requirements.</p> |
| |
| </section> |
| |
| <section id="env"><title>Access control by arbitrary variables</title> |
| |
| <p>Using the <directive type="section" module="core">If</directive>, |
| you can allow or deny access based on arbitrary environment |
| variables or request header values. For example, to deny access |
| based on user-agent (the browser type) you might do the |
| following:</p> |
| |
| <highlight language="config"> |
| <If "%{HTTP_USER_AGENT} == 'BadBot'"> |
| Require all denied |
| </If> |
| </highlight> |
| |
| <p>Using the <directive module="mod_authz_core">Require</directive> |
| <code>expr</code> syntax, this could also be written as:</p> |
| |
| |
| <highlight language="config"> |
| Require expr %{HTTP_USER_AGENT} != 'BadBot' |
| </highlight> |
| |
| <note><title>Warning:</title> |
| <p>Access control by <code>User-Agent</code> is an unreliable technique, |
| since the <code>User-Agent</code> header can be set to anything at all, |
| at the whim of the end user.</p> |
| </note> |
| |
| <p>See <a href="../expr.html">the expressions document</a> for a |
| further discussion of what expression syntaxes and variables are |
| available to you.</p> |
| |
| </section> |
| |
| <section id="rewrite"><title>Access control with mod_rewrite</title> |
| |
| <p>The <code>[F]</code> <directive |
| module="mod_rewrite">RewriteRule</directive> flag causes a 403 Forbidden |
| response to be sent. Using this, you can deny access to a resource based |
| on arbitrary criteria.</p> |
| |
| <p>For example, if you wish to block access to a resource between 8pm |
| and 7am, you can do this using <module>mod_rewrite</module>.</p> |
| |
| <highlight language="config"> |
| RewriteEngine On |
| RewriteCond "%{TIME_HOUR}" ">=20" [OR] |
| RewriteCond "%{TIME_HOUR}" "<07" |
| RewriteRule "^/fridge" "-" [F] |
| </highlight> |
| |
| <p>This will return a 403 Forbidden response for any request after 8pm |
| or before 7am. This technique can be used for any criteria that you wish |
| to check. You can also redirect, or otherwise rewrite these requests, if |
| that approach is preferred.</p> |
| |
| <p>The <directive type="section" module="core">If</directive> directive, |
| added in 2.4, replaces many things that <module>mod_rewrite</module> has |
| traditionally been used to do, and you should probably look there first |
| before resorting to mod_rewrite.</p> |
| |
| </section> |
| |
| <section id="moreinformation"><title>More information</title> |
| |
| <p>The <a href="../expr.html">expression engine</a> gives you a |
| great deal of power to do a variety of things based on arbitrary |
| server variables, and you should consult that document for more |
| detail.</p> |
| |
| <p>Also, you should read the <module>mod_authz_core</module> |
| documentation for examples of combining multiple access requirements |
| and specifying how they interact.</p> |
| |
| <p>See also the <a href="auth.html">Authentication and Authorization</a> |
| howto.</p> |
| </section> |
| |
| </manualpage> |