One instance.
Many vhosts. Each its own rules.

What's new, at a glance #

Five additions, all opt-in — an existing routes.yml/config.json keeps working unchanged until you reach for one of these.

config.json — full reference #

config.json is read once at startup. With the exception of the otpkey field on each user (see Database-backed TOTP), changes to this file require a service restart to take effect — unless the equivalent setting is one of the nine per-vhost overrides, which apply live as soon as routes.yml is reloaded.

Core & networking

Authentication & sessions

Every field below can also be set per vhost, overriding this global default for just that vhost — see Per-vhost configuration. These remain the fallback a vhost uses when it doesn't set its own.

Password reset & SMTP

Rate limiting

ratelimit_auth and ratelimit_proxy share the same three keys, applied independently to /auth traffic and proxied traffic — a burst of bad login attempts can't drown out real API traffic, or vice versa.

Requests within the limit pass straight through; anything over the burst gets a clean 429, not a dropped connection. /adm/* admin endpoints are not rate-limited at all — protected only by token_admin, the same as /adm/revoke//adm/logs.

Multi-instance & scaling

Operational

The User object

How a token is built and verified #

A successful login doesn't just sign a JWT-style payload — the token's construction itself has a build-specific layer on top of the usual encryption, which is what makes sync export/sync import (see SSO across instances) necessary for multi-node deployments rather than sharing secret alone.

Building a token

1. Seven values are gathered: the username, a secret+timestamp composite, the running binary's build time, the token's expiry, a per-build random value, the token's ID, and a per-build key-derivation salt.
2. These are concatenated in an order that is itself randomized per build — a fresh binary compiled from the same source produces a different shuffle order, derived from a build-time constant baked into that specific binary.
3. The shuffled, colon-joined string is hashed with BLAKE3.
4. That hash, plus the expiry, the user's index, and the token ID, are joined with | and encrypted with XChaCha20-Poly1305, using a key derived from secret via HKDF-SHA256 (salted with another per-build constant).

Two binaries built from identical source, with identical config.json, produce tokens that don't validate against each other — the shuffle order and the HKDF salt both differ per build. This is deliberate: it means stealing secret alone is never enough to forge a valid token without the matching binary's build constants too.

Verifying a token

1. Decrypt with the same derived key, and split the four |-delimited fields back out.
2. Look the user up by the index encoded in the token — not by username — and check the expiry against token_expiry_seconds.
3. Recompute the expected hash the same way it was built, using the now-known username, expiry, and token ID from the decrypted payload.
4. Compare the recomputed hash against the one embedded in the token, using a constant-time comparison — a plain != on the raw bytes would leak timing information about how many leading bytes matched, an actual side-channel against the token's own integrity check.
5. Check the token ID against the revocation set (see /adm/revoke) — a structurally valid, unexpired token that's been explicitly revoked is still rejected.

How a route is matched #

Every incoming request is matched against routes.yml in a fixed order — understanding this order explains a lot of otherwise-surprising behavior, especially on an instance with several vhosts or overlapping prefixes.

The evaluation order

1. Regex routes first, in the order they appear in routes.yml — first match wins, the same way nginx tries location ~ pattern blocks in file order.
2. Then every plain-prefix route, longest prefix first. A route matching /api/v2 is tried before one matching /api, regardless of which is listed first in the file — the more specific route always gets first refusal.
3. / (the bare root) is always tried last among plain-prefix routes, whatever its actual listed position — it's the most generic possible prefix, so it only catches what nothing more specific claimed.

Within that order, a route only actually matches if its vhost list also matches the request's Host header (or the route has no vhost at all — see Virtual hosts below).

Prefix matching, precisely

A request path matches a route's prefix if it's an exact match, or if it starts with the prefix followed by /. prefix: "/api" matches /api and /api/users, but not /apikeys — the boundary has to land on a real path segment, not just a shared string of characters.

Core fields #

Every route needs exactly one of two content sources — a proxied backend, or a static file/directory — plus a prefix to match requests against.

routes:
  - prefix: "/api"
    target: "http://127.0.0.1:8000"

routes:
  - prefix: "/"
    static: "/var/www/app/public/"
    static_index: "login.html"

Virtual hosts & per-vhost TLS #

A route with no vhost at all is a catch-all — it matches any Host header, the same behavior every routes.yml had before vhost existed. A route with a vhost list only matches requests for one of those hostnames.

vhosts:
  - vhost: ["app.example.com"]
    vhost_cert:
      cert: "/etc/proxyauth/cert/app.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/app.example.com/privkey.pem"
    certbot_renew: true
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8000"
      - prefix: "/admin"
        target: "http://127.0.0.1:8001"

A vhosts: group is a convenience — it expands into individual routes at load time, each inheriting the group's vhost/vhost_cert/certbot_renew (and every per-vhost override covered next) unless the route sets its own. If more than one route shares a vhost, these only need to be set on one of them — or, cleaner, once on the group.

Per-vhost configuration #

Nine settings that used to be global-only in config.json can now be set on a vhosts: entry in routes.yml instead — letting different domains on the same instance behave completely differently. A vhost that doesn't set one of these simply falls through to the existing global default, so nothing changes for a vhost that doesn't need it.

vhosts:
  - vhost: ["app.example.com"]
    session_cookie: true
    tag_csrf_token: true
    login_redirect_url: "/app"
    logout_redirect_url: "/"
    login_via_otp: true
    page_change_password: "https://app.example.com/lost-password.html"
    max_age_session_cookie: 3600
    cors_origins: ["https://app.example.com"]
    smtp:
      host: smtp.app.example.com
      port: 587
      username: noreply@app.example.com
      password: "..."
      from: "App <noreply@app.example.com>"
      timeout_secs: 10
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8000"

  - vhost: ["other.example.com"]
    smtp:
      host: smtp.another-domain.com
      port: 587
      username: noreply@other.example.com
      password: "..."
      from: "Other <noreply@other.example.com>"
      timeout_secs: 10
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:9000"

The nine fields

Vhost login authorization #

A different, earlier gate than the route-level username/groups/roles fields, which only govern access to a specific route's content for someone already logged in. This one decides whether a login attempt on a given vhost's /auth succeeds at all, before any session or route access even enters the picture.

vhosts:
  - vhost: ["app.example.com"]
    allow_groups: ["ops"]
    allow_roles: ["admin"]
    exclude_users: ["toto"]
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8000"

Here, anyone in the ops group or holding the admin role can log in — except toto, even if toto happens to also be in ops or hold that role.

The four fields

How the decision is made

OIDC provider — overview & flow #

A vhost with oidc: configured turns ProxyAuth into a genuine OpenID Connect provider (OP) for the backend sitting behind it. The backend — Grafana, Nextcloud, GitLab, or anything else that natively speaks OIDC as a relying party (RP) — receives a real, independently-verifiable id_token via the standard authorization code flow, instead of relying on ProxyAuth's own header injection (X-User, X-User-Roles, …) or session cookie.

What changes on an oidc-enabled vhost

ProxyAuth's own required_login/session enforcement is bypassed for this vhost's proxied routes — the backend is responsible for its own auth decision via OIDC now, the same way it would be sitting behind any other OIDC provider. What ProxyAuth does still do on this vhost is serve five endpoints, intercepted ahead of normal routing:

Every other path on this vhost proxies straight through to the backend, unauthenticated by ProxyAuth itself — exactly as if required_login were never set.

A user still authenticates the normal way

Nothing about how someone proves who they are changes — it's still ProxyAuth's own account store (file or database), the same credential/TOTP verification as everywhere else. What changes is when and how that gets communicated: the login happens at /authorize, packaged as the OIDC login step, and the proof that reaches the backend is a signed token instead of a header or cookie.

The full flow

The /authorize → login detour only happens once per session — a returning visitor with a still-valid ProxyAuth session skips straight from GET /authorize to the redirect-with-code, no login form in between.

OIDC provider — configuration #

One oidc: block per vhost, registering exactly one relying party — the backend sitting behind that vhost. Deliberately one client per vhost, not a list: ProxyAuth's own model is already "one vhost, one backend" everywhere else (target:, backends:), and matching that here keeps the block answering one question — which backend, at which callback URL, is allowed to receive tokens for this vhost's identity.

vhosts:
  - vhost: ["grafana.example.com"]
    tls: true                        # required — an OIDC issuer must be https
    oidc:
      client_id: "grafana"
      client_secret_hash: "$argon2id$v=19$m=19456,t=2,p=1$..."
      redirect_uris:
        - "https://grafana.example.com/login/generic_oauth"
      scopes: ["openid", "profile", "email"]
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:3000"

The four fields

Generating client_secret_hash

Pick a long random value for the secret itself (treat it like an API key, not a password a human types — no length/memorability constraints apply), then hash it with Argon2id the same way ProxyAuth hashes everything else. There's no dedicated CLI command for this yet — until there is, any small script using the same argon2 crate ProxyAuth itself depends on works:

use argon2::password_hash::{PasswordHasher, SaltString, rand_core::OsRng};
use argon2::Argon2;

let secret = "grafana-super-secret-value"; // keep this, plaintext, for the backend's own config
let salt = SaltString::generate(&mut OsRng);
let hash = Argon2::default()
    .hash_password(secret.as_bytes(), &salt)
    .unwrap()
    .to_string();
println!("{hash}"); // this goes in routes.yml's client_secret_hash

Keep the plaintext secret for the backend's own configuration — routes.yml only ever needs the hash.

Configuring the backend

Any application that speaks standard OIDC configures against the same five URLs regardless of which one it is. Grafana, as a concrete example:

[auth.generic_oauth]
enabled = true
name = ProxyAuth
client_id = grafana
client_secret = grafana-super-secret-value
scopes = openid profile email
auth_url = https://grafana.example.com/authorize
token_url = https://grafana.example.com/token
api_url = https://grafana.example.com/userinfo
redirect_uri = https://grafana.example.com/login/generic_oauth

Verifying it's working

$ curl https://grafana.example.com/.well-known/openid-configuration
$ curl https://grafana.example.com/jwks.json

Both should return JSON with the expected URLs and a public key respectively. The real end-to-end test is clicking "Sign in with ProxyAuth" from the backend's own login page and following the flow through.

OIDC provider — endpoint reference #

Every check below is enforced in this order — each one earns its place in the chain that turns "someone has a code" into "here is cryptographic proof of who logged in."

Authorization codes

Single-use, validated and consumed atomically (one LMDB read-write transaction — the same fix applied to ProxyAuth's own password-reset tokens after a real race condition was found there), and deliberately short-lived: 120 seconds, enough for the immediate browser redirect and server-to-server exchange, not for anything else.

Token verification, precisely

id_token carries iss/sub/aud/exp/iat/nonce — meant to be verified by the relying party's own OIDC library against /jwks.json, checking aud matches its own client_id. access_token additionally carries scope, deliberately without aud — it's only ever verified by ProxyAuth's own /userinfo, which also checks the token's iss matches the vhost the request actually arrived on, since every oidc-enabled vhost currently shares one signing key.

Access control #

Route-level access control — what an already-logged-in visitor can reach. Not to be confused with vhost login authorization, which decides whether someone can log in on a vhost at all, before any route access is relevant.

username, groups and roles combine as an OR — a user reaches the route if any condition holds. All three empty means any authenticated account may use the route — the opposite default from vhost login authorization, and worth keeping straight: an empty list here is permissive, an empty list there is a lockout.

routes:
  - prefix: "/admin"
    target: "http://127.0.0.1:8000"
    groups: ["ops"]
    roles: ["admin"]

Group- and role-based access control #

Alternatives to enumerating individual usernames on every route, for when the same set of people needs access to many routes.

A user reaches a route if any of three conditions hold: their username is explicitly listed in username, they belong to an allowed groups entry, or they hold an allowed roles entry — see Access control. groups and roles are checked against the matching fields on the User object (or the equivalent database columns).

roles vs. groups — a real distinction, not two names for the same thing

roles predates route-level access control and originally did one thing only: get forwarded to the backend as an X-User-Roles header, for the backend's own authorization logic to consume. That still happens. roles can also now gate route access directly, the same way groups does — the two mechanisms coexist without conflict, since a role either matching a route's roles list or not is independent of whatever the backend chooses to do with the same header.

groups was added specifically for access control and has no header side-effect — use it when you want a permission grouping that has no meaning to the backend at all, and roles when the backend also needs to know.

What the backend sees

X-User: alice
X-User-Roles: admin,ops
X-User-Groups: engineering

Path handling #

CSRF #

CSRF protection has three layers, each answering a different question:

All three are combined with logical AND at the actual check: session cookies on, and CSRF resolved-enabled for the vhost, and this route requires it. Turning any one off is enough to skip both injection and validation for that scope.

Where the token gets filled in

Two independent mechanisms fill {{ csrf_token }} into HTML, and either can apply to the same response:

• The CSRF-specific mechanism — always active on proxied responses once session_cookie + CSRF are on for the vhost, regardless of tag_proxyauth.
• The tag_proxyauth mechanism — also fills {{ csrf_token }}, on top of {{ username }}/{{ proxyauth_version }}/{{ proxyauth_id }}, on both static files and proxied responses — see Dynamic tags. It also respects tag_csrf_token: off means the tag is left as literal text there too.

Error pages

Applies when session_cookie is on. Errors are embedded in an HTML comment block for the page to reveal:

<!-- BEGIN_BLOCK_ERROR -->
<!--
  <div id="error_display">
    {{ error }}
  </div>
-->
<!-- END_BLOCK_ERROR -->

On a login failure, ProxyAuth uncomments this block and fills {{ error }} in — on a success, the block stays commented out and invisible. The page this happens to is resolved the same vhost-aware way any other request is routed (see How a route is matched) — critical on a multi-vhost instance, where more than one vhost commonly has its own route at the exact same path.

Password reset & first-login forced change #

Two related but distinct flows, both landing on the same page_change_password page with a single-use token.

Admin-initiated reset

proxyauth reset-password --username alice [--vhost app.example.com] generates a single-use, time-limited link and emails it via smtp. Alice's current password keeps working until she actually follows the link and sets a new one — this doesn't lock her out immediately, it just gives her a way back in without needing the old password.

Forced change on first login

An account created with must_change_password: true — typically right after an admin sets a temporary password — is redirected to page_change_password on its very next successful login, instead of getting a normal session. The flag clears automatically the moment a new password is actually set.

Logging #

Compression #

gzip, deflate and brotli, negotiated per request via Accept-Encoding. Configurable per route — algorithm, level, minimum size before compressing.

routes:
  - prefix: "/"
    target: "http://127.0.0.1:8000"
    compression:
      algorithm: "br"
      level: 5
      min_size: 1024

Custom response headers #

Arbitrary headers — CSP, HSTS, X-Frame-Options, or anything else — added to every response a route produces, proxied and static alike.

routes:
  - prefix: "/"
    target: "http://127.0.0.1:8000"
    headers:
      Content-Security-Policy: "default-src 'self'; script-src 'self' 'unsafe-inline'"
      Strict-Transport-Security: "max-age=63072000; includeSubDomains"
      X-Frame-Options: "DENY"

Also settable on a vhosts: group — a route's own headers is merged with its group's, not replaced by it: the route's own entries win only on a key both define. Lets you set something like HSTS once for a whole vhost, then override just one header on a specific route.

Dynamic tags in pages #

Four template tags, substituted server-side in static files and proxied responses alike, gated per route by tag_proxyauth: true.

Both a spaced ({{ username }}) and unspaced ({{username}}) form are recognized for every tag.

tag_proxyauth: why it's opt-in

Off by default, and — unlike most per-route settings — not inherited-then-defaulted-on anywhere. Substitution means reading the whole response body as text and scanning it on every matching request; a route that doesn't use any of these tags shouldn't pay that cost for nothing. Only text/html responses are scanned even when it's on.

A login page served entirely as static files

vhosts:
  - vhost: ["app.example.com"]
    login_redirect_url: "/app"
    routes:
      - prefix: "/"
        static: "/var/www/app/public/"
        static_index: "login.html"
        tag_proxyauth: true
      - prefix: "/app"
        static: "/var/www/app/secret/index.html"
        required_login: true

<p>{{ username }}</p>

<form method="POST" action="/auth">
  <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
  <input type="text" name="username">
  <input type="password" name="password">
  <button type="submit">Sign in</button>
</form>

<footer>v{{ proxyauth_version }}</footer>

For a first-time visitor: {{ username }} is left as literal text (nobody to greet), {{ csrf_token }} is filled in with a real token so the login form actually works, {{ proxyauth_version }} resolves regardless of login state.

Anti-Replay #

An opt-in request-signing layer, separate from the base token model — protects against a captured, otherwise-valid request being resent later by an attacker who doesn't have the signing key itself.

Each signed request carries a timestamp and a nonce; ProxyAuth rejects anything outside the accepted time window, or any nonce it's already seen — a captured request can't simply be replayed even by someone who intercepted it in full.

Caching #

Client certificates (mTLS to the backend) #

ProxyAuth can present its own client certificate when connecting to a backend that requires mutual TLS — the backend authenticates ProxyAuth itself, independent of whatever authenticates the original visitor.

routes:
  - prefix: "/secure-api"
    target: "https://internal-service:8443"
    cert:
      file: "/etc/proxyauth/certs/client.p12"
      password: "..."

Connections to the same backend are pooled and reused across requests rather than renegotiating TLS every time — the pool is keyed by target and certificate together, so two routes pointing at the same backend with different client certificates each get their own pool, never accidentally sharing a connection authenticated as the wrong identity.

Egress proxy #

Route a proxied request through another HTTP proxy before it reaches the real target — for a backend only reachable through a corporate egress proxy, for instance.

Load balancing (backends) #

A route can point at several backends instead of one, weighted round-robin, with automatic failover — a request that times out against one backend is retried against the next, not dropped.

routes:
  - prefix: "/api"
    backends:
      - url: "http://10.0.0.1:8000"
        weight: 2
      - url: "http://10.0.0.2:8000"
        weight: 1
      - url: "http://10.0.0.3:8000"
        weight: -1   # failover only — never gets traffic unless the others are all down

A backend that times out is put on a short cooldown rather than being retried immediately on every subsequent request — avoiding a thundering-herd of failed attempts against something that's genuinely down.

Filters (fine-grained request matching) #

ACL rules evaluated before forwarding — every condition in allow must match for the request to proceed, checked against method, path, headers, query parameters, or the request body itself.

routes:
  - prefix: "/webhook"
    target: "http://127.0.0.1:9000"
    filters:
      default_allow: false
      allow:
        - method: "POST"
          header:
            X-Webhook-Secret: "expected-value"

Database-backed users #

An alternative to hand-editing users in config.json — accounts live in PostgreSQL or MySQL instead, shared automatically across every instance pointed at the same database. File-based and database-backed accounts coexist freely; a request is checked against both.

"databases": {
  "kind": "postgres",
  "url": "postgres://user:pass@localhost/proxyauth",
  "connect_timeout_secs": 5,
  "refresh_interval_secs": 30,
  "incremental_window_secs": 300
}

Schema

Six tables: users (username, password hash, otpkey, timestamps, a soft-delete flag, must_change_password), plus user_allow, user_roles, groups/user_groups, and user_email for the one-to-many fields — mirroring the file-based User object's shape exactly, so the two backends behave identically from the application's point of view.

Sync model: incremental scan + full scan

Two scans run on independent timers, at different costs:

A deleted account is only ever concluded from a genuinely fresh full-table read, never from a cache — see below.

Local fallback cache

A local LMDB cache mirrors the last successful full read, purely as a startup/outage resilience layer — consulted only when the real database can't be reached at all, never part of the normal read path otherwise. Read-only from the application's point of view for almost everything: db-add-user/db-delete-user always require a live connection and refuse outright if the database is unreachable, rather than writing to the cache instead. The one exception is TOTP enrollment/reset, which patches just the affected user's otpkey in the cache immediately — see Database-backed TOTP for why that specific case needed an exception.

Managing users via the CLI

$ proxyauth db-add-user --username alice --password '...' --roles admin --groups ops
$ proxyauth db-delete-user --username alice
$ proxyauth db-sync-cache        # force an immediate full scan
$ proxyauth db-restore-from-cache  # rebuild in-memory state from the LMDB cache
$ proxyauth db-clear-cache

Database-backed TOTP #

TOTP enrollment and reset now work identically whether an account lives in config.json or in a shared PostgreSQL/MySQL database — the same two routes detect automatically which one a given user actually belongs to.

Two storage backends, two ways of staying in sync

Both problems come from the same root cause — the running server keeps its own in-memory view of accounts, and a raw write to storage doesn't update that view by itself — but each backend solves it differently:

The LMDB fallback cache

Database-backed accounts have a third layer behind the two above: a local LMDB cache that stands in for the real database if it's ever unreachable — most importantly, right at startup. This cache is only a resilience fallback, not part of the normal read path. But an enrollment or reset patches it immediately alongside the real database write, specifically so a database outage occurring shortly afterward can't cause ProxyAuth to fall back to a stale, since-replaced secret.

Self-service re-enrollment #

/adm/auth/totp/get normally refuses to hand out a new secret to an account that already has one — even with the correct password — specifically so a stolen password alone can't be used to silently take over someone's second factor. allow_totp_reenroll: true on a vhost removes that restriction: a user with a working username/password gets a brand-new TOTP secret in one request, no admin, no prior /adm/auth/totp/reset call.

vhosts:
  - vhost: ["internal-tool.example.com"]
    allow_totp_reenroll: true

What this costs you

TOTP stops protecting against a stolen or guessed password the way two-factor authentication is meant to, for any account on a vhost where this is on. Whoever currently holds the password also controls the second factor — they can silently re-enroll their own authenticator app, and the legitimate user's old one just stops working, with no built-in notification.

Meant for specific low-stakes vhosts where the operational cost of admin-mediated resets outweighs the reduced protection — not a default worth reaching for generally.

Local stats socket #

proxyauth stats reads live stats directly from the running instance over a local Unix domain socket — no HTTPS round-trip, no admin token needed for this specific, local-only path.

$ proxyauth stats

requests/sec (last):  42
avg req/sec (10s):     38.50
avg req/sec (60s):     35.20
total requests:        918273
active sessions:       7
uptime:                1d 1h 2m 03s

SSO across multiple instances #

Since token construction depends on per-build constants, not just secret, two independently-built ProxyAuth instances don't validate each other's tokens by default — even with identical config.json. sync export/sync import is how a fleet of instances is made to agree on the same constants, achieving real single-sign-on across them.

How it works

1. On the source instance, sync export generates a fresh OpenPGP certificate (via Sequoia), encrypts its own private key material with a passphrase derived from that instance's config.json secret, and writes it to key.asc. It then encrypts its own current build constants — version, build time, build random value, two build seeds, a build epoch, an HKDF salt, and the shuffle order — into data.pgp, addressed to that same certificate.
2. Both files are transferred to the target instance (out of band — scp, a shared volume, however you'd move any other secret).
3. On the target instance, sync import uses its own (matching) secret to unlock key.asc's private key, then decrypts data.pgp with it.
4. The decrypted build constants overwrite the target instance's own, in a runtime-mutable global — not a compile-time constant, despite originating from one. From that point on, this instance builds and verifies tokens exactly as the source instance would.

$ proxyauth sync export
Key export Success (secret key encrypted with AppConfig password)
# produces ./key.asc and ./data.pgp

$ proxyauth sync

CLI reference #

Every proxyauth subcommand switches to run_user automatically (reading it from config.json while still root) — the command itself still needs to be launched as root so that switch is possible.

Setup & lifecycle

Database-backed users

Accounts & access

TLS & certificates

Operations

Admin routes reference #

Every /adm/* route requires X-Auth-Token: <token_admin> and is not rate-limited — the admin token is the only protection, so treat it like a root credential.