2.4.x-mod_md/docs/manual/mod/mod_authn_file.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_authn_file.xml.meta">

<name>mod_authn_file</name>
<description>User authentication using text files</description>
<status>Base</status>
<sourcefile>mod_authn_file.c</sourcefile>
<identifier>authn_file_module</identifier>
<compatibility>Available in Apache 2.1 and later</compatibility>

<summary>
    <p>This module provides authentication front-ends such as
    <module>mod_auth_digest</module> and <module>mod_auth_basic</module>
    to authenticate users by looking up users in plain text password files.
    Similar functionality is provided by <module>mod_authn_dbm</module>.</p>

    <p>When using <module>mod_auth_basic</module> or
    <module>mod_auth_digest</module>, this module is invoked via the
    <directive module="mod_auth_basic">AuthBasicProvider</directive> or
    <directive module="mod_auth_digest">AuthDigestProvider</directive>
    with the <code>file</code> value.</p>
</summary>
<seealso>
  <directive module="mod_auth_basic">AuthBasicProvider</directive>
</seealso>
<seealso>
  <directive module="mod_auth_digest">AuthDigestProvider</directive>
</seealso>
<seealso><program>htpasswd</program></seealso>
<seealso><program>htdigest</program></seealso>
<seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso>

<directivesynopsis>
<name>AuthUserFile</name>
<description>Sets the name of a text file containing the list of users and
passwords for authentication</description>
<syntax>AuthUserFile <var>file-path</var></syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthUserFile</directive> directive sets the name
    of a textual file containing the list of users and passwords for
    user authentication. <var>File-path</var> is the path to the user
    file. If it is not absolute, it is treated as relative to the
    <directive module="core">ServerRoot</directive>.</p>

    <p>Each line of the user file contains a username followed by
    a colon, followed by the encrypted password. If the same user
    ID is defined multiple times, <module>mod_authn_file</module> will
    use the first occurrence to verify the password.</p>

    <p>The encrypted password format depends on which authentication
    frontend (e.g. <module>mod_auth_basic</module> or
    <module>mod_auth_digest</module>) is being used.  See <a
    href="../misc/password_encryptions.html">Password Formats</a> for
    more information.</p>

    <p>For <module>mod_auth_basic</module>, use the utility <program>htpasswd</program>
    which is installed as part of the binary distribution, or which
    can be found in <code>src/support</code>. See the
    <a href="../programs/htpasswd.html">man page</a> for more details.
    In short:</p>

    <p>Create a password file <code>Filename</code> with
    <code>username</code> as the initial ID. It will prompt for
    the password:</p>

    <example>
      htpasswd -c Filename username
    </example>

    <p>Add or modify <code>username2</code> in the password file
    <code>Filename</code>:</p>

    <example>
      htpasswd Filename username2
    </example>

    <p>Note that searching large text files is <em>very</em>
    inefficient; <directive
    module="mod_authn_dbm">AuthDBMUserFile</directive> should be used
    instead.</p>

    <p>For <module>mod_auth_digest</module>, use <program>htdigest</program>
    instead. Note that you cannot mix user data for Digest Authentication
    and Basic Authentication within the same file.</p>

    <note type="warning"><title>Security</title>
      <p>Make sure that the <directive>AuthUserFile</directive> is
      stored outside the document tree of the web-server. Do
      <strong>not</strong> put it in the directory that it protects.
      Otherwise, clients may be able to download the
      <directive>AuthUserFile</directive>.</p>
    </note>
</usage>
</directivesynopsis>

</modulesynopsis>