f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>This module allows the use of HTTP Basic Authentication to
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz restrict access by looking up users in the given providers.
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz HTTP Digest Authentication is provided by
3604deb3632beeca54cfdb3864d872715971c300slive usually be combined with at least one authentication module
3604deb3632beeca54cfdb3864d872715971c300slive such as <module>mod_authn_file</module> and one authorization
87a0e78ba862eb998ccd545ae27c46c7ef89215abnicholes<seealso><directive module="mod_authn_core">AuthName</directive></seealso>
87a0e78ba862eb998ccd545ae27c46c7ef89215abnicholes<seealso><directive module="mod_authn_core">AuthType</directive></seealso>
87a0e78ba862eb998ccd545ae27c46c7ef89215abnicholes<seealso><directive module="mod_authz_core">Require</directive></seealso>
92988aaf68a67c9fa417556cb944eba6bb82ef92rbowen<seealso><a href="/howto/auth.html">Authentication howto</a></seealso>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<description>Sets the authentication provider(s) for this location</description>
f07998c217193b829f55c5ca8f4313ad5ba28f84nd<contextlist><context>directory</context><context>.htaccess</context>
f07998c217193b829f55c5ca8f4313ad5ba28f84nd</contextlist>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>The <directive>AuthBasicProvider</directive> directive sets
35ffb30f57f777dbf3f17c5a5ddf706559942c16nd which provider is used to authenticate the users for this location.
3604deb3632beeca54cfdb3864d872715971c300slive by the <module>mod_authn_file</module> module. Make sure
3604deb3632beeca54cfdb3864d872715971c300slive that the chosen provider module is present in the server.</p>
3658293f56f1683ca41e3bc5b70d98b203d8004bcoar<Location "/secure">
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh AuthType basic
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh AuthName "private area"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh AuthBasicProvider dbm
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh AuthDBMType SDBM
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh Require valid-user
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh</Location>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
35ffb30f57f777dbf3f17c5a5ddf706559942c16nd </example>
41618b507c149c7adf89bd92a0cc2c6962a29dcfcovener <p> Providers are queried in order until a provider finds a match
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim for the requested username, at which point this sole provider will
41618b507c149c7adf89bd92a0cc2c6962a29dcfcovener attempt to check the password. A failure to verify the password does
41618b507c149c7adf89bd92a0cc2c6962a29dcfcovener not result in control being passed on to subsequent providers.</p>
3604deb3632beeca54cfdb3864d872715971c300slive <p>Providers are implemented by <module>mod_authn_dbm</module>,
3604deb3632beeca54cfdb3864d872715971c300slive <module>mod_authn_file</module>, <module>mod_authn_dbd</module>,
5632f75dd34db0112cf4b6b7527eb538c80d976cniq <module>mod_authnz_ldap</module> and <module>mod_authn_socache</module>.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<directivesynopsis>
35ffb30f57f777dbf3f17c5a5ddf706559942c16nd<description>Sets whether authorization and authentication are passed to
35ffb30f57f777dbf3f17c5a5ddf706559942c16ndlower level modules</description>
35ffb30f57f777dbf3f17c5a5ddf706559942c16nd<contextlist><context>directory</context><context>.htaccess</context>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</contextlist>
3604deb3632beeca54cfdb3864d872715971c300slive <p>Normally, each authorization module listed in <directive
3604deb3632beeca54cfdb3864d872715971c300slive module="mod_auth_basic">AuthBasicProvider</directive> will attempt
3604deb3632beeca54cfdb3864d872715971c300slive to verify the user, and if the user is not found in any provider,
3604deb3632beeca54cfdb3864d872715971c300slive access will be denied. Setting the
3604deb3632beeca54cfdb3864d872715971c300slive <directive>AuthBasicAuthoritative</directive> directive explicitly
3604deb3632beeca54cfdb3864d872715971c300slive to <code>Off</code> allows for both authentication and
3604deb3632beeca54cfdb3864d872715971c300slive authorization to be passed on to other non-provider-based modules
3604deb3632beeca54cfdb3864d872715971c300slive if there is <strong>no userID</strong> or <strong>rule</strong>
3604deb3632beeca54cfdb3864d872715971c300slive matching the supplied userID. This should only be necessary when
3604deb3632beeca54cfdb3864d872715971c300slive combining <module>mod_auth_basic</module> with third-party modules
3604deb3632beeca54cfdb3864d872715971c300slive that are not configured with the <directive
3604deb3632beeca54cfdb3864d872715971c300slive directive. When using such modules, the order of processing
3604deb3632beeca54cfdb3864d872715971c300slive is determined in the modules' source code and is not configurable.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</directivesynopsis>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin<directivesynopsis>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin<description>Fake basic authentication using the given expressions for
fbc5cf5c3505692a5a250416bba8bc785783364aminfrinusername and password</description>
3640cdf72453e58a12ca1f4b1de5c778ecde621dminfrin<syntax>AuthBasicFake off|username [password]</syntax>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin<contextlist><context>directory</context><context>.htaccess</context>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin</contextlist>
9da97ff0bac3a0ff56a9cdebe6e5ab563636aa86jailletc<compatibility>Apache HTTP Server 2.4.5 and later</compatibility>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin <p>The username and password specified are combined into an
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin Authorization header, which is passed to the server or service
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin behind the webserver. Both the username and password fields are
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin interpreted using the <a href="/expr.html">expression parser</a>,
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin which allows both the username and password to be set based on
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin request parameters.</p>
3640cdf72453e58a12ca1f4b1de5c778ecde621dminfrin <p>If the password is not specified, the default value "password"
3640cdf72453e58a12ca1f4b1de5c778ecde621dminfrin will be used. To disable fake basic authentication for an URL
3640cdf72453e58a12ca1f4b1de5c778ecde621dminfrin space, specify "AuthBasicFake off".</p>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin <p>In this example, we pass a fixed username and password to a
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin backend server.</p>
3658293f56f1683ca41e3bc5b70d98b203d8004bcoar<Location "/demo">
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin AuthBasicFake demo demopass
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin</Location>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin </highlight>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin <p>In this example, we pass the email address extracted from a client
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin certificate, extending the functionality of the FakeBasicAuth option
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin within the <directive module="mod_ssl">SSLOptions</directive>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin directive. Like the FakeBasicAuth option, the password is set to the
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin fixed string "password".</p>
3658293f56f1683ca41e3bc5b70d98b203d8004bcoar<Location "/secure">
3658293f56f1683ca41e3bc5b70d98b203d8004bcoar AuthBasicFake "%{SSL_CLIENT_S_DN_Email}"
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin</Location>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin </highlight>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin <p>Extending the above example, we generate a password by hashing the
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin email address with a fixed passphrase, and passing the hash to the
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin backend server. This can be used to gate into legacy systems that do
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin not support client certificates.</p>
3658293f56f1683ca41e3bc5b70d98b203d8004bcoar<Location "/secure">
3658293f56f1683ca41e3bc5b70d98b203d8004bcoar AuthBasicFake "%{SSL_CLIENT_S_DN_Email}" "%{sha1:passphrase-%{SSL_CLIENT_S_DN_Email}}"
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin</Location>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin </highlight>
3658293f56f1683ca41e3bc5b70d98b203d8004bcoar<Location "/public">
3640cdf72453e58a12ca1f4b1de5c778ecde621dminfrin AuthBasicFake off
3640cdf72453e58a12ca1f4b1de5c778ecde621dminfrin</Location>
3640cdf72453e58a12ca1f4b1de5c778ecde621dminfrin </highlight>
fbc5cf5c3505692a5a250416bba8bc785783364aminfrin</directivesynopsis>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd<directivesynopsis>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd<description>Check passwords against the authentication providers as if
5cb0075c38fc868730c4981e346845dad6c7ea58chrisdDigest Authentication was in force instead of Basic Authentication.
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd</description>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd<contextlist><context>directory</context><context>.htaccess</context>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd</contextlist>
9da97ff0bac3a0ff56a9cdebe6e5ab563636aa86jailletc<compatibility>Apache HTTP Server 2.4.7 and later</compatibility>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd <p>Normally, when using Basic Authentication, the providers listed in
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd <directive module="mod_auth_basic">AuthBasicProvider</directive>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd attempt to verify a user by checking their data stores for
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd a matching username and associated password. The stored passwords
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd are usually encrypted, but not necessarily so; each provider may
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd choose its own storage scheme for passwords.</p>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd module="mod_auth_digest">AuthDigestProvider</directive> and Digest
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd Authentication, providers perform a similar check to find a matching
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd username in their data stores. However, unlike in the Basic
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd Authentication case, the value associated with each stored username
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd must be an encrypted string composed from the username, realm name,
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd and password. (See
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd <a href="http://tools.ietf.org/html/rfc2617#section-3.2.2.2">
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd RFC 2617, Section 3.2.2.2</a> for more details on the format used
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd for this encrypted string.)</p>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd <p>As a consequence of the difference in the stored values between
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd Basic and Digest Authentication, converting from Digest
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd Authentication to Basic Authentication generally requires that all
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd users be assigned new passwords, as their existing passwords cannot
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd be recovered from the password storage scheme imposed on those
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd providers which support Digest Authentication.</p>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd module="mod_auth_basic">AuthBasicUseDigestAlgorithm</directive> directive
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd to <code>MD5</code> will cause the user's Basic Authentication password
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd to be checked using the same encrypted format as for Digest
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd Authentication. First a string composed from the username, realm name,
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd and password is hashed with MD5; then the username and this encrypted
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd string are passed to the providers listed in
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd <directive module="mod_auth_basic">AuthBasicProvider</directive>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd <directive module="mod_authn_core">AuthType</directive>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd was set to <code>Digest</code> and Digest Authentication was in force.
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd module="mod_auth_basic">AuthBasicUseDigestAlgorithm</directive>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd a site may switch from Digest to Basic Authentication without
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd requiring users to be assigned new passwords.</p>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd The inverse process of switching from Basic to Digest
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd Authentication without assigning new passwords is generally
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd not possible. Only if the Basic Authentication passwords
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd have been stored in plain text or with a reversable encryption
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd scheme will it be possible to recover them and generate a
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd new data store following the Digest Authentication password
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd storage scheme.
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd Only providers which support Digest Authentication will be able
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd to authenticate users when <directive
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd module="mod_auth_basic">AuthBasicUseDigestAlgorithm</directive>
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd is set to <code>MD5</code>. Use of other providers will result
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd in an error response and the client will be denied access.
5cb0075c38fc868730c4981e346845dad6c7ea58chrisd</directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</modulesynopsis>