Understanding .htpasswd: A quick guide to Apache basic authentication

What is .htpasswd?

.htpasswd is a simple text file used by Apache to store usernames and password hashes for basic authentication. It is typically referenced by directives in a .htaccess file or in the main server configuration via AuthUserFile. The server uses these entries to verify credentials when a user tries to access a protected resource.

How it works with Apache

When a client requests a protected resource, Apache prompts the user for a username and password (via basic authentication). The browser sends these credentials (encoded in base64) to the server. The server looks up the username in the .htpasswd file and compares the supplied password against the stored hash. If they match, access is granted; otherwise, authentication fails. For security, always use HTTPS so credentials are encrypted in transit.

Auth files and directives

The .htpasswd file is a plain text file with one entry per line in the format: username:hash. The file path is supplied to the server using the AuthUserFile directive, which can be placed in a directory block within the server config or in a .htaccess file (where allowed by the server).

Hashing and security

Password data in .htpasswd is stored as a hash, not in plain text. This helps protect passwords if the file is exposed. However, because basic authentication transmits credentials in base64, it is essential to protect the connection with TLS (HTTPS).

Hash schemes supported by htpasswd

Apache's htpasswd tool supports several hashing schemes, including:

• DES (default in very old setups)
• MD5-based (often invoked with -m)
• APR1 (an MD5-based scheme used by Apache, often with -m or -s)
• SHA-1 (with -s)
• Bcrypt (with -B)

The -C option allows you to set the number of rounds for some algorithms to increase security. For new deployments, bcrypt (-B) is generally preferred for its strength.

Why HTTPS matters

Basic authentication sends credentials with each request. If you do not use TLS, anyone on the network could capture usernames and passwords. Always pair .htpasswd with HTTPS to protect credentials in transit.

Creating and managing .htpasswd

You typically manage entries with the htpasswd command. The -c option creates a new file; omit -c to add or update users.

Generating entries

Create the first user (this creates the file):

htpasswd -c .htpasswd username

You will be prompted to enter the password. To use a specific hashing method, add the appropriate flag, for example:

htpasswd -c -B .htpasswd username   # bcrypt
htpasswd -m .htpasswd username        # MD5-based
htpasswd -s .htpasswd username        # SHA-1

Updating users

Add another user or update an existing one (without -c):

htpasswd .htpasswd newuser

Or specify a method:

htpasswd -B .htpasswd newuser

File permissions and location

Place the .htpasswd file outside the web root whenever possible, so it cannot be downloaded from the browser. Secure the file with permissions that prevent world-readable access (for example, on Unix systems: 640 or more restrictive, with the web server user as the owner or in the web server group).

Best practices and pitfalls

• Always use HTTPS when using basic authentication.
• Store the .htpasswd file outside the document root.
• Choose a strong hashing method (bcrypt preferred for new setups).
• Regularly rotate passwords and audit access.
• Do not store credentials in version-controlled repositories or backups exposed to public access.

Conclusion

.htpasswd provides a simple, text-based way to protect resources with basic authentication on Apache. By understanding how it stores hashed passwords, choosing a strong hashing method, and enforcing encrypted connections, you can implement a straightforward access control mechanism without introducing complex infrastructure.