One instance. Many vhosts.
Each with its own rules.

Installation #

One script, twelve steps, on Debian, Ubuntu, Alpine, Arch or Fedora. It compiles ProxyAuth from source on your own machine, verifies what it downloaded before touching it, and runs the result as an unprivileged system account. Everything it does is listed below.

$ curl -fsSLO https://proxyauth.app/install.sh
$ less install.sh
$ sudo sh install.sh

The script re-executes itself under sudo if you start it as a normal user, so sh install.sh alone also works. A full transcript is written to /tmp/proxyauth-install.log as it goes.

What it does, in order

Everything it writes

The complete list. Nothing outside these paths is modified.

How it runs afterwards

The service unit is deliberately narrow. ProxyAuth does not run as root.

Before you go to production

The install leaves a working instance; three things are then yours to set.

Quick start #

Two paths to a working instance, both starting from an installed host. Pick the one matching where you are deploying — the plain-HTTP path is for a local machine or a network you already trust, the TLS path is what you want anywhere a browser will actually reach it.

$ sudo proxyauth prepare

{
  "secret": "a-random-value-of-at-least-64-characters-generated-not-typed",
  "token_expiry_seconds": 3600,
  "host": "127.0.0.1",
  "port": 8080,
  "tls": false,
  "session_cookie": true,
  "users": [
    {
      "username": "alice",
      "password": "changeme",
      "roles": ["admin"]
    }
  ]
}

vhosts:
  - vhost: ["localhost"]
    login_redirect_url: "/app"
    routes:
      - prefix: "/"
        static: "/var/www/app/public/"
        static_index: "login.html"
        tag_proxyauth: true
        cache: false

      - prefix: "/app"
        target: "http://127.0.0.1:8000"
        required_login: true

$ sudo systemctl enable --now proxyauth
$ curl -I http://localhost:8080/

$ sudo proxyauth routes-audit
$ sudo proxyauth check-access --username alice

$ sudo proxyauth prepare

{
  "secret": "a-random-value-of-at-least-64-characters-generated-not-typed",
  "token_expiry_seconds": 3600,
  "host": ["0.0.0.0", "::"],
  "port": 443,
  "tls": true,
  "session_cookie": true,
  "max_age_session_cookie": 3600,
  "csrf_token": true,
  "run_user": "proxyauth",
  "letsencrypt": {
    "contact_email": "ops@example.com",
    "renew_before_days": 30
  },
  "users": [
    {
      "username": "alice",
      "password": "changeme",
      "roles": ["admin"]
    }
  ]
}

vhosts:
  - vhost: ["app.example.com"]

    # ── TLS ──────────────────────────────────────────────
    vhost_cert:
      cert: "/etc/proxyauth/cert/app.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/app.example.com/privkey.pem"
    certbot_renew: true

    # ── session policy ───────────────────────────────────
    session_cookie: true
    tag_csrf_token: true
    login_redirect_url: "/app"
    logout_redirect_url: "/"

    routes:
      - prefix: "/"
        static: "/var/www/app/public/"
        static_index: "login.html"
        tag_proxyauth: true
        cache: false

      - prefix: "/app"
        target: "http://127.0.0.1:8000"
        required_login: true
        forward_proxy_headers: true
        headers:
          Strict-Transport-Security: "max-age=63072000; includeSubDomains"

$ sudo proxyauth certbot new app.example.com
$ sudo proxyauth certbot check app.example.com

$ sudo systemctl enable --now proxyauth
$ curl -I https://app.example.com/
$ sudo proxyauth routes-audit
$ sudo proxyauth check-access --username alice

Concepts & vocabulary #

Six terms used consistently throughout this documentation. Getting them straight makes the rest of the reference read much faster.

Where each setting lives

Three scopes, from broadest to narrowest. A narrower scope always overrides a broader one. Every reference section in this documentation is marked with the file and the level its fields belong to, so you never have to infer it from context.

Release highlights — v1.2.2 #

Nine additions, all opt-in. An existing routes.yml and config.json keep working unchanged until you reach for one of them.

Added in 1.2.1 and later

Which setup am I? #

Pick by what sits behind the proxy and who talks to it.

The three decisions every setup makes

Whatever you pick, you are answering the same three questions. Knowing that makes the recipes below read as variations rather than seven unrelated things.

Gate one app behind a login page #

The most common deployment by a wide margin: an internal tool, a dashboard, a legacy application with no authentication of its own — put a login in front of it without touching its code.

{
  "secret": "generate-64-random-characters-do-not-type-them-by-hand",
  "token_expiry_seconds": 28800,
  "host": ["0.0.0.0", "::"],
  "port": 443,
  "tls": true,

  "session_cookie": true,
  "max_age_session_cookie": 28800,
  "csrf_token": true,

  "log": { "type": "local" },
  "letsencrypt": { "contact_email": "ops@example.com" },

  "users": [
    { "username": "alice", "password": "temporary", "groups": ["staff"] },
    { "username": "bob",   "password": "temporary", "groups": ["staff"] }
  ]
}

vhosts:
  - vhost: ["tool.example.com"]

    vhost_cert:
      cert: "/etc/proxyauth/cert/tool.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/tool.example.com/privkey.pem"
    certbot_renew: true

    # Who may log in on this vhost at all.
    allow_groups: ["staff"]

    session_cookie: true
    login_redirect_url: "/app"
    logout_redirect_url: "/"

    routes:
      # The login page, public by definition — nobody can log in
      # through a page that requires being logged in.
      - prefix: "/"
        static: "/var/www/login/"
        static_index: "login.html"
        tag_proxyauth: true
        cache: false

      # The application itself.
      - prefix: "/app"
        target: "http://127.0.0.1:8000"
        required_login: true
        forward_proxy_headers: true

The login page

A plain HTML file. tag_proxyauth: true on that route is what fills the CSRF field in; without it the tag stays as literal text and every submission is rejected.

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

What to change

• tool.example.com and the two certificate paths — three places.
• http://127.0.0.1:8000 to wherever your app listens.
• The accounts. Passwords written in plaintext are hashed in place with Argon2id on first startup.

Protect an API #

No browser, no cookie, no login page. A client posts credentials once to /auth, gets a token back as JSON, and sends it on every subsequent request.

{
  "secret": "generate-64-random-characters-do-not-type-them-by-hand",
  "token_expiry_seconds": 3600,
  "host": ["0.0.0.0"],
  "port": 443,
  "tls": true,

  "session_cookie": false,
  "csrf_token": false,

  "ratelimit_auth":  { "requests_per_second": 2,   "burst": 5,   "block_delay": 5000 },
  "ratelimit_proxy": { "requests_per_second": 200, "burst": 400, "block_delay": 200 },

  "log": { "type": "local" },
  "letsencrypt": { "contact_email": "ops@example.com" },

  "users": [
    { "username": "ci-runner",  "password": "temporary", "roles": ["ci"] },
    { "username": "partner-01", "password": "temporary", "roles": ["partner"] }
  ]
}

vhosts:
  - vhost: ["api.example.com"]

    vhost_cert:
      cert: "/etc/proxyauth/cert/api.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/api.example.com/privkey.pem"
    certbot_renew: true

    allow_roles: ["ci", "partner"]
    session_cookie: false

    routes:
      # Read-only, open to every authenticated client.
      - prefix: "/v1"
        target: "http://127.0.0.1:8000"
        required_login: true
        allow_methods: ["GET", "HEAD"]
        forward_proxy_headers: true

      # Writes, restricted to CI and coming only from the build network.
      - prefix: "/v1/deploy"
        target: "http://127.0.0.1:8000"
        required_login: true
        roles: ["ci"]
        allow_ips: ["10.20.0.0/16"]
        allow_methods: ["POST"]

      # Health check: no auth, no logging, no caching.
      - prefix: "/healthz"
        target: "http://127.0.0.1:8000"
        required_login: false
        log: false
        cache: false

How a client uses it

$ TOKEN=$(curl -s -X POST https://api.example.com/auth \
      -d 'username=ci-runner&password=...' | jq -r .token)

$ curl https://api.example.com/v1/builds -H "Authorization: Bearer $TOKEN"

Public site, private admin #

One domain, one backend, two audiences. Everyone reads the site; a few people reach /admin. The only difference between the two routes is required_login.

vhosts:
  - vhost: ["www.example.com", "example.com"]

    vhost_cert:
      cert: "/etc/proxyauth/cert/example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/example.com/privkey.pem"
    certbot_renew: true

    allow_groups: ["editors"]
    session_cookie: true
    login_redirect_url: "/admin"

    headers:
      Strict-Transport-Security: "max-age=63072000; includeSubDomains"

    routes:
      # Everything public. Compressed, cached, no session needed.
      - prefix: "/"
        target: "http://127.0.0.1:8000"
        required_login: false
        forward_proxy_headers: true
        compression:
          enabled: true
          algorithm: "br"
          min_size: 1024
        cache: true
        cache_duration_secs: 600

      # The login form, served from disk.
      - prefix: "/login"
        static: "/var/www/login/"
        static_index: "login.html"
        tag_proxyauth: true
        cache: false

      # The admin area. Longest prefix wins, so this beats "/" above.
      - prefix: "/admin"
        target: "http://127.0.0.1:8000"
        required_login: true
        groups: ["editors"]
        cache: false
        headers:
          X-Frame-Options: "DENY"

Several domains on one instance #

This is what ProxyAuth is built around. Each vhost gets its own certificate, its own session policy, its own login rules, its own mail server — sharing nothing but the process.

vhosts:
  # ── Internal tool: strict. TOTP required, short sessions. ──
  - vhost: ["internal.example.com"]
    vhost_cert:
      cert: "/etc/proxyauth/cert/internal.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/internal.example.com/privkey.pem"
    certbot_renew: true

    allow_groups: ["staff"]
    exclude_users: ["contractor-temp"]

    session_cookie: true
    login_via_otp: true
    max_age_session_cookie: 1800
    login_redirect_url: "/app"

    routes:
      - prefix: "/"
        static: "/var/www/internal-login/"
        static_index: "login.html"
        tag_proxyauth: true
        cache: false
      - prefix: "/app"
        target: "http://127.0.0.1:8000"
        required_login: true

  # ── Customer portal: its own mail server, longer sessions. ──
  - vhost: ["portal.customer.tld"]
    vhost_cert:
      cert: "/etc/proxyauth/cert/portal.customer.tld/fullchain.pem"
      key: "/etc/proxyauth/cert/portal.customer.tld/privkey.pem"
    certbot_renew: true

    allow_groups: ["customers"]

    session_cookie: true
    max_age_session_cookie: 86400
    login_redirect_url: "/"
    page_change_password: "https://portal.customer.tld/new-password.html"
    cors_origins: ["https://portal.customer.tld"]

    smtp:
      host: "smtp.customer.tld"
      port: 587
      username: "noreply@customer.tld"
      password: "..."
      from: "Portal <noreply@customer.tld>"
      timeout_secs: 10

    routes:
      - prefix: "/"
        target: "http://127.0.0.1:9000"
        required_login: true
        forward_proxy_headers: true

Hand identity to an app that speaks OIDC #

Grafana, Nextcloud, GitLab — anything with its own user model and native OIDC support. Instead of gating it from outside, ProxyAuth becomes its identity provider, and the app manages its own sessions and permissions.

vhosts:
  - vhost: ["grafana.example.com"]

    vhost_cert:
      cert: "/etc/proxyauth/cert/grafana.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/grafana.example.com/privkey.pem"
    certbot_renew: true

    allow_groups: ["staff"]

    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"
      logout_redirect_uris:
        - "https://grafana.example.com/login"
      scopes: ["openid", "profile", "email"]

    routes:
      # No required_login here — the backend decides.
      - prefix: "/"
        target: "http://127.0.0.1:3000"

Generate the signing key once, before starting, and set the app up against the six endpoints:

$ openssl genrsa -traditional -out /etc/proxyauth/oidc/signing_key.pem 2048
$ chmod 600 /etc/proxyauth/oidc/signing_key.pem
$ chown proxyauth /etc/proxyauth/oidc/signing_key.pem
$ curl https://grafana.example.com/.well-known/openid-configuration

Spread the load across several backends #

Replace target with backends. Weighted round-robin, automatic failover, and a cooldown on anything that times out.

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

    allow_groups: ["staff"]
    session_cookie: true

    routes:
      - prefix: "/"
        required_login: true
        forward_proxy_headers: true
        backends:
          # Two equal workers.
          - url: "http://10.0.0.1:8000"
            weight: 1
          - url: "http://10.0.0.2:8000"
            weight: 1
          # A bigger machine, twice the share.
          - url: "http://10.0.0.3:8000"
            weight: 2
          # Cold standby: no traffic unless all three above are down.
          - url: "http://10.0.9.9:8000"
            weight: -1

Close the doors for a deployment #

Add one block to a vhost, reload, and everyone but you gets a maintenance page. Remove it afterwards. routes.yml reloads live, so neither step needs a restart.

vhosts:
  - vhost: ["app.example.com"]

    redirect_protect:
      allow_ip:
        - "203.0.113.42"     # you
        - "10.0.0.0/8"       # the office
      path: "/var/www/maintenance/index.html"

    # ...the rest of the vhost, unchanged
    allow_groups: ["staff"]
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8000"
        required_login: true

Blocked visitors get the file at path with a 503. It is read fresh on every request, never cached, so editing the page takes effect immediately. Leave allow_ip empty for a genuine maintenance-for-everyone — there is no need to spell out a catch-all.

Request lifecycle #

The order in which checks run is part of the contract. It tells you what each mechanism protects, and where in the chain a given setting takes effect.

Three properties this ordering provides:

• IP blocklists run before everything. A blocked address never reaches route matching, authentication, or CSRF — so nothing downstream can be used to bypass it.
• Certificate renewal is never gated. ACME challenge handling sits ahead of maintenance mode, so putting a vhost into maintenance cannot lock you out of renewing its certificate.
• Admin endpoints are not rate-limited. /adm/* is protected by token_admin alone. Treat that token as a root credential.

Routing & route matching #

Every incoming request is matched against routes.yml in a fixed order. Regex routes are tried in file order; prefix routes are tried longest first, whatever their position. Knowing which rule applies to which kind is all it takes to predict where a request lands.

Evaluation order

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

Within that order, a route only matches if its vhost list also matches the request's Host header — or if the route declares no vhost at all, making it a catch-all. See Virtual hosts.

Prefix matching, precisely

A request path matches a route's prefix if it is an exact match, or if it starts with the prefix followed by /. So 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.

Tokens & sessions #

Everything cryptographic about a token — key derivation, sealing, the signature, the optional obfuscation pass — lives in the zerocrypt library. ProxyAuth's job is to map its configuration and its build constants onto one process-wide vault at startup. That vault is immutable afterwards and Send + Sync, so every worker shares one instance with no lock and no cache on the request path.

Two secrets, not one

The vault is built from your secret plus a build key derived from constants baked into the binary at compile time. Both are required — this is what makes sync export/sync import necessary for a multi-node deployment rather than simply copying secret across.

All of it is folded into a single 32-byte key through BuildKey::derive, under the domain string proxyauth.token.v1 — so two callers feeding identical material into the same library still get unrelated keys. The parts are length-prefixed inside the derivation, so no rearrangement of them can collide with another.

The obfuscation pass

fast decides whether an extra obfuscation pass runs on top, keyed by a build seed. Read once at startup rather than on every request.

The verification cache

The vault keeps up to 50 000 successfully verified tokens. The bound is deliberate: the cache key is a live token, and an unbounded map keyed by attacker-supplied strings is a memory-exhaustion primitive. At roughly 300 bytes an entry that is a few megabytes, and a deployment with more live sessions than that sees a lower hit rate rather than unbounded growth.

What the cache does not cover

This is the part that matters operationally. The cache stores only successful verifications and re-checks expiry on every hit. It knows nothing about revocation, user lookup, or the expiry policy — and those three are re-checked after every vault call, cached or not:

The practical consequence: revoking a token, editing a user, or lowering token_expiry_seconds all take effect immediately, rather than when a cache entry ages out.

Server & networking #

config.json is read once at startup. With the sole exception of each user's otpkey (see TOTP enrollment), changes require a service restart — unless the equivalent setting is one of the nine per-vhost overrides, which apply live as soon as routes.yml is reloaded.

Authentication & sessions #

Every field in this section can also be set per vhost, overriding the global default for that vhost alone — see Per-vhost overrides. What follows is the fallback a vhost uses when it sets nothing of its own.

Password reset & SMTP

Rate limiting #

ratelimit_auth and ratelimit_proxy share the same three keys, applied independently to /auth traffic and to proxied traffic. A burst of bad login attempts cannot drown out real API traffic, or the reverse.

"ratelimit_auth": {
  "requests_per_second": 5,
  "burst": 10,
  "block_delay": 1000
},
"ratelimit_proxy": {
  "requests_per_second": 200,
  "burst": 400,
  "block_delay": 200
}

Requests within the limit pass straight through; anything over the burst receives a clean 429, not a dropped connection.

Scaling & shared storage #

What a single instance needs in order to behave consistently as one of several.

Sharing accounts is not the same as sharing token validity. Two instances with the same databases block still reject each other's tokens until their build constants agree — see SSO across instances.

Let's Encrypt & ACME #

Global settings shared by every vhost that opted into automatic renewal with certbot_renew: true. One check interval, one renewal threshold, one ACME account for the whole instance. The key is letsencrypt; acme is still accepted as an alias, matching the feature's original name.

"letsencrypt": {
  "check_interval_secs": 3600,
  "renew_before_days": 30,
  "directory_url": "https://acme-v02.api.letsencrypt.org/directory",
  "contact_email": "ops@example.com",
  "account_credentials_path": "/etc/proxyauth/acme/account.json"
}

The port 80 listener

Let's Encrypt always fetches http://{vhost}/.well-known/acme-challenge/{token} over plain HTTP on port 80, and that is not configurable on their end. A TLS-only deployment — everything real on 443, nothing listening on 80 — could therefore never complete a renewal without something answering there. ProxyAuth handles this itself rather than making you run a second web server for it.

Operational settings #

The User object #

One entry in the users array. The database schema mirrors this shape exactly, so file-based and database-backed accounts behave identically from the application's point of view.

Core route fields #

Every route needs exactly one content source — a proxied backend or a static file on disk — 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 is a catch-all: it matches any Host header, the 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 purely an authoring convenience. It is flattened into plain routes right after parsing, so nothing downstream — routing, TLS SNI resolution, the CLI audit tools — knows the form exists. Each route inherits the group's vhost, vhost_cert, certbot_renew and every per-vhost override, unless it sets its own. Mixing both styles in one file is fine, and a route inside a group can still override the group's values.

Per-vhost overrides #

Nine settings that were global-only in config.json can be set on a vhosts: entry in routes.yml instead, letting different domains on the same instance behave completely differently. A vhost that sets none of them falls through to the global default, so nothing changes for a vhost that does not need them.

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"

Login authorization #

An earlier, different gate from the route-level username, groups and roles fields, which only govern what an already logged-in visitor can reach. This one decides whether a login attempt on a given vhost's /auth succeeds at all, before any session or route access 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"

Anyone in the ops group or holding the admin role can log in — except toto, even if toto is also in ops or holds that role.

Overview & flow #

A vhost with an oidc: block turns ProxyAuth into a genuine OpenID Connect provider for the backend behind it. The backend — Grafana, Nextcloud, GitLab, anything that natively speaks OIDC as a relying party — receives a real, independently verifiable id_token via the standard authorization code flow, instead of relying on ProxyAuth's header injection or session cookie.

What changes on an OIDC-enabled vhost

ProxyAuth's own auth machinery steps aside entirely — not just required_login, but CSRF validation and injection, the Authorization header forwarding decision, and route-level username, groups and roles access control too, since none of them mean anything once the backend handles its own auth. Left unchecked, that last one specifically could reject a session the OIDC flow itself just correctly established, if the route happens to carry an unrelated groups: restriction from before it went OIDC-enabled.

This includes the global /auth and /logout endpoints that every other vhost gets: here, both proxy straight through to the backend, exactly like any other path. A relying party like Grafana has its own native login and logout UI, and it is that UI visitors reach on this vhost.

The six endpoints

What ProxyAuth does still serve on this vhost, all intercepted ahead of normal routing:

Every endpoint except discovery lives under /oidc/ — kept visually and structurally distinct from whatever the backend serves at its own root, rather than fixed names like /token sitting in the same namespace as the backend's own routes. Discovery is the one exception, fixed at the root by RFC 8414 rather than by ProxyAuth's choice. Every other path on this vhost proxies straight through, untouched.

A user still authenticates the normal way

Nothing about how someone proves who they are changes — still ProxyAuth's own account store, file or database, with the same credential and TOTP verification as everywhere else. What changes is when and how it is communicated: the login step happens directly at /oidc/authorize, both rendering the form on GET and processing its submission on POST, rather than detouring through the global /auth. The proof that reaches the backend at the end is a signed token instead of a header or cookie.

The full flow

The login step only happens once per session. A returning visitor with a still-valid ProxyAuth session goes straight from GET /oidc/authorize to the redirect-with-code, with no login form in between.

Configuration #

One oidc: block per vhost, registering exactly one relying party. Deliberately one client per vhost rather than a list: ProxyAuth's model is already one vhost, one backend everywhere else, and matching that keeps the block answering a single question — which backend, at which callback URL, may 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"
      logout_redirect_uris:
        - "https://grafana.example.com/login"
      scopes: ["openid", "profile", "email"]
      login_page: "/etc/proxyauth/pages/login.html"
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:3000"

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, so no length or memorability constraints apply — then hash it with Argon2id the way ProxyAuth hashes everything else. There is no dedicated CLI command for this yet; until there is, any small script using the same argon2 crate 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 speaking standard OIDC configures against the same URLs. Most need only the discovery URL and auto-configure the rest. Grafana wants each one spelled out:

[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/oidc/authorize
token_url = https://grafana.example.com/oidc/token
api_url = https://grafana.example.com/oidc/userinfo
redirect_uri = https://grafana.example.com/login/generic_oauth
allow_sign_up = true
signout_redirect_url = https://grafana.example.com/oidc/end-session

allow_sign_up = true matters the first time any given account signs in — without it, Grafana refuses to create a local account for an identity it has not seen before, even though the OIDC handshake succeeded.

Verifying

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

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

Endpoint reference #

Each check below is enforced in the order given. Every 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 in one LMDB read-write transaction — the same fix applied to ProxyAuth's own password-reset tokens after a real race condition was found there. Deliberately short-lived at 120 seconds: enough for the immediate browser redirect and the server-to-server exchange, not for anything else.

Token verification, precisely

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

Signing key setup #

The RSA keypair that signs every id_token is generated externally, once, before ProxyAuth ever starts with oidc: enabled anywhere. It is not something ProxyAuth generates for itself.

$ openssl genrsa -traditional -out /etc/proxyauth/oidc/signing_key.pem 2048
$ chmod 600 /etc/proxyauth/oidc/signing_key.pem
$ chown <run_user> /etc/proxyauth/oidc/signing_key.pem

ProxyAuth only ever reads this file, never generates or rewrites it. If it is missing, or its permissions are not exactly 600, ProxyAuth refuses to start with a clear message giving these same commands rather than a stack trace.

Every OIDC-enabled vhost currently shares this one key. There is no per-vhost key rotation or support for multiple simultaneous keys yet.

Customizing the login page #

The built-in login form is unstyled but fully functional — nothing needs configuring to get OIDC working. Setting oidc.login_page swaps it for a static HTML file rendered with three context-specific tags, in addition to the general-purpose tags covered in Dynamic tags.

Same form, your own branding

<!DOCTYPE html>
<html><body>
  <img src="/logo.svg">
  {{ form }}
</body></html>

Two-step UX, one form and one POST underneath

<form method="POST" action="{{ auth_action }}">
  <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
  <input type="text" name="username">
  <input type="password" name="password">
  <button type="button" onclick="showTotp()">Next</button>

  <div id="totp-step" style="display:none">
    {{ form_totp }}
    <button type="submit">Sign in</button>
  </div>
</form>
<script>
function showTotp() { document.getElementById('totp-step').style.display = 'block'; }
</script>

TOTP is still verified alongside username and password in one request server-side. The reveal is presentation only, not a separate login step ProxyAuth is aware of.

Logging out #

The global /logout proxies through to the backend on an OIDC-enabled vhost, the same as /auth. Ending a ProxyAuth session therefore needs its own dedicated endpoint, advertised as end_session_endpoint in the discovery document, implementing RP-Initiated Logout.

GET /oidc/end-session
    ?post_logout_redirect_uri=https://grafana.example.com/login
    &state=abc123

ProxyAuth clears its own session cookie unconditionally. If post_logout_redirect_uri is present and matches logout_redirect_uris exactly, the browser is redirected there with state echoed back. If it is absent entirely, ProxyAuth falls back to the first entry in logout_redirect_uris — so a backend's sign-out configuration can point at /oidc/end-session with no query string at all and still land somewhere sensible. A present-but-unrecognized URI shows a plain confirmation page instead of guessing.

[auth.generic_oauth]
signout_redirect_url = https://grafana.example.com/oidc/end-session

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.

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 it.

The decision is a single function, not a boolean — it reports why access was granted: by username, by a named group, by a named role, or because the route is open. That is what lets routes-audit and check-access explain themselves, and it guarantees those tools cannot drift from what the proxy actually enforces, since both call the same code.

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

Maintenance mode #

redirect_protect is a different kind of gate from access control: it runs before authentication is even considered, as early in request handling as possible — after IP blocklisting and ACME challenge handling, before everything else. It is not about who is logged in, but about who reaches this route's real content at all right now.

vhosts:
  - vhost: ["app.example.com"]
    redirect_protect:
      allow_ip: ["203.0.113.42"]
      path: "/var/www/maintenance/index.html"
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8000"

Admin bypass — the classic use

redirect_protect:
  allow_ip:
    - "203.0.113.42"      # a single admin IP
    - "10.0.0.0/8"        # or a whole office network
  path: "/var/www/maintenance/index.html"

Fetched allow and deny lists

Allowing an externally published range instead of listing every IP by hand — a team's dynamic VPN egress list, say — with a separate feed excluding one address from it:

redirect_protect:
  allow_url_ips:
    source: "https://vpn.example.com/egress-ips.txt"
  deny_url_ips:
    source: "https://example.com/known-compromised.txt"
  path: "/var/www/maintenance/index.html"

Set redirect_protect_refresh_interval_secs globally to control how often every route's sources are re-fetched. 0 fetches once at startup only.

Proxied maintenance page

redirect_protect:
  allow_ip: ["203.0.113.42"]
  target: "http://backup-status.example.com"
  path: "/var/www/maintenance/index.html"   # fallback if target is unreachable

Set on a vhosts: group, the gate covers every route under it at once — which is what a maintenance window usually calls for. Set on a single route, it covers that prefix alone.

Session-checked paths #

An IP allow-list is all-or-nothing per route. paths adds a second, independent layer: specific sub-paths, matched by regex, that also require a genuinely valid backend session — verified by asking the backend itself, not by inspecting ProxyAuth's own session_token.

That indirection is deliberate. It works the same way regardless of what the backend's auth scheme actually is, including on an OIDC-enabled vhost where ProxyAuth's session cookie is not the authority to begin with.

redirect_protect:
  allow_ip: ["203.0.113.0/24"]
  redirect_url: "https://git.example.com/user/login"
  paths:
    - regex: '^/[^/]+/[^/]+/src(/.*)?$'
      check_path: "/notifications"
      type_return: "status_code"
      expected_status: 200

For every request whose path matches regex, ProxyAuth issues a real request to this route's own backend at check_path, forwarding the original Cookie header unchanged, and interprets the response the way type_return says to.

JSON field check

A stricter alternative for a backend whose logged-out response happens to also be a 2xx:

paths:
  - regex: '^/billing(/.*)?$'
    check_path: "/api/user"
    type_return: "json"
    expected_field: "authenticated"
    expected_value: "true"

Hidden blocks #

Nested inside a paths entry, hidden_blocks reuses that entry's own check — but instead of redirecting or blocking the whole path on failure, it lets the request through untouched and, once the real response comes back, finds and strips one specific HTML element from it.

redirect_protect:
  paths:
    - regex: '^/dashboard(/.*)?$'
      check_path: "/api/user"
      type_return: "json"
      expected_field: "role"
      expected_value: "admin"
      hidden_blocks:
        - html_tag: '<div id="admin-panel" class="widget">'
          fallback_html: "<p>You don't have permission to view this.</p>"

The check itself is never repeated per element: one backend request per matching paths entry, its result applied to every hidden_blocks rule under it.

CSRF #

Three layers, each answering a different question. All three are combined with logical AND at the actual check — turning any one off is enough to skip both injection and validation for that scope.

The full condition: session cookies on, and CSRF resolved-enabled for the vhost, and this route requires it.

Where the token gets filled in

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

• The CSRF-specific mechanism — always active on proxied responses once session_cookie and CSRF are on for the vhost, regardless of tag_proxyauth.
• The tag_proxyauth mechanism — also fills {{ csrf_token }}, on top of the other three tags, on static files and proxied responses alike. It respects tag_csrf_token too: off means the tag is left as literal text there as well.

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 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 — critical on a multi-vhost instance, where more than one vhost commonly has its own route at the exact same path.

Dynamic tags #

Four template tags, substituted server-side in static files and proxied responses alike, gated per route by tag_proxyauth: true. Both spaced ({{ username }}) and unspaced ({{username}}) forms are recognized.

Why tag_proxyauth is opt-in

Off by default, and — unlike most per-route settings — not inherited-then-defaulted-on anywhere. Substitution reads the whole response body as text and scans it on every matching request, so it is enabled per route, for exactly the content that uses these tags. Only text/html responses are scanned even where it is 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
        cache: false
      - 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 }} stays literal text since there is nobody to greet, {{ csrf_token }} is filled with a real token so the form works, and {{ proxyauth_version }} resolves regardless of login state.

Response headers #

Arbitrary headers — CSP, HSTS, X-Frame-Options, 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 entries win only on a key both define. That lets you set HSTS once for a whole vhost, then override one header on a specific route.

Compression #

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

routes:
  - prefix: "/"
    target: "http://127.0.0.1:8000"
    compression:
      enabled: true
      algorithm: "br"
      min_size: 1024
      max_size: 10485760
      types: ["text/html", "application/json"]

Every field is individually optional, so a route can override just enabled: false — or just algorithm — and inherit the rest from its vhost group, then from the global compression block.

Caching #

Request filters #

Regex conditions evaluated before forwarding, against the method, path, a header, a query parameter, or the request body. Every condition in allow must match — they combine as an AND, not an OR. A request that fails any of them gets a 403.

routes:
  - prefix: "/webhook"
    target: "http://127.0.0.1:9000"
    filters:
      default_allow: false
      allow:
        - field: method
          pattern: "^POST$"
        - field: header
          name: "^x-webhook-secret$"
          pattern: "^expected-value$"

Condition types

default_allow

Load balancing #

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 — no traffic unless the others are all down

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

Forwarding client info #

A backend behind ProxyAuth normally sees ProxyAuth itself as the client — its address, not the real visitor's. forward_proxy_headers: true adds the standard set of headers a backend needs to recover the original request, the same information nginx's proxy_set_header directives provide.

vhosts:
  - vhost: ["app.example.com"]
    forward_proxy_headers: true
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8000"

Client certificates (mTLS) #

ProxyAuth can present its own client certificate when connecting to a backend that requires mutual TLS. The backend authenticates ProxyAuth itself, independently 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 and never accidentally share a connection authenticated as the wrong identity.

Choosing how certificate errors surface

A certificate that cannot be read, or that fails to pair with its key, is handled one of two ways. strict_mtls in config.json picks which.

Path handling #

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.

Groups & roles #

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 listed in username, they belong to an allowed groups entry, or they hold an allowed roles entry. Both are checked against the matching fields on the User object, or the equivalent database columns.

roles vs. groups — a real distinction

roles predates route-level access control and originally did one thing: 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 whether a role matches a route's list is independent of what the backend chooses to do with the header.

groups was added specifically for access control and has no header side effect. Use it when you want a permission grouping that means nothing to the backend, 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

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": {
  "db_type": "postgres",
  "host": "127.0.0.1",
  "port": 5432,
  "db_name": "proxyauth",
  "user": "proxyauth",
  "password": "...",
  "connect_timeout_secs": 5,
  "refresh_interval_secs": 30,
  "incremental_window_secs": 300,
  "full_refresh_interval_secs": 300,
  "deleted_retention_secs": 86400,
  "purge_interval_secs": 3600
}

Schema

Six tables. users carries the username, password hash, otpkey, timestamps, a soft-delete flag and must_change_password. user_allow, user_roles, groups with user_groups, and user_email carry 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

Two scans run on independent timers, at very different costs.

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

Local fallback cache

A local LMDB cache mirrors the last successful full read, purely as a startup and outage resilience layer. It is consulted only when the real database cannot be reached at all, never as part of the normal read path. It is read-only from the application's point of view for almost everything: db-add-user and 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 and reset, which patches the affected user's otpkey in the cache immediately — see TOTP enrollment for why that specific case needed an exception.

Managing users

$ 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 the database from the local cache
$ proxyauth db-clear-cache

TOTP enrollment #

Enrollment and reset work identically whether an account lives in config.json or in a shared database — the same two routes detect automatically which one a given user belongs to.

Two storage backends, two ways of staying in sync

Both backends work around the same constraint: the running server holds its own in-memory view of accounts, and a write to storage does not update that view on its own. Each keeps the two in step differently, and in both cases the change is live without a restart.

Why the fallback cache is patched too

Database-backed accounts have a third layer behind the two above: the local LMDB cache that stands in for the real database if it is ever unreachable, most importantly right at startup. That 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 cannot 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, so that replacing an enrolled second factor requires an administrator. allow_totp_reenroll: true on a vhost removes that restriction: a user with a working username and password gets a brand-new TOTP secret in one request, with no admin and no prior reset call.

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

What changes on that vhost

With this on, the password becomes sufficient to replace the TOTP secret: a holder of valid credentials can enroll a new authenticator in one request, and the previous one stops working. The second factor therefore protects against a device lost or an authenticator app reinstalled, rather than against a password that has been obtained by someone else.

It is scoped to a single vhost, so an instance can offer self-service re-enrollment on an internal tool while keeping admin-mediated resets everywhere else. Where the second factor is meant to hold independently of the password, leave it off and use proxyauth reset-otp.

Password reset #

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 does not lock her out immediately, it gives her a way back in without needing the old password.

Both smtp and page_change_password can be set per vhost. Name --vhost explicitly to use that vhost's own values; this command has no live request to resolve one from automatically. Omit it to use the global default.

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 set.

Logging & observability #

Two settings that look similar and are not. log chooses the transport — where every line the process emits ends up. logging shapes the access line — what a per-request record contains and which requests get one.

The practical consequence of keeping them apart: logging.enabled: false drops access lines while leaving warnings and errors intact, which is what "turn off logging on this endpoint" usually means in practice. log.type: "disabled" silences everything.

Two files, on purpose

The local transport explicitly filters the access-log target out. Without that filter every request would land in both files, since access lines are emitted through the same tracing call as everything else. Keeping "requests" and "everything else" separate is the intent.

Transports — the log block

Grafana Loki

One line to enable, no agent to install and no file to tail — ProxyAuth pushes to Loki itself.

"log": {
  "type": "loki",
  "host": "http://loki.internal:3100"
}

The access line — the logging block

"logging": {
  "enabled": true,
  "format": "[time] [[vhost]] [[ip]] - [method] [status] [path] [request-time]",
  "log_file": "access.log",
  "flush_interval_ms": 500,
  "vhosts": {
    "noisy.example.com": { "enabled": false },
    "portal.example.com": { "log_file": "portal.log" }
  },
  "routes": {
    "/healthz": false
  }
}

Format placeholders

The default:

[time] [[vhost]] [[ip]] - [method] [protocol] [status] [length] [path] [tid:[token-id]] '[user-agent]' '[referer]' [request-time-ns]

Per-route overrides

Stats socket #

proxyauth stats reads live statistics directly from the running instance over a local Unix domain socket — no HTTPS round-trip, and no admin token needed for this 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 instances #

Since token construction depends on per-build constants and not just secret, two independently built instances do not validate each other's tokens by default — even with identical configuration. sync export and sync import are how a fleet is made to agree on the same constants.

$ proxyauth sync export
Key export Success (secret key encrypted with AppConfig password)
# written to the current working directory

$ 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 API reference #

Every /adm/* route requires X-Auth-Token: <token_admin>, with the two TOTP endpoints as documented exceptions.