Password rotation is one of those security practices that everyone knows they should do but nobody actually enjoys. With .htpasswd files, the process is simpler than most people think, but there are a few gotchas that can cause problems. Let's walk through how to rotate .htpasswd passwords safely, without taking your site offline.
Why You Need Password Rotation
There are several scenarios where you need to change .htpasswd passwords:
**An employee or contractor leaves.** This is the most common reason. If someone who had access to a protected area leaves your organization, you need to revoke their access. If they shared the password with others (which happens more than people admit), you need to change it for everyone.
**A credential may have been exposed.** If someone accidentally committed the .htpasswd file to a public repository, or if a server was compromised, or if a team member's laptop was stolen, you need to rotate passwords as a precaution.
**Regular security policy.** Many organizations require password rotation on a schedule (every 6 or 12 months) for sensitive areas. This is a defense-in-depth measure: even if a password was quietly compromised, rotation limits the window of exposure.
**A password was too weak.** If you discover that your .htpasswd file contains weak passwords (or worse, plaintext entries from an old misconfiguration), you need to replace them with strong ones.
The Atomic File Replacement Approach
The key to rotating passwords without downtime is atomic file replacement. You do not edit the .htpasswd file in place. You create a new version of the file and then replace the old one in a single operation.
Here is why this matters. Apache and nginx read the .htpasswd file on every request. If you edit the file in place, there is a window where the file is partially written. A request that arrives during that window might see a truncated or malformed file and fail to authenticate the user. This is a race condition, and while it is brief, it can cause intermittent authentication failures that are hard to debug.
The atomic approach avoids this:
1. Create the new .htpasswd file as a temporary file (e.g., .htpasswd.new). 2. Verify the new file is correct (correct format, correct users, correct hashes). 3. Move the temporary file to the real location in a single operation.
On Linux, the mv command is atomic when both files are on the same filesystem. The replacement happens in a single filesystem operation, so no request ever sees a partially written file.
Here is the process in practice:
bash # Generate new entries in a temporary file htpasswd -cB /etc/nginx/.htpasswd.new admin htpasswd -B /etc/nginx/.htpasswd.new editor
# Set correct permissions chown www-data:www-data /etc/nginx/.htpasswd.new chmod 640 /etc/nginx/.htpasswd.new
# Verify the file looks correct cat /etc/nginx/.htpasswd.new
# Replace the old file atomically mv /etc/nginx/.htpasswd.new /etc/nginx/.htpasswd
The mv command is instant. The old file is replaced with the new one in a single operation. No request sees a partial file.
Testing New Credentials Before Going Live
Before you replace the file, test the new credentials. This is important because a typo in a username or a mistake in the hash format will lock everyone out.
You can test by pointing a temporary Apache or nginx config at the new .htpasswd file and trying to authenticate. Or more simply, you can verify the format manually:
1. Check that each line has the format username:hash. 2. Check that the hash starts with the correct prefix ($2y$ for bcrypt, $apr1$ for APR1). 3. Check that there are no extra whitespace characters or line breaks. 4. Check that the usernames match what you expect.
If you want to be thorough, set up a test location that points to the new .htpasswd file and try logging in:
nginx location /test-auth/ { auth_basic "Test Area"; auth_basic_user_file /etc/nginx/.htpasswd.new; # serve some test content }
Visit /test-auth/ in your browser and try the new credentials. If they work, you are safe to replace the file.
The Transition Period Problem
Here is a subtle issue. When you replace the .htpasswd file, any user who is currently authenticated with the old password will be logged out on their next request. Their browser is still sending the old credentials, which no longer match, so they get a 401 and see the login dialog again.
For most use cases, this is fine. The user sees a login dialog, enters the new password, and continues. But for some scenarios, this abrupt cutoff is a problem:
- API clients that use Basic Auth will start getting 401s and may not handle it gracefully. - Automated processes that use stored credentials will fail until updated. - Users in the middle of a multi-step process may lose their context.
If you need a transition period where both the old and new passwords work, you can add a second entry for the same user with the new password:
admin:$2y$05$oldHashHere... admin:$2y$05$newHashHere...
Both entries will work. Apache and nginx check each line in order, so a user with either password will be authenticated. Once everyone has transitioned to the new password, remove the old entry.
This is not a standard feature of Basic Auth. It works because both servers iterate through the .htpasswd file and try each matching username. If the first hash does not match, they try the next one. It is a hack, but it works and is useful for coordinated transitions.
Common Mistakes to Avoid
**Editing the file in place.** As we discussed, this can cause intermittent authentication failures. Always use the atomic replacement approach.
**Forgetting to set file permissions.** The new file needs the same ownership and permissions as the old one. If the web server cannot read the new file, authentication will fail for everyone. Always chown and chmod the new file before replacing the old one.
**Using a different algorithm.** If your old file used bcrypt and your new file uses APR1, the hashes will look different and may confuse anyone who looks at the file later. Stick with the same algorithm unless you are intentionally migrating. If you are migrating, do it deliberately and document it.
**Not testing before replacing.** A typo in a username or a malformed hash will lock everyone out. Always test the new credentials before replacing the file.
**Not communicating the change.** If users are not expecting a password change, they will think the site is broken when they see the login dialog. Send a notification before rotating passwords, especially for shared credentials.
The Full Rotation Process
Here is the complete process, step by step:
1. Generate new .htpasswd entries with strong passwords. Use our htpasswd generator or the htpasswd command with bcrypt. 2. Write the entries to a temporary file (not the live .htpasswd file). 3. Set the correct ownership and permissions on the temporary file. 4. Verify the format and test the credentials if possible. 5. Notify users that the password is changing and give them the new password through a secure channel (not email). 6. Replace the live .htpasswd file with the temporary file using mv (atomic replacement). 7. Test that the new credentials work by visiting the protected area. 8. Remove any old .htpasswd backup files that might contain old hashes.
The Bottom Line
Rotating .htpasswd passwords is straightforward if you follow the atomic replacement approach. Create the new file, verify it, replace the old one in a single operation. No downtime, no race conditions, no partial updates. The main things to get right are file permissions, format verification, and communication with users.
Generate your new .htpasswd entries with our htpasswd generator, and for the full setup guide, read our Apache .htaccess guide.
