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_auth_basic.xml.meta">
25 <name>mod_auth_basic</name>
26 <description>Basic HTTP authentication</description>
28 <sourcefile>mod_auth_basic.c</sourcefile>
29 <identifier>auth_basic_module</identifier>
32 <p>This module allows the use of HTTP Basic Authentication to
33 restrict access by looking up users in the given providers.
34 HTTP Digest Authentication is provided by
35 <module>mod_auth_digest</module>. This module should
36 usually be combined with at least one authentication module
37 such as <module>mod_authn_file</module> and one authorization
38 module such as <module>mod_authz_user</module>.</p>
40 <seealso><directive module="mod_authn_core">AuthName</directive></seealso>
41 <seealso><directive module="mod_authn_core">AuthType</directive></seealso>
42 <seealso><directive module="mod_authz_core">Require</directive></seealso>
43 <seealso><a href="../howto/auth.html">Authentication howto</a></seealso>
46 <name>AuthBasicProvider</name>
47 <description>Sets the authentication provider(s) for this location</description>
48 <syntax>AuthBasicProvider <var>provider-name</var>
49 [<var>provider-name</var>] ...</syntax>
50 <default>AuthBasicProvider file</default>
51 <contextlist><context>directory</context><context>.htaccess</context>
53 <override>AuthConfig</override>
56 <p>The <directive>AuthBasicProvider</directive> directive sets
57 which provider is used to authenticate the users for this location.
58 The default <code>file</code> provider is implemented
59 by the <module>mod_authn_file</module> module. Make sure
60 that the chosen provider module is present in the server.</p>
61 <example><title>Example</title>
62 <highlight language="config">
63 <Location "/secure">
65 AuthName "private area"
68 AuthDBMUserFile "/www/etc/dbmpasswd"
73 <p> Providers are queried in order until a provider finds a match
74 for the requested username, at which point this sole provider will
75 attempt to check the password. A failure to verify the password does
76 not result in control being passed on to subsequent providers.</p>
78 <p>Providers are implemented by <module>mod_authn_dbm</module>,
79 <module>mod_authn_file</module>, <module>mod_authn_dbd</module>,
80 <module>mod_authnz_ldap</module> and <module>mod_authn_socache</module>.</p>
85 <name>AuthBasicAuthoritative</name>
86 <description>Sets whether authorization and authentication are passed to
87 lower level modules</description>
88 <syntax>AuthBasicAuthoritative On|Off</syntax>
89 <default>AuthBasicAuthoritative On</default>
90 <contextlist><context>directory</context><context>.htaccess</context>
92 <override>AuthConfig</override>
95 <p>Normally, each authorization module listed in <directive
96 module="mod_auth_basic">AuthBasicProvider</directive> will attempt
97 to verify the user, and if the user is not found in any provider,
98 access will be denied. Setting the
99 <directive>AuthBasicAuthoritative</directive> directive explicitly
100 to <code>Off</code> allows for both authentication and
101 authorization to be passed on to other non-provider-based modules
102 if there is <strong>no userID</strong> or <strong>rule</strong>
103 matching the supplied userID. This should only be necessary when
104 combining <module>mod_auth_basic</module> with third-party modules
105 that are not configured with the <directive
106 module="mod_auth_basic">AuthBasicProvider</directive>
107 directive. When using such modules, the order of processing
108 is determined in the modules' source code and is not configurable.</p>
113 <name>AuthBasicFake</name>
114 <description>Fake basic authentication using the given expressions for
115 username and password</description>
116 <syntax>AuthBasicFake off|username [password]</syntax>
117 <default>none</default>
118 <contextlist><context>directory</context><context>.htaccess</context>
120 <override>AuthConfig</override>
121 <compatibility>Apache HTTP Server 2.4.5 and later</compatibility>
123 <p>The username and password specified are combined into an
124 Authorization header, which is passed to the server or service
125 behind the webserver. Both the username and password fields are
126 interpreted using the <a href="../expr.html">expression parser</a>,
127 which allows both the username and password to be set based on
128 request parameters.</p>
130 <p>If the password is not specified, the default value "password"
131 will be used. To disable fake basic authentication for an URL
132 space, specify "AuthBasicFake off".</p>
134 <p>In this example, we pass a fixed username and password to a
137 <example><title>Fixed Example</title>
138 <highlight language="config">
139 <Location "/demo">
140 AuthBasicFake demo demopass
145 <p>In this example, we pass the email address extracted from a client
146 certificate, extending the functionality of the FakeBasicAuth option
147 within the <directive module="mod_ssl">SSLOptions</directive>
148 directive. Like the FakeBasicAuth option, the password is set to the
149 fixed string "password".</p>
151 <example><title>Certificate Example</title>
152 <highlight language="config">
153 <Location "/secure">
154 AuthBasicFake "%{SSL_CLIENT_S_DN_Email}"
159 <p>Extending the above example, we generate a password by hashing the
160 email address with a fixed passphrase, and passing the hash to the
161 backend server. This can be used to gate into legacy systems that do
162 not support client certificates.</p>
164 <example><title>Password Example</title>
165 <highlight language="config">
166 <Location "/secure">
167 AuthBasicFake "%{SSL_CLIENT_S_DN_Email}" "%{sha1:passphrase-%{SSL_CLIENT_S_DN_Email}}"
172 <example><title>Exclusion Example</title>
173 <highlight language="config">
174 <Location "/public">
184 <name>AuthBasicUseDigestAlgorithm</name>
185 <description>Check passwords against the authentication providers as if
186 Digest Authentication was in force instead of Basic Authentication.
188 <syntax>AuthBasicUseDigestAlgorithm MD5|Off</syntax>
189 <default>AuthBasicUseDigestAlgorithm Off</default>
190 <contextlist><context>directory</context><context>.htaccess</context>
192 <override>AuthConfig</override>
193 <compatibility>Apache HTTP Server 2.4.7 and later</compatibility>
196 <p>Normally, when using Basic Authentication, the providers listed in
197 <directive module="mod_auth_basic">AuthBasicProvider</directive>
198 attempt to verify a user by checking their data stores for
199 a matching username and associated password. The stored passwords
200 are usually encrypted, but not necessarily so; each provider may
201 choose its own storage scheme for passwords.</p>
203 <p>When using <directive
204 module="mod_auth_digest">AuthDigestProvider</directive> and Digest
205 Authentication, providers perform a similar check to find a matching
206 username in their data stores. However, unlike in the Basic
207 Authentication case, the value associated with each stored username
208 must be an encrypted string composed from the username, realm name,
210 <a href="http://tools.ietf.org/html/rfc2617#section-3.2.2.2">
211 RFC 2617, Section 3.2.2.2</a> for more details on the format used
212 for this encrypted string.)</p>
214 <p>As a consequence of the difference in the stored values between
215 Basic and Digest Authentication, converting from Digest
216 Authentication to Basic Authentication generally requires that all
217 users be assigned new passwords, as their existing passwords cannot
218 be recovered from the password storage scheme imposed on those
219 providers which support Digest Authentication.</p>
221 <p>Setting the <directive
222 module="mod_auth_basic">AuthBasicUseDigestAlgorithm</directive> directive
223 to <code>MD5</code> will cause the user's Basic Authentication password
224 to be checked using the same encrypted format as for Digest
225 Authentication. First a string composed from the username, realm name,
226 and password is hashed with MD5; then the username and this encrypted
227 string are passed to the providers listed in
228 <directive module="mod_auth_basic">AuthBasicProvider</directive>
230 <directive module="mod_authn_core">AuthType</directive>
231 was set to <code>Digest</code> and Digest Authentication was in force.
234 <p>Through the use of <directive
235 module="mod_auth_basic">AuthBasicUseDigestAlgorithm</directive>
236 a site may switch from Digest to Basic Authentication without
237 requiring users to be assigned new passwords.</p>
240 The inverse process of switching from Basic to Digest
241 Authentication without assigning new passwords is generally
242 not possible. Only if the Basic Authentication passwords
243 have been stored in plain text or with a reversable encryption
244 scheme will it be possible to recover them and generate a
245 new data store following the Digest Authentication password
250 Only providers which support Digest Authentication will be able
251 to authenticate users when <directive
252 module="mod_auth_basic">AuthBasicUseDigestAlgorithm</directive>
253 is set to <code>MD5</code>. Use of other providers will result
254 in an error response and the client will be denied access.