mirror of
https://github.com/apache/httpd.git
synced 2025-07-04 05:22:30 +03:00
cd65f78994
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1826856 13f79535-47bb-0310-9956-ffa450edef68
260 lines
11 KiB
XML
260 lines
11 KiB
XML
<?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>
|
|
|
|
<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|<var>username</var> [<var>password</var>]</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
|
|
>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
|
|
>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
|
|
>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>
|