# mildly-basic-auth


[](https://crates.io/crates/mildly-basic-auth)
[](https://github.com/qrichert/mildly-basic-auth/actions)
_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.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/qrichert/mildly-basic-auth/main/demo/dark.png">
<img alt="Rendered visual of the auth gate." src="https://raw.githubusercontent.com/qrichert/mildly-basic-auth/main/demo/light.png">
</picture>
## 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.
```python
if not authenticated:
show_password_gate()
else:
passthrough_transparently() # 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`].
[`qrichert/mildly-basic-auth`]:
https://hub.docker.com/r/qrichert/mildly-basic-auth
[`ghcr.io/qrichert/mildly-basic-auth`]:
https://github.com/qrichert/mildly-basic-auth/pkgs/container/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:
```yml
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):
```yml
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:
```yml
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
# 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](#installation), then hand it the same two
variables (it binds `0.0.0.0:8000` by default):
```console
$ 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
| `MBA_PASSWORD` | yes\* | A password. Any configured password grants access. |
| `MBA_UPSTREAM` | yes | Absolute `http(s)://host[:port]` to forward to. |
### General
| `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]
### Template
| `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:
```yaml
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:
```yaml
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:
```yaml
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:
```yaml
environment:
MBA_TEMPLATE_FILE: /etc/mba/template.html
volumes:
- ./template.html:/etc/mba/template.html:ro
```
Copy and adapt [`src/template.html`](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_FILE` or 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:
```shell
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.
[crates.io]: https://crates.io/crates/mildly-basic-auth
[latest GitHub release]:
https://github.com/qrichert/mildly-basic-auth/releases/latest
[Documentation]: https://docs.rs/mildly-basic-auth