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
  58         # Check here first<br />
  59         &lt;AuthnProviderAlias file file1&gt;<br />
  60         <indent>
  61             AuthUserFile /www/conf/passwords1<br />
  62         </indent>
  63         &lt;/AuthnProviderAlias&gt;<br />
  64         <br />
  65         # Then check here<br />
  66         &lt;AuthnProviderAlias file file2&gt;   <br />
  67         <indent>
  68             AuthUserFile /www/conf/passwords2<br />
  69         </indent>
  70         &lt;/AuthnProviderAlias&gt;<br />
  71         <br />
  72         &lt;Directory /var/web/pages/secure&gt;<br />
  73         <indent>
  74             AuthBasicProvider file1 file2<br />
  75             <br />
  76             AuthType Basic<br />
  77             AuthName "Protected Area"<br />
  78             Require valid-user<br />
  79         </indent>
  80         &lt;/Directory&gt;<br />
  81         </example>
  82
  83         <p>The example below creates two different ldap authentication
  84         provider aliases based on the ldap provider.  This allows
  85         a single authenticated location to be serviced by multiple ldap
  86         hosts:</p>
  87
  88         <example><title>Checking multiple LDAP servers</title>
  89           &lt;AuthnProviderAlias ldap ldap-alias1&gt;<br />
  90           <indent>
  91              AuthLDAPBindDN cn=youruser,o=ctx<br />
  92              AuthLDAPBindPassword yourpassword<br />
  93              AuthLDAPURL ldap://ldap.host/o=ctx<br />
  94           </indent>
  95           &lt;/AuthnProviderAlias&gt;<br /><br />
  96           &lt;AuthnProviderAlias ldap ldap-other-alias&gt;<br />
  97           <indent>
  98              AuthLDAPBindDN cn=yourotheruser,o=dev<br />
  99              AuthLDAPBindPassword yourotherpassword<br />
 100              AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br />
 101           </indent>
 102           &lt;/AuthnProviderAlias&gt;<br /><br />
 103
 104           Alias /secure /webpages/secure<br />
 105           &lt;Directory /webpages/secure&gt;<br />
 106           <indent>
 107              Order deny,allow<br />
 108              Allow from all<br /><br />
 109
 110              AuthBasicProvider ldap-other-alias  ldap-alias1<br /><br />
 111
 112              AuthType Basic<br />
 113              AuthName LDAP_Protected_Place<br />
 114              Require valid-user<br />
 115           </indent>
 116           &lt;/Directory&gt;<br />
 117         </example>
 118     </section>
 119
 120 </section>
 121
 122
 123 <directivesynopsis>
 124 <name>AuthName</name>
 125 <description>Authorization realm for use in HTTP
 126 authentication</description>
 127 <syntax>AuthName <var>auth-domain</var></syntax>
 128 <contextlist><context>directory</context><context>.htaccess</context>
 129 </contextlist>
 130 <override>AuthConfig</override>
 131
 132 <usage>
 133     <p>This directive sets the name of the authorization realm for a
 134     directory. This realm is given to the client so that the user
 135     knows which username and password to send.
 136     <directive>AuthName</directive> takes a single argument; if the
 137     realm name contains spaces, it must be enclosed in quotation
 138     marks.  It must be accompanied by <directive
 139     module="mod_authn_core">AuthType</directive> and <directive
 140     module="mod_authz_core">Require</directive> directives, and directives such
 141     as <directive module="mod_authn_file">AuthUserFile</directive> and
 142     <directive module="mod_authz_groupfile">AuthGroupFile</directive> to
 143     work.</p>
 144
 145    <p>For example:</p>
 146
 147    <example>
 148      AuthName "Top Secret"
 149    </example>
 150
 151     <p>The string provided for the <code>AuthName</code> is what will
 152     appear in the password dialog provided by most browsers.</p>
 153 </usage>
 154 <seealso><a
 155     href="../howto/auth.html">Authentication, Authorization, and
 156     Access Control</a></seealso>
 157 <seealso><module>mod_authz_core</module></seealso>
 158 </directivesynopsis>
 159
 160 <directivesynopsis>
 161 <name>AuthType</name>
 162 <description>Type of user authentication</description>
 163 <syntax>AuthType None|Basic|Digest|Form</syntax>
 164 <contextlist><context>directory</context><context>.htaccess</context>
 165 </contextlist>
 166 <override>AuthConfig</override>
 167
 168 <usage>
 169     <p>This directive selects the type of user authentication for a
 170     directory. The authentication types available are <code>None</code>,
 171     <code>Basic</code> (implemented by
 172     <module>mod_auth_basic</module>), <code>Digest</code>
 173     (implemented by <module>mod_auth_digest</module>), and
 174     <code>Form</code> (implemented by <module>mod_auth_form</module>).</p>
 175
 176     <p>To implement authentication, you must also use the <directive
 177     module="mod_authn_core">AuthName</directive> and <directive
 178     module="mod_authz_core">Require</directive> directives.  In addition, the
 179     server must have an authentication-provider module such as
 180     <module>mod_authn_file</module> and an authorization module such
 181     as <module>mod_authz_user</module>.</p>
 182
 183     <p>The authentication type <code>None</code> disables authentication.
 184     When authentication is enabled, it is normally inherited by each
 185     subsequent <a href="../sections.html#mergin">configuration section</a>,
 186     unless a different authentication type is specified.  If no
 187     authentication is desired for a subsection of an authenticated
 188     section, the authentication type <code>None</code> may be used;
 189     in the following example, clients may access the
 190     <code>/www/docs/public</code> directory without authenticating:</p>
 191
 192     <example>
 193         &lt;Directory /www/docs&gt;
 194         <indent>
 195             AuthType Basic<br />
 196             AuthName Documents<br />
 197             AuthBasicProvider file<br />
 198             AuthUserFile /usr/local/apache/passwd/passwords<br />
 199             Require valid-user
 200         </indent>
 201         &lt;/Directory&gt;<br />
 202         <br />
 203         &lt;Directory /www/docs/public&gt;
 204         <indent>
 205             AuthType None<br />
 206             Require all granted
 207         </indent>
 208         &lt;/Directory&gt;
 209     </example>
 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 </usage>
 241 </directivesynopsis>
 242
 243 </modulesynopsis>