granicus.if.org Git - apache/blob - docs/manual/mod/mod_authn_core.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   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
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  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.
  21 -->
  22
  23 <modulesynopsis metafile="mod_authn_core.xml.meta">
  24
  25 <name>mod_authn_core</name>
  26 <description>Core Authentication</description>
  27 <status>Base</status>
  28 <sourcefile>mod_authn_core.c</sourcefile>
  29 <identifier>authn_core_module</identifier>
  30 <compatibility>Available in Apache 2.3 and later</compatibility>
  31
  32 <summary>
  33     <p>This module provides core authentication capabilities to
  34     allow or deny access to portions of the web site.
  35     <module>mod_authn_core</module> provides directives that are
  36     common to all authentication providers.</p>
  37 </summary>
  38
  39 <section id="authnalias"><title>Creating Authentication Provider Aliases</title>
  40
  41     <p>Extended authentication providers can be created
  42     within the configuration file and assigned an alias name.  The alias
  43     providers can then be referenced through the directives
  44     <directive module="mod_auth_basic">AuthBasicProvider</directive> or
  45     <directive module="mod_auth_digest">AuthDigestProvider</directive> in
  46     the same way as a base authentication provider.  Besides the ability
  47     to create and alias an extended provider, it also allows the same
  48     extended authentication provider to be reference by multiple
  49     locations.</p>
  50
  51     <section id="example"><title>Examples</title>
  52
  53         <p>This example checks for passwords in two different text
  54         files.</p>
  55
  56         <example><title>Checking multiple text password files</title>
  57         <highlight language="config">
  58 # Check here first
  59 &lt;AuthnProviderAlias file file1&gt;
  60     AuthUserFile "/www/conf/passwords1"
  61 &lt;/AuthnProviderAlias&gt;
  62
  63 # Then check here
  64 &lt;AuthnProviderAlias file file2&gt;
  65     AuthUserFile "/www/conf/passwords2"
  66 &lt;/AuthnProviderAlias&gt;
  67
  68 &lt;Directory "/var/web/pages/secure"&gt;
  69     AuthBasicProvider file1 file2
  70
  71     AuthType Basic
  72     AuthName "Protected Area"
  73     Require valid-user
  74 &lt;/Directory&gt;
  75         </highlight>
  76         </example>
  77
  78         <p>The example below creates two different ldap authentication
  79         provider aliases based on the ldap provider.  This allows
  80         a single authenticated location to be serviced by multiple ldap
  81         hosts:</p>
  82
  83         <example><title>Checking multiple LDAP servers</title>
  84         <highlight language="config">
  85 &lt;AuthnProviderAlias ldap ldap-alias1&gt;
  86     AuthLDAPBindDN "cn=youruser,o=ctx"
  87     AuthLDAPBindPassword yourpassword
  88     AuthLDAPURL "ldap://ldap.host/o=ctx"
  89 &lt;/AuthnProviderAlias&gt;
  90 &lt;AuthnProviderAlias ldap ldap-other-alias&gt;
  91     AuthLDAPBindDN "cn=yourotheruser,o=dev"
  92     AuthLDAPBindPassword yourotherpassword
  93     AuthLDAPURL "ldap://other.ldap.host/o=dev?cn"
  94 &lt;/AuthnProviderAlias&gt;
  95
  96 Alias "/secure" "/webpages/secure"
  97 &lt;Directory "/webpages/secure"&gt;
  98     AuthBasicProvider ldap-other-alias  ldap-alias1
  99
 100     AuthType Basic
 101     AuthName "LDAP Protected Place"
 102     Require valid-user
 103     # Note that Require ldap-* would not work here, since the
 104     # AuthnProviderAlias does not provide the config to authorization providers
 105     # that are implemented in the same module as the authentication provider.
 106 &lt;/Directory&gt;
 107           </highlight>
 108         </example>
 109     </section>
 110
 111 </section>
 112
 113
 114 <directivesynopsis>
 115 <name>AuthName</name>
 116 <description>Authorization realm for use in HTTP
 117 authentication</description>
 118 <syntax>AuthName <var>auth-domain</var></syntax>
 119 <contextlist><context>directory</context><context>.htaccess</context>
 120 </contextlist>
 121 <override>AuthConfig</override>
 122
 123 <usage>
 124     <p>This directive sets the name of the authorization realm for a
 125     directory. This realm is given to the client so that the user
 126     knows which username and password to send.
 127     <directive>AuthName</directive> takes a single argument; if the
 128     realm name contains spaces, it must be enclosed in quotation
 129     marks.  It must be accompanied by <directive
 130     module="mod_authn_core">AuthType</directive> and <directive
 131     module="mod_authz_core">Require</directive> directives, and directives such
 132     as <directive module="mod_authn_file">AuthUserFile</directive> and
 133     <directive module="mod_authz_groupfile">AuthGroupFile</directive> to
 134     work.</p>
 135
 136    <p>For example:</p>
 137
 138    <highlight language="config">
 139      AuthName "Top Secret"
 140    </highlight>
 141
 142     <p>The string provided for the <code>AuthName</code> is what will
 143     appear in the password dialog provided by most browsers.</p>
 144
 145     <p>From 2.4.13, <a href="../expr.html">expression syntax</a> can be
 146     used inside the directive to produce the name dynamically.</p>
 147
 148    <p>For example:</p>
 149
 150    <highlight language="config">
 151      AuthName "%{HTTP_HOST}"
 152    </highlight>
 153
 154 </usage>
 155 <seealso><a
 156     href="../howto/auth.html">Authentication, Authorization, and
 157     Access Control</a></seealso>
 158 <seealso><module>mod_authz_core</module></seealso>
 159 </directivesynopsis>
 160
 161 <directivesynopsis>
 162 <name>AuthType</name>
 163 <description>Type of user authentication</description>
 164 <syntax>AuthType None|Basic|Digest|Form</syntax>
 165 <contextlist><context>directory</context><context>.htaccess</context>
 166 </contextlist>
 167 <override>AuthConfig</override>
 168
 169 <usage>
 170     <p>This directive selects the type of user authentication for a
 171     directory. The authentication types available are <code>None</code>,
 172     <code>Basic</code> (implemented by
 173     <module>mod_auth_basic</module>), <code>Digest</code>
 174     (implemented by <module>mod_auth_digest</module>), and
 175     <code>Form</code> (implemented by <module>mod_auth_form</module>).</p>
 176
 177     <p>To implement authentication, you must also use the <directive
 178     module="mod_authn_core">AuthName</directive> and <directive
 179     module="mod_authz_core">Require</directive> directives.  In addition, the
 180     server must have an authentication-provider module such as
 181     <module>mod_authn_file</module> and an authorization module such
 182     as <module>mod_authz_user</module>.</p>
 183
 184     <p>The authentication type <code>None</code> disables authentication.
 185     When authentication is enabled, it is normally inherited by each
 186     subsequent <a href="../sections.html#mergin">configuration section</a>,
 187     unless a different authentication type is specified.  If no
 188     authentication is desired for a subsection of an authenticated
 189     section, the authentication type <code>None</code> may be used;
 190     in the following example, clients may access the
 191     <code>/www/docs/public</code> directory without authenticating:</p>
 192
 193     <highlight language="config">
 194 &lt;Directory "/www/docs"&gt;
 195     AuthType Basic
 196     AuthName Documents
 197     AuthBasicProvider file
 198     AuthUserFile "/usr/local/apache/passwd/passwords"
 199     Require valid-user
 200 &lt;/Directory&gt;
 201
 202 &lt;Directory "/www/docs/public"&gt;
 203     AuthType None
 204     Require all granted
 205 &lt;/Directory&gt;
 206     </highlight>
 207
 208     <p>From 2.4.13, <a href="../expr.html">expression syntax</a> can be
 209     used inside the directive to specify the type dynamically.</p>
 210
 211     <note>When disabling authentication, note that clients which have
 212     already authenticated against another portion of the server's document
 213     tree will typically continue to send authentication HTTP headers
 214     or cookies with each request, regardless of whether the server
 215     actually requires authentication for every resource.</note>
 216 </usage>
 217
 218 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 219     and Access Control</a></seealso>
 220 </directivesynopsis>
 221
 222 <directivesynopsis type="section">
 223 <name>AuthnProviderAlias</name>
 224 <description>Enclose a group of directives that represent an
 225 extension of a base authentication provider and referenced by
 226 the specified alias</description>
 227 <syntax>&lt;AuthnProviderAlias <var>baseProvider Alias</var>&gt;
 228 ... &lt;/AuthnProviderAlias&gt;</syntax>
 229 <contextlist><context>server config</context>
 230 </contextlist>
 231
 232 <usage>
 233     <p><code>&lt;AuthnProviderAlias&gt;</code> and
 234     <code>&lt;/AuthnProviderAlias&gt;</code> are used to enclose a group of
 235     authentication directives that can be referenced by the alias name
 236     using one of the directives <directive module="mod_auth_basic">
 237     AuthBasicProvider</directive> or <directive module="mod_auth_digest">
 238     AuthDigestProvider</directive>.</p>
 239
 240     <note>This directive has no affect on authorization, even for modules that
 241     provide both authentication and authorization.</note>
 242 </usage>
 243 </directivesynopsis>
 244
 245 </modulesynopsis>