Learning Caddy - Basic Authentication

#Introduction

Sometimes you need to lock something down quickly and without extra infrastructure: a staging environment the public shouldn't see, a small admin panel, or private documents. For needs like these, basic authentication is enough — and Caddy has it built in.

Episode 17 covers the basicauth directive: how to create password hashes with caddy hash-password, protect an entire site or only specific paths, register multiple users, and follow best practices when using basic auth.

Remember: basic auth is only appropriate for simple needs. For enterprise authentication, we'll cover forward auth and SSO in episode 18.

#The basicauth Directive

#Basic Syntax

basicauth uses a user and a bcrypt hash:

example.com {
    basicauth * {
        admin $2y$10$abcdefghijklmnopqrstuv
    }
    root * /var/www
    file_server
}

The format is: a username followed by a bcrypt hash. Requests without valid credentials are rejected with 401 and the browser shows a login dialog.

#Creating Password Hashes

Never write a plaintext password in the Caddyfile. Use the built-in command:

caddy hash-password --plaintext 'my-secret'

The output is a $2y$10$... string you can use directly in the Caddyfile. caddy hash-password --plaintext '...' produces a hash that can only be verified, never reversed.

#Multiple Users

Register several users with their own hashes:

example.com {
    basicauth * {
        admin $2y$10$hashAdmin
        editor $2y$10$hashEditor
        viewer $2y$10$hashViewer
    }
    root * /var/www
    file_server
}

Each user has their own hash. Caddy verifies credentials against all entries — anyone who matches is accepted. Separating roles (admin, editor, viewer) makes it easy to revoke one user's access without affecting the others.

#Protecting Specific Resources

#Entire Site vs Specific Paths

The asterisk (*) at the start of the directive means all paths:

example.com {
    basicauth * {
        admin $2y$10$hash
    }
    root * /var/www
    file_server
}

To protect only part of the site:

example.com {
    @admin {
        path /admin/*
    }
    basicauth @admin {
        admin $2y$10$hash
    }
    root * /var/www
    file_server
}

basicauth @admin only locks the /admin/* paths — public pages stay open without login. This is the most common pattern: a public site with a protected admin panel.

#Multiple Protection Zones

Combine matchers for different zones:

example.com {
    @admin {
        path /admin/*
    }
    @staging {
        host staging.example.com
    }
    basicauth @admin {
        admin $2y$10$hashAdmin
    }
    basicauth @staging {
        tester $2y$10$hashTester
    }
    root * /var/www
    file_server
}

The admin zone locks /admin/* paths with the admin user; the staging zone locks the subdomain with the tester user. Each zone has its own credentials — clean access isolation.

#Best Practices

#Always Use HTTPS

Basic auth sends credentials in the Authorization header. Without HTTPS, passwords can be intercepted. Since Caddy handles HTTPS automatically for public domains, make sure you don't disable it.

#Password Management

• Use strong, unique passwords per user.
• Rotate hashes regularly — a new hash whenever a password changes.
• Revoke users by removing their entry from the Caddyfile.
• Never commit passwords to Git; use env vars if you need automation.

#When to Move to a Bigger System

Basic auth is enough for prototypes and internal tools. Switch to forward auth (episode 18) when you need:

• Centralized login and SSO.
• OAuth2 or LDAP integration.
• User management without editing the Caddyfile.
• Sessions that can be logged out and revoked.

#Use Case: Staging Environment

A real staging pattern:

staging.example.com {
    basicauth * {
        developer $2y$10$hashStaging
    }
    reverse_proxy localhost:8080
}

A staging environment protected with basic auth won't be indexed by search engines and is hard for casual visitors to break into. The basicauth * + reverse proxy combination is one of the most used setups among developers in the real world.

#Conclusion

Episode 17 equipped you with basic authentication: the basicauth directive with bcrypt hashes, hash creation via caddy hash-password, protecting an entire site or specific paths with matchers, multiple users and protection zones, and best practices with HTTPS.

Key takeaways:

• basicauth uses bcrypt hashes, not plaintext passwords.
• Create hashes with caddy hash-password --plaintext.
• The asterisk protects all paths; matchers lock specific paths.
• Multiple users can be registered in one block.
• Basic auth should always be used with HTTPS.
• For bigger needs, move to forward auth in episode 18.

In the next episode, episode 18, we'll cover forward authentication & SSO — the forward_auth directive, integration with Authelia, Authentik, OAuth2 Proxy, and Keycloak, forwarding headers from the auth response, and global auth patterns with snippets. Centralized login for all your applications awaits.