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