mildly-basic-auth
Basic auth with nicer UX.
A transparent reverse proxy that shows a password page, sets a secure session cookie, and otherwise gets out of the way.
What it is
mildly-basic-auth puts a password page in front of anything that
speaks HTTP. Enter the password once; it sets a session cookie and turns
into a transparent passthrough — as if it were never there.
# as if we're not even there...
It fills the awkward middle ground: HTTP Basic auth is too ugly (a native browser dialog that never remembers you), and a full OAuth2 proxy is far too much (Google sign-in, callback URLs, client secrets) just to keep strangers out of a work-in-progress project or some personal docs.
Philosophy: stupid simple
One or more environment variables for passwords, one for the upstream. No config file to learn, no docs to read, no accounts, no database, no Redis. Drop the container in front of your app and it works.
Everything else follows from that:
- The built-in login page is a single self-contained HTML file (inline CSS and SVG, no external requests — the wall never phones home).
- Sessions are stateless. The cookie is a digest of the password used to log in, so there is nothing to persist, and rotating (or removing) a password invalidates only the sessions created with it — the others keep working.
- Authenticated traffic passes through untouched, streaming and WebSockets included.
Cookbook
Images are published to Docker Hub as qrichert/mildly-basic-auth and
to GitHub Container Registry as ghcr.io/qrichert/mildly-basic-auth.
Drop-in
The whole thing is two environment variables. Point MBA_UPSTREAM at
the service you want to protect and publish the gate's port instead of
the app's:
services:
auth-gate:
image: qrichert/mildly-basic-auth:latest
ports:
- "80:8000"
environment:
MBA_PASSWORD: "Tr0ub4dor&3"
MBA_UPSTREAM: http://app:2001
app:
image: traefik/whoami
command:
- "--port=2001"
Use a long, random MBA_PASSWORD, not something guessable like the
Tr0ub4dor&3 above. The session cookie is a fast digest of the
password, so a leaked cookie is an offline verifier of it — a strong
secret stays safe, a weak one does not.
Multiple passwords
Give each person or system its own password by adding
MBA_PASSWORD_<label> variables — the <label> is a free-form tag
(typically who it is for). Any of them logs in; there is no privileged
base variable, and the passwords must be distinct (startup rejects
duplicates so each can be revoked on its own):
services:
auth-gate:
image: qrichert/mildly-basic-auth:latest
ports:
- "80:8000"
environment:
MBA_PASSWORD_ALICE: ${ALICE_PASSWORD:?set a strong password}
MBA_PASSWORD_BOB: ${BOB_PASSWORD:?set a strong password}
MBA_UPSTREAM: http://app:2001
app:
image: traefik/whoami
command:
- "--port=2001"
Delete a variable and restart to revoke the sessions created with that password; the others keep working. The label is only for you: the gate authenticates anonymously and never learns who is behind a request, so revocation is per-password, not per-person.
Behind Caddy (TLS)
The drop-in above serves plain HTTP, so the session cookie is not
Secure and both the password and the token are visible on the wire.
That is fine on a trusted network, but for anything public, terminate
TLS in front. Caddy sets X-Forwarded-Proto: https, which flips the
cookie's Secure flag on automatically:
services:
caddy:
image: caddy:2
ports:
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
auth-gate:
image: qrichert/mildly-basic-auth:latest
environment:
MBA_ADDRESS: 0.0.0.0:4630
MBA_PASSWORD: ${MBA_PASSWORD:?set a strong password}
MBA_UPSTREAM: http://app:2001
app:
image: traefik/whoami
command:
- "--port=2001"
# Caddyfile
docs.example.com {
reverse_proxy auth-gate:4630
}
Without Docker
It is a single static binary. Install it as described in the
installation section, then hand it the same two
variables (it binds 0.0.0.0:8000 by default):
$ MBA_PASSWORD='…' MBA_UPSTREAM='http://127.0.0.1:2001' mildly-basic-auth
Bind each protected upstream to localhost or block its port with a firewall. If clients can reach the upstream directly, they can bypass authentication.
Configuration
Required
| Variable | Required | Description |
|---|---|---|
MBA_PASSWORD |
yes* | A password. Any configured password grants access. |
MBA_UPSTREAM |
yes | Absolute http(s)://host[:port] to forward to. |
General
| Variable | Required | Description |
|---|---|---|
MBA_ADDRESS |
no | IP and port to bind. Defaults to 0.0.0.0:8000. |
MBA_PASSWORD_<tag> |
no* | An additional password; <tag> is a free-form label. |
* At least one password must be set — MBA_PASSWORD or any
MBA_PASSWORD_<tag>; there is no privileged base variable. Passwords
must be distinct: startup rejects duplicates so each can be revoked
independently. Any of them logs in; removing a variable revokes the
sessions created with it.
MBA_ADDRESS accepts a concrete IPv4 or bracketed IPv6 address, not a
hostname, and the port must not be zero.
A missing or empty required variable, a duplicate password, or an
invalid MBA_ADDRESS is a hard startup error, not a silent passthrough
— the point is protection, so a misconfiguration fails loud instead of
leaving the door open.
The container listens on 0.0.0.0:8000 by default and runs as a
non-root user (UID 10001) on a Debian-slim image.[^debian]
[^debian]: Debian slim, not Alpine: musl's allocator degrades under the per-request, multithreaded allocation a proxy does, and the pure-Rust TLS stack (rustls + blake3, no OpenSSL) means Alpine's usual glibc/OpenSSL payoff does not apply here.
Template
| Variable | Default | Description |
|---|---|---|
MBA_TEMPLATE_FILE |
Built-in page | Path to custom password-page HTML. |
MBA_TEMPLATE_PAGE_LANGUAGE |
en |
Document language used by assistive tech. |
MBA_TEMPLATE_PAGE_TITLE |
Welcome! |
Browser tab title. |
MBA_TEMPLATE_ICON |
Lucide lock SVG | Complete icon HTML fragment. |
MBA_TEMPLATE_PASSWORD_LABEL* |
Password |
Accessible password-field label. |
MBA_TEMPLATE_PASSWORD_PLACEHOLDER |
password |
Visible password-field placeholder. |
MBA_TEMPLATE_WRONG_PASSWORD_MESSAGE* |
Wrong password. |
Accessible failed-login message. |
MBA_TEMPLATE_SUBMIT_BUTTON_TEXT |
Enter |
Submit-button text. |
* In the built-in page these are announced to assistive technologies only and not shown visually — sighted users see the placeholder and, on a failed login, the invalid-field icon and red border. A custom template may place the corresponding markers anywhere.
Icon override
MBA_TEMPLATE_ICON replaces the whole icon with unescaped HTML—no
wrapper or class is added. An empty value removes it.
The default is the Lucide lock:
environment:
MBA_TEMPLATE_ICON: |
<!-- Lock icon from Lucide (https://lucide.dev/icons/lock), ISC license. -->
<svg
style="margin: 0 auto; width: 1.5rem; height: 1.5rem;"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
aria-hidden="true"
>
<rect width="18" height="11" x="3" y="11" rx="2" ry="2"></rect>
<path d="M7 11V7a5 5 0 0 1 10 0v4"></path>
</svg>
An emoji works too:
environment:
MBA_TEMPLATE_ICON: |
<div
style="margin: 0 auto; font-size: 2.2rem; line-height: 2.3rem;"
aria-hidden="true"
>
🦖
</div>
Text overrides
The built-in password page can be translated or renamed without replacing its HTML.
For example:
environment:
MBA_TEMPLATE_PAGE_LANGUAGE: "fr"
MBA_TEMPLATE_PAGE_TITLE: "Mon site"
MBA_TEMPLATE_PASSWORD_LABEL: "Mot de passe"
MBA_TEMPLATE_PASSWORD_PLACEHOLDER: "mot de passe"
MBA_TEMPLATE_WRONG_PASSWORD_MESSAGE: "Mot de passe incorrect."
MBA_TEMPLATE_SUBMIT_BUTTON_TEXT: "Entrer"
An unset variable uses its default. An explicitly empty value removes that text. Values are inserted as text, not HTML, and are escaped before the page is served. A configured override that is not valid Unicode is a startup error.
Full override
Bind-mount a custom page and point MBA_TEMPLATE_FILE at it:
environment:
MBA_TEMPLATE_FILE: /etc/mba/template.html
volumes:
- ./template.html:/etc/mba/template.html:ro
Copy and adapt src/template.html; its structure
is not validated. The file must be non-empty UTF-8 readable by container
UID 10001. It is loaded once at startup, so changes require a restart.
Its {{...}} markers, and how each one renders, are documented inline
in the file.
Text marker values are escaped only for HTML text and quoted
attributes—not JavaScript, CSS, or URLs. {{ICON}} is inserted
verbatim. Custom HTML is public before authentication: keep it
self-contained and never put secrets in it.
Roadmap
v0 remains plain-passwords-in-environment-variables and deliberately small. Planned next:
- More auth methods: pre-hashed passwords, and possibly a
header-only bearer-token check. Pre-hashed passwords will be
BLAKE3-only — the login path hashes with BLAKE3 and the cookie is
that digest, so no other algorithm could match. A possible explicit
format is
blake3:<hex>; the exact syntax remains undecided. A pre-hash is still a password-equivalent bearer secret: it keeps the plaintext out of configuration but does not make configuration disclosure harmless. - Config beyond env vars: an env file or a YAML config file (via
MBA_CONFIG_FILEor discovery). - More settings: auth method, logging on/off, session lifetime.
- Authentication hardening: optional failed-login throttling, once trusted client-IP handling is configurable.
Non-goals
General traffic controls such as rate limiting and host allow-listing belong at the edge, not here. Also deliberately out of scope, permanently: LDAP, OAuth, an admin panel, policy rules, Redis, MFA/TOTP, and SSO.
Installation
Install from crates.io with Cargo:
cargo install mildly-basic-auth
Pre-built binaries for Linux and macOS are available on the latest GitHub release.
Documentation is available on docs.rs.