DEV Community

Michael Lip
Michael Lip

Posted on • Originally published at zovo.one

HTTP Basic Auth Still Works for Quick Access Control

#tutorial #devops #security #webdev

Before OAuth, before JWTs, before session cookies, there was HTTP Basic Authentication. It sends a username and password with every request, encoded in Base64 (not encrypted -- encoded). It is the simplest authentication mechanism in HTTP, and in certain contexts, it is still the right choice.

When Basic Auth makes sense

Staging environments. You want to prevent search engine indexing and casual access to your staging site without implementing a full authentication system. An htpasswd file in front of your staging server solves this in five minutes.

Internal tools. A monitoring dashboard, a build status page, or an admin panel that is only accessible on your VPN. Basic Auth adds a layer of access control without the overhead of implementing user management.

API authentication for simple services. If your API serves a single client (your own frontend) and runs over HTTPS, Basic Auth is simpler than implementing API key management or OAuth.

Quick prototyping. When you need "some authentication" on a prototype and do not want to spend time on auth before validating the concept.

When Basic Auth does not make sense

Any production user-facing application. Users expect to log in once and stay logged in. Basic Auth has no session management, no "remember me," and no logout mechanism (clearing the credential cache requires closing the browser).

Anything over plain HTTP. Base64 is trivially reversible. Without TLS/HTTPS, credentials are transmitted in cleartext.

Fine-grained access control. Basic Auth is all-or-nothing. Either you have the password or you do not. There are no roles, no permissions, no user-specific behavior.

How htpasswd works

The .htpasswd file stores username-password pairs where the password is hashed:

admin:$apr1$xyz123$HashedPasswordString
readonly:$2y$05$BcryptHashedPasswordString
Enter fullscreen mode Exit fullscreen mode

Apache's htpasswd utility creates and updates this file:

# Create new file with first user
htpasswd -c /etc/apache2/.htpasswd admin

# Add another user to existing file
htpasswd /etc/apache2/.htpasswd readonly

# Use bcrypt algorithm (recommended)
htpasswd -B /etc/apache2/.htpasswd admin
Enter fullscreen mode Exit fullscreen mode

The -c flag creates a new file (overwrites if existing -- be careful). The -B flag uses bcrypt, which is the strongest algorithm htpasswd supports.

Hash algorithms

The htpasswd format supports several algorithms:

bcrypt ($2y$): The current recommendation. Slow by design, resistant to brute force. Use this.

MD5/APR1 ($apr1$): Apache's custom MD5-based scheme. Adequate but weaker than bcrypt. Still the default in many Apache installations.

SHA1 ({SHA}): Unsalted SHA-1. Do not use. Vulnerable to rainbow table attacks.

crypt: The original Unix crypt function. Limited to 8-character passwords. Obsolete.

Nginx configuration

Nginx uses the same htpasswd file format:

server {
    listen 443 ssl;
    server_name staging.example.com;

    auth_basic "Staging Environment";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://localhost:3000;
    }
}
Enter fullscreen mode Exit fullscreen mode

The auth_basic directive sets the realm name (displayed in the browser's login dialog). The auth_basic_user_file points to the htpasswd file.

To protect only specific paths:

location /admin {
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://localhost:3000;
}
Enter fullscreen mode Exit fullscreen mode

Docker and CI/CD contexts

For containerized deployments, generate the htpasswd file during build:

RUN apt-get update && apt-get install -y apache2-utils
RUN htpasswd -bBc /etc/nginx/.htpasswd admin $STAGING_PASSWORD
Enter fullscreen mode Exit fullscreen mode

Or generate it locally and include it as a secret. Avoid committing htpasswd files to version control.

I built an htpasswd generator at zovo.one/free-tools/htpasswd-generator that creates properly formatted htpasswd entries with bcrypt, MD5/APR1, or SHA-1 hashing, entirely in your browser. Enter a username and password, select the hash algorithm, and copy the resulting line into your htpasswd file. No command-line tools needed.

I'm Michael Lip. I build free developer tools at zovo.one. 500+ tools, all private, all free.

Top comments (0)