htpasswd Generator

Which hash should I use?

Apache documents bcrypt as currently very secure. APR1/MD5 is Apache-specific and commonly compatible, but older. This page now validates APR1 against Apache/OpenSSL example vectors. SHA-1, crypt, and plaintext are legacy formats and should only be used when your host requires them.

A practical guide to .htpasswd and Apache Basic Auth

HTTP Basic Authentication is the oldest access control on the web and still one of the most useful. It takes about two minutes to set up, needs no database and no application code, and is the right tool for putting a staging site behind a door, keeping crawlers off an internal dashboard, or protecting an admin endpoint that only a handful of people should reach.

It is also widely misconfigured, usually in ways that are invisible until someone goes looking. The sections below cover the decisions that actually matter.

What Basic Auth does, and what it does not

When a browser hits a protected resource, Apache returns 401 with a WWW-Authenticate header. The browser prompts, then sends the username and password on every subsequent request in an Authorization header, encoded as base64.

Base64 is an encoding, not encryption. Anyone who can see the traffic can decode the credentials instantly. Over plain HTTP, Basic Auth is equivalent to sending the password in the clear. HTTPS is not a recommendation here, it is a requirement — and it should be enforced with a redirect so the credentials are never sent over an unencrypted connection even once.

Choosing a hash format

The .htpasswd file stores one username:hash pair per line. Apache supports four formats, and they are not equivalent:

• bcrypt (-B, hashes start $2y$) — the right choice for anything new. Deliberately slow, salted, with a tunable cost factor. Supported by Apache 2.4 and later.
• APR1 (-m, hashes start $apr1$) — Apache's own MD5-based format, salted and iterated 1,000 times. Weak by modern standards but supported essentially everywhere, which is why it remains the default on many hosts. Note that it is not a plain MD5 checksum.
• SHA-1 (-s, hashes start {SHA}) — a single unsalted SHA-1. Because it is unsalted, identical passwords produce identical hashes and the whole file is vulnerable to precomputed lookup tables. Use only when a host refuses anything else.
• crypt — legacy Unix DES. It silently truncates the password to eight characters, so a 30-character passphrase provides eight characters of protection. Avoid.
• Plain text (-p) — Windows and NetWare only, and exactly what it sounds like.

The bcrypt cost factor, and an honest caveat

Apache's htpasswd -B defaults to a cost of 5, which is low — it dates from when the feature was added and has not moved since. For a password file, -C 10 or -C 12 is a more appropriate setting, and each step up doubles the work required to test a candidate password.

There is a real trade-off, though, and it is specific to Basic Auth. Basic Auth has no session: the browser resends the credentials on every single request, and Apache verifies the hash every time. At cost 12, that verification takes on the order of a quarter of a second, and a page pulling forty assets pays it forty times. For a staging site with three users this is irrelevant. For anything with real traffic, cost 10 is a sensible ceiling, and the honest answer is that a site needing both strong hashing and throughput should not be using Basic Auth as its primary authentication.

Where to put the file

This is the mistake that undoes everything else. The .htpasswd file must live outside your document root. If it sits next to index.html, it may be downloadable over the web, and an attacker with the file can crack it offline at their leisure with nothing to rate-limit them.

Put it somewhere like /etc/apache2/.htpasswd or a private directory a level above public_html, and give it restrictive permissions — readable by the Apache user, nobody else. If your hosting forces it inside the web root, add an explicit rule denying access to files matching .ht* and verify by requesting the file in a browser. Most distributions ship that rule by default; do not assume yours has it.

Wiring it up

The .htaccess block in the tool above is the standard Apache 2.4 form. Two details are worth knowing:

• AuthUserFile takes an absolute filesystem path, not a URL and not a path relative to the web root. A relative path is interpreted against the server root and is the usual cause of a mysterious 500.
• Apache 2.4 replaced the old Order/Allow/Deny directives with Require. Copying a 2.2-era snippet into a 2.4 server produces either an error or, worse, a rule that does not apply. Use Require valid-user for any authenticated user, or Require user alice bob to name them.

For .htaccess to be read at all, the surrounding directory must be covered by AllowOverride AuthConfig or AllowOverride All in the main server configuration. If you control the server config, putting the directives there instead of in .htaccess is faster — Apache re-reads .htaccess on every request.

What Basic Auth cannot do

Knowing the gaps is what keeps it in its lane:

• No logout. The browser caches the credentials for the session and there is no clean, cross-browser way to clear them. Users close the browser or use a private window.
• No lockout or rate limiting. Apache will happily check ten thousand attempts a minute. If the endpoint is public, pair it with fail2ban or an equivalent, watching your Apache error log for repeated 401s.
• No per-user anything. No roles, no audit trail beyond access logs, no password reset, no expiry. It is a door, not an identity system.
• Shared credentials drift. In practice one username and password gets passed around a team and never changes. Give each person their own line in the file so you can remove one without disrupting everyone.

When to reach for something else

If you need sessions, roles, password resets, or an audit trail, Basic Auth is the wrong layer and the answer is authentication in your application. If you want SSO in front of a site you would rather not modify, an identity-aware proxy — Cloudflare Access, an OIDC module such as mod_auth_openidc, or your cloud provider's equivalent — gives you real accounts and logging without touching the application. Digest authentication is not the upgrade it appears to be; it is effectively deprecated and carries its own storage problems.

For its actual purpose — a quick, dependency-free gate on something that should not be publicly readable — Basic Auth over HTTPS with a bcrypt password file remains a perfectly reasonable answer.

Related password tools

FAQ