(warning) THIS IS A SCRATCHPAD DOCUMENT, PLEASE CONSIDER THIS WHEN READING ON (lightbulb)

Auth Troubleshooting

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

Should I use .htaccess for access control?

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.

Basic Example

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.

My browser continuously prompts for a password but it's never accepted!

The relevant error log should explain why this is happening. Common errors are:

  • user foo: authentication failure for "/": Password Mismatch

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.

My browser doesn't prompt for a password

Check context etc.

My password is accepted but I get a Permission Denied error

Check Satisfy or other permissions errors in the log.

Troubleshooting for .htaccess users

These instructions are for untrusted users who are forced to use htaccess files.

I'm not being asked for a password

  • Make sure your htaccess file is being read by putting garbage in it.

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).

My password is never accepted

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.

  • No labels