THIS IS A SCRATCHPAD DOCUMENT, PLEASE CONSIDER THIS WHEN READING ON
This guide aims to answer the question "Help, my authentication isn't working! What's wrong?". It is specific to the latest stable branch of Apache HTTPD, version 2.2.
For more detailed reference information, see: http://httpd.apache.org/docs/2.2/howto/auth.html
Generally, no. There is a very common misconception that htaccess files are needed for authentication and authorisation, propped up by countless misleading guides and unfortunate naming conventions. This troubleshooter assumes that you are using the server's main configuration file(s), which is recommended whenever possible. Information for htaccess users follows later for those forced to use this mechanism.
This example requires a password for access to any resource on a site.
# (other modules) LoadModule authn_file_module modules/mod_authn_file.so LoadModule authz_user_module modules/mod_authz_user.so LoadModule auth_basic_module modules/mod_auth_basic.so # (other modules) # (rest of the config) NameVirtualHost *:80 <VirtualHost *:80> ServerName example.com DocumentRoot /svr/www/example.com <Location /> AuthName "Secret Widgets" AuthType Basic AuthUserFile /etc/httpd/passwords Require valid-user </Location> </VirtualHost> |
In order for this configuration to work, the file /etc/httpd/passwords
must be created using the htpasswd
utility. See htpasswd -h
for help on its available options (in particular, note that the -c option should be used exactly once per file, to create the passwords file).
Users of Debian or Ubuntu Linux operating systems should check that the module configuration files for each of the three modules listed above have been symlinked from the mods-available directory to mods-enabled.
The relevant error log should explain why this is happening. Common errors are:
The password you are attempting to use is incorrect.
\[userfile not found\] |
Make sure the path to the AuthUserFile is a correct, absolute filesystem path.
\[UserFile can't be read\] |
Ensure that the user account under which apache runs is able to read the password file, and is able to access (+x) all of the file's parent directories.
\[Passwords in unrecognised encryption\] |
Blah blah windows doesn't have crypt() or something. Use md5 instead.
\[password file can't be read. no groups file?\] |
Make sure mod_authn_file is loaded. This is a common problem for Debian users who upgrade from version 2.0 to 2.2 as the new/changed auth modules aren't automatically enabled.
\[Unrecognised directive blah de feh\] |
Load your modules, silly.
Check context etc.
Check Satisfy or other permissions errors in the log.
These instructions are for untrusted users who are forced to use htaccess files.
If you don't get a 500 Internal Server Error, your server is not looking for htaccess files. Ask your administrator to enable AllowOverride AuthConfig
for the directory containing your htaccess file.
Alternatively, it could be that your htaccess file is in the wrong directory, or is misnamed (check for leading or trailing spaces in the file name).
In addition to the instructions noted above for administrators able to edit the main server config, htaccess users should ensure that the path specified in the AuthUserFile directive is a full filesystem path, and not relative to the site's root or the htaccess file.