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     Order deny,allow
  99     Allow from all
 100
 101     AuthBasicProvider ldap-other-alias  ldap-alias1
 102
 103     AuthType Basic
 104     AuthName "LDAP Protected Place"
 105     Require valid-user
 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 </usage>
 145 <seealso><a
 146     href="../howto/auth.html">Authentication, Authorization, and
 147     Access Control</a></seealso>
 148 <seealso><module>mod_authz_core</module></seealso>
 149 </directivesynopsis>
 150
 151 <directivesynopsis>
 152 <name>AuthType</name>
 153 <description>Type of user authentication</description>
 154 <syntax>AuthType None|Basic|Digest|Form</syntax>
 155 <contextlist><context>directory</context><context>.htaccess</context>
 156 </contextlist>
 157 <override>AuthConfig</override>
 158
 159 <usage>
 160     <p>This directive selects the type of user authentication for a
 161     directory. The authentication types available are <code>None</code>,
 162     <code>Basic</code> (implemented by
 163     <module>mod_auth_basic</module>), <code>Digest</code>
 164     (implemented by <module>mod_auth_digest</module>), and
 165     <code>Form</code> (implemented by <module>mod_auth_form</module>).</p>
 166
 167     <p>To implement authentication, you must also use the <directive
 168     module="mod_authn_core">AuthName</directive> and <directive
 169     module="mod_authz_core">Require</directive> directives.  In addition, the
 170     server must have an authentication-provider module such as
 171     <module>mod_authn_file</module> and an authorization module such
 172     as <module>mod_authz_user</module>.</p>
 173
 174     <p>The authentication type <code>None</code> disables authentication.
 175     When authentication is enabled, it is normally inherited by each
 176     subsequent <a href="../sections.html#mergin">configuration section</a>,
 177     unless a different authentication type is specified.  If no
 178     authentication is desired for a subsection of an authenticated
 179     section, the authentication type <code>None</code> may be used;
 180     in the following example, clients may access the
 181     <code>/www/docs/public</code> directory without authenticating:</p>
 182
 183     <highlight language="config">
 184 &lt;Directory /www/docs&gt;
 185     AuthType Basic
 186     AuthName Documents
 187     AuthBasicProvider file
 188     AuthUserFile /usr/local/apache/passwd/passwords
 189     Require valid-user
 190 &lt;/Directory&gt;
 191
 192 &lt;Directory /www/docs/public&gt;
 193     AuthType None
 194     Require all granted
 195 &lt;/Directory&gt;
 196     </highlight>
 197
 198     <note>When disabling authentication, note that clients which have
 199     already authenticated against another portion of the server's document
 200     tree will typically continue to send authentication HTTP headers
 201     or cookies with each request, regardless of whether the server
 202     actually requires authentication for every resource.</note>
 203 </usage>
 204
 205 <seealso><a href="../howto/auth.html">Authentication, Authorization,
 206     and Access Control</a></seealso>
 207 </directivesynopsis>
 208
 209 <directivesynopsis type="section">
 210 <name>AuthnProviderAlias</name>
 211 <description>Enclose a group of directives that represent an
 212 extension of a base authentication provider and referenced by
 213 the specified alias</description>
 214 <syntax>&lt;AuthnProviderAlias <var>baseProvider Alias</var>&gt;
 215 ... &lt;/AuthnProviderAlias&gt;</syntax>
 216 <contextlist><context>server config</context>
 217 </contextlist>
 218
 219 <usage>
 220     <p><code>&lt;AuthnProviderAlias&gt;</code> and
 221     <code>&lt;/AuthnProviderAlias&gt;</code> are used to enclose a group of
 222     authentication directives that can be referenced by the alias name
 223     using one of the directives <directive module="mod_auth_basic">
 224     AuthBasicProvider</directive> or <directive module="mod_auth_digest">
 225     AuthDigestProvider</directive>.</p>
 226
 227 </usage>
 228 </directivesynopsis>
 229
 230 </modulesynopsis>