Any app. Any language.
Authentication it never has to implement.

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 #

Three ways to a working instance, all starting from an installed host. Guided asks a few questions and writes the files for you — the fastest start, and a good way to learn their format. The two manual paths give the complete files to copy: plain HTTP for a local machine or a network you already trust, TLS for anywhere a browser will actually reach it.

$ proxyauth prepare

$ proxyauth quickstart vhost

Quickstart — a vhost and its routes
───────────────────────────────────
      Every question has a default. Press Enter to accept it.
      Nothing is written until you confirm at the end.

[1/6] Which hostname does this vhost answer to?
      hostname(s) (comma separated): tool.example.com
[2/6] TLS
        1) Let's Encrypt — ProxyAuth issues and renews it, nothing else to install
        2) Own certificate — you provide the cert and key paths
        3) None — plain HTTP — local development only
      choice [1]:
[3/6] Who talks to this vhost?
      choice [1]:
[4/6] Who may sign in here?
      groups allowed to log in (comma separated): staff
[5/6] The application behind it
      backend URL [http://127.0.0.1:8000]:
      path it is served at [/app]:
      Require a session to reach it? [Y/n]:
      Send the visitor's real IP and Host to the backend? [Y/n]:
[6/6] The login page
      Serve a login page from disk on /? [Y/n]:
      directory [/var/www/login/]:
      index file [login.html]:

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
    allow_groups: ["staff"]
    session_cookie: true
    tag_csrf_token: true
    login_redirect_url: "/app"
    logout_redirect_url: "/"

    routes:
      # The login page is public by definition — nobody can sign in
      # through a page that already requires being signed in.
      - prefix: "/"
        static: "/var/www/login/"
        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

$ proxyauth quickstart users

$ proxyauth quickstart vhost-access

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

$ proxyauth certbot new tool.example.com
$ systemctl enable --now proxyauth
$ systemctl restart proxyauth        # once, so the new certificate is watched

$ proxyauth routes-audit
$ proxyauth check-access --username alice
$ curl -I https://tool.example.com/app      # 302 to / without a session

{
  "session_refresh_interval_secs": 900,
  "session_refresh_grace_secs": 30
}

$ 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"
    redirect_login_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

$ 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.3.0 #

1.3.0 is about sessions: how they start, how they are kept alive, and how they end. Browsers are sent to the login page instead of receiving a bare 401, active sessions are renewed without signing in again, and every revocation now carries an end date and is cleaned up in memory, LMDB and Redis alike.

Added in 1.3.0

Changed in 1.3.0

Behavior changes worth reading before upgrading. None of them requires a configuration change.

Added in 1.2.7

Added in 1.2.5

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"
    redirect_login_url: "/login"

    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
    session_refresh_interval_secs: 300
    login_redirect_url: "/app"
    redirect_login_url: "/"

    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.

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.
• Only the login page forwards a signed-in visitor. Every other page, public ones included, is served normally. See Login redirect.
• A missing session is not the same as a refused one. No valid session: the page is sent to the login page, an API call gets 401. A valid session without access: 403, and the session stays valid.
• 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. Exact vhosts before wildcard vhosts. Matching runs in two passes: the first considers only routes naming the requested host literally, the second adds routes matching it through a pattern. A host named explicitly anywhere in routes.yml therefore always wins over a pattern that would also cover it. Catch-all routes — an empty vhost — sit in the first pass and keep the rank they have always had.
2. Regex routes — 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.
3. 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.
4. / 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 a token carries

Besides the username, the token id and the expiry, a token carries what ProxyAuth reads back about the session: the account's index, the time the token was issued, the time the session began and, for a token issued by a renewal, the id of the token it replaced. They drive session renewal, session_max_lifetime_secs and the early retirement of a replaced token; the session start is carried over from token to token. Tokens issued before 1.3.0 carry only the index and still validate.

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.

Session renewal #

A session that is being used gets a fresh token at a regular interval, delivered in a new Set-Cookie. The visitor stays signed in without doing anything, the token in their browser keeps changing, and each replaced token stops working shortly after.

Renewal is off by default. Set session_refresh_interval_secs to turn it on — nothing else is required.

{
  "token_expiry_seconds": 3600,
  "session_refresh_interval_secs": 900,
  "session_refresh_grace_secs": 30,
  "session_max_lifetime_secs": 43200
}

All three can be set in config.json, on a vhosts: group, or on a single route; the narrowest scope wins. A vhost can therefore renew sessions every minute while another sets session_refresh_interval_secs: 0.

What happens on a renewal

Where renewal applies

Tokens issued before 1.3.0

A token now carries its issue time, the session's login time and, when it comes from a renewal, the id of the token it replaced, next to the user index. Tokens issued by an earlier version carry only the index: they remain valid, their age is estimated from their remaining lifetime, and they move to the new format at their first renewal.

Checking it works

1. At startup, look for session renewal every 900s, previous token accepted 30s more. session renewal off means the setting is not being read — see Startup checks.
2. Sign in, wait longer than the interval, then open or reload a page served by ProxyAuth.
3. In the browser's developer tools, the response carries set-cookie: session_token=… and cache-control: private, no-store, max-age=0. The stored cookie value has changed.

Login redirect #

What a request gets when it reaches a required_login route without a valid session — no cookie, an expired or revoked one, or a session past its maximum lifetime — and what a visitor who is already signed in gets when they open the login page.

vhosts:
  - vhost: ["blog.example.com"]
    logout_redirect_url: "/login"     # the login page
    login_redirect_url: "/admin"      # where a login lands
    allow_users: ["admin"]
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:9005"
      - prefix: "/login"
        static: "/var/www/blog/"
        static_index: "login.html"
        tag_proxyauth: true
        cache: false
      - prefix: "/admin"
        target: "http://127.0.0.1:9005"
        preserve_prefix: true
        required_login: true

Which page is the login page

Resolved per route, first match wins:

1. redirect_login_url on the route;
2. redirect_login_url on its vhosts: group;
3. logout_redirect_url on the vhost, then in config.json — the page ProxyAuth already treats as the login page, since that is where a failed login displays its error.

With none of them set, a request without a session keeps the historical 401.

A request without a valid session

A signed-in visitor

Refresh tokens #

For API sessions — vhosts with session_cookie: false — /auth can return a refresh token next to the access token. The client keeps a short-lived access token and exchanges the refresh token for a new pair at POST /refresh_token, without sending the password again.

The access token and the refresh token are two different tokens that carry the same token id, for the whole life of the session. Revoking that id ends the session: both tokens, and every pair issued by later refreshes.

{
  "session_cookie": false,
  "csrf_token": false,
  "token_expiry_seconds": 600,
  "refresh_token_expiry_seconds": 86400
}

session_max_lifetime_secs applies here too: neither token of a pair outlives the end of the session, and a refresh past it is refused.

POST /auth

$ curl -s -X POST https://api.example.com/auth -d 'username=ci-runner&password=...'

{
  "token": "AS1mFWRmJ3s_…",
  "expires_at": "2026-09-17 10:29:05 +02:00",
  "refresh_token": "AXtkX_71LsWz…",
  "refresh_token_expires_at": "2026-09-18 10:19:05 +02:00"
}

With refresh_token_expiry_seconds: 0 the response keeps its earlier shape, token and expires_at only.

POST /refresh_token

$ curl -s -X POST https://api.example.com/refresh_token \
    -H 'content-type: application/json' \
    -d "{\"refresh_token\": \"$REFRESH\"}"

Errors are JSON — {"error": "...", "error_description": "..."} — with the codes OAuth 2.0 clients already know.

One token id, several generations

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 per-vhost overrides, which apply live as soon as routes.yml is reloaded.

Backend timeout #

How long a proxied request may take before ProxyAuth gives up on it, in milliseconds. Raise it for a backend that is legitimately slow to answer; lower it to fail faster when one stops responding.

{
  "backend_timeout": 30000
}

What it covers depends on streaming

With streaming off, the response is collected in full before anything is sent on, so this bounds the whole exchange. With streaming on it bounds only the arrival of the response headers — the body then flows for as long as it takes, which is the entire point of streaming a large transfer.

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.

One counter, whatever num_instances is

The counters are built once at startup and shared by every num_instances server and every worker thread under them. The burst you configure is therefore the burst enforced across the whole host.

Turning one off

requests_per_second: 0 is what disables a limiter, and it disables it completely: no counter is built and no middleware is wrapped around the traffic class.

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.

Revocation & Redis sync #

Three storage layers hold the same revocation set, each answering a different need: an in-memory map read on every request, an LMDB store that survives a restart, and — when redis is configured — a bus that carries a revocation to every other instance.

A revoked token is refused as soon as its id is in the store. Every entry also says when it can be forgotten: a token never lives longer than token_expiry_seconds, so no revocation needs to be kept beyond that, and nothing is kept forever.

The three layers

How long an entry is kept

What LMDB records

Each entry is the token id and a 16-byte value: when the revocation was made, then when it can be purged, both as big-endian Unix seconds.

Writing a revocation

The in-memory map is updated first, so the token stops working on this instance before anything else is attempted. The entry is then written to LMDB and, when redis is configured, published on the bus as three keys:

The three keys are written in one atomic pipeline and share one TTL, so Redis cleans itself up. The 60-second floor guarantees every instance sees an entry on at least one tick, even one about to be purged.

The sync loop

One background task per instance, with or without Redis, ticking every 15 seconds. LMDB and Redis calls run off the request threads.

Propagation delay

The instance handling the revocation enforces it immediately. Every other instance picks it up on its next tick, so worst case is one tick — up to 15 seconds across a fleet.

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"
}

One certificate per file, not per name

A vhost group listing several names shares one vhost_cert, and that file is what defines one certificate. Every name pointing at the same fullchain.pem is issued together, on a single certificate carrying all of them as SANs.

- vhost: ["example.com", "www.example.com"]
  certbot_renew: true
  vhost_cert:
    cert: "/etc/proxyauth/cert/example.com/fullchain.pem"
    key: "/etc/proxyauth/cert/example.com/privkey.pem"

This applies to certbot new, certbot renew <vhost> and certbot renew all alike. Naming a single member of a group renews the whole group and says so — reissuing one name alone would overwrite the shared file with a certificate no longer covering its siblings.

certbot check lists the SANs actually present, which is the quickest way to confirm what a file holds.

Wildcard certificates

A group containing a wildcard vhost can be issued a certificate, but not the same way as everything above.

DNS-01 is selected automatically as soon as any name in the group starts with *.. The command prints the records to create, waits for you to confirm, then asks Let's Encrypt to validate.

$ sudo proxyauth certbot new example.com
$ dig +short TXT _acme-challenge.example.com

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 #

IP abuse blocklists #

Published abuse feeds — Spamhaus DROP, FireHOL, an AbuseIPDB export, your own file — fetched on a timer and checked against every request before anything else happens.

This is the first gate in the request lifecycle. A blocked address never reaches route matching, authentication or CSRF, so nothing downstream can be used to get around it.

{
  "ip_blocklists": [
    { "source": "https://www.spamhaus.org/drop/drop.txt", "name": "spamhaus" },
    { "source": "https://iplists.firehol.org/files/firehol_level1.netset", "name": "firehol1" },
    {
      "source": "https://internal.example.com/exports/abuse.csv.gz",
      "name": "internal",
      "csv": true,
      "csv_column": 2
    },
    { "source": "/etc/proxyauth/local-bans.txt", "name": "local" }
  ],
  "ip_blocklist_refresh_interval_secs": 3600
}

The source object

What it accepts

These are third-party files written to no common standard, so the parser is deliberately forgiving about everything except the address itself.

Refresh, cache and failure

Sources are fetched on their own background task at ip_blocklist_refresh_interval_secs, never on the request path. 0 fetches once at startup and holds that result. With no source configured, no task is started at all.

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.

Wildcard vhosts #

A vhost entry beginning with *. is a pattern rather than a literal hostname, so one route can serve every subdomain of a parent domain without listing them.

vhosts:
  - vhost: ["*.test.example.com"]
    vhost_cert:
      cert: "/etc/proxyauth/cert/test.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/test.example.com/privkey.pem"
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8080"

What a pattern covers

Exactly one extra label. This is RFC 6125's rule — the same one browsers apply to certificate SANs — adopted deliberately so routing a hostname and holding a certificate for it can never disagree.

Precedence

An exact vhost always wins over a wildcard that would also match — for request routing, for resolving vhost-level settings, and for TLS certificate selection alike. SNI follows the same order: the exact name first, then patterns. Without this the winner would depend on where each route sits in routes.yml, which is the class of ambiguity route matching exists to remove.

The decision is made per request rather than once at startup, and that distinction matters for a mixed list. vhost: ["example.com", "*.example.com"] is an exact match when example.com is asked for, and a wildcard match when a.example.com is. A rank assigned to the route as a whole could not express both, so matching runs in two passes over the requested host instead.

vhosts:
  # git.example.com reaches this one, even though the pattern below
  # also covers it — and regardless of the order they appear in.
  - vhost: ["git.example.com"]
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:3000"

  # Everything else under example.com.
  - vhost: ["*.example.com"]
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8080"

Narrowing a route to some of the group's hosts #

A group's routes serve every host the group declares. if_vhost restricts one route to a subset of them — so a single group can hold two routes at the same prefix, each answering a different host.

vhosts:
  - vhost: ["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
    session_cookie: true

    routes:
      # the apex only
      - prefix: "/"
        if_vhost: ["example.com"]
        target: "http://127.0.0.1:8000"

      # every subdomain not declared elsewhere
      - prefix: "/"
        if_vhost: ["*.example.com"]
        target: "http://127.0.0.1:8080"

The certificate, the renewal flag and the session policy are written once. Without if_vhost the same result needs two full groups, with every vhost-level setting duplicated between them.

if_vhost against vhost

Both fields can appear on a route and they answer different questions.

Per-vhost overrides #

Session, CSRF, redirect, SMTP and CORS settings from 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 — none of them mean anything once the backend handles its own auth.

That last one matters most. Left unchecked, a route still carrying a groups: restriction from before it went OIDC-enabled would reject a session the OIDC flow had just correctly established.

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 out of 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, which both renders the form on GET and processes its submission on POST, rather than detouring through the global /auth. And 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. The relying party's own OIDC library verifies it 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. That endpoint also checks the token's iss against 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.

A build that can sign

Signing an id_token needs a crypto provider compiled into the jsonwebtoken crate. Version 11 of that crate enables none by default, and panics the moment it is asked to sign — on POST /oidc/token, which the relying party sees as a dropped connection. One line in Cargo.toml settles it:

jsonwebtoken = { version = "11", features = ["aws_lc_rs"] }

aws_lc_rs is already in the dependency tree, through rustls and the ACME client. Its alternative, rust_crypto, also works but brings back the rsa crate and with it RUSTSEC-2023-0071, which this code deliberately avoids.

Since 1.3.0, ProxyAuth signs a probe token while loading the key: a build without a provider is refused at startup, with that same line in the message, instead of failing on the first relying party.

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

What happens to a malformed entry

A name or value that is not valid in HTTP — a typo in routes.yml, a stray newline — is skipped, with a warning naming the route and the header. It is not passed on to the response builder, because a rejected header there turns the whole response into a 500: one bad line in a configuration file should cost that line, not the route.

Where they do and do not apply

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.

Choosing the algorithm and the level

algorithm accepts a single value or a preference list, most-preferred first — "br, gzip, deflate". It is filtered against the client's Accept-Encoding, and a client that expresses its own preference with q-values wins: the list says what you would rather send, not what you impose.

What is never compressed

• A body the backend already compressed. A response arriving with Content-Encoding is passed through untouched — no double compression.
• Anything outside the size window. When the length is known, the decision is taken from the header, without reading the body at all; below min_size the encoding overhead costs more than it saves, and max_size is there for the occasional very large export whose CPU cost you would rather skip.
• Media types outside the allow-list, images and video included: they are already compressed.

Every field is optional and inherited: a route falls back to its vhosts: group, then to the global compression block in config.json. Set it once at the top and override only where a route needs something different.

Streamed responses #

By default a proxied response is collected in full before a single byte reaches the client. streaming: true relays the body as it arrives instead.

The cost of buffering is the size of the response multiplied by the number of concurrent requests — the exact shape of a git server, a package registry, or any download endpoint.

vhosts:
  - vhost: ["git.example.com"]
    streaming: true
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:3000"

What changes

When buffering wins anyway

Three features rewrite the response body and therefore need to see it whole. When any of them is active on a route, that route buffers regardless of streaming, and a warning naming the route is logged at startup — silently dropping a substitution an operator explicitly configured would be the worse failure.

The split is clean in practice: HTML served to a browser is small and often wants rewriting, while git traffic, package downloads, API responses and event streams want neither rewriting nor buffering.

Caching #

Signed-in visitors

The route's policy applies to anonymous visitors. Two cases override it, whatever the route or the backend asked for:

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.

How a backend is chosen

Not a plain round-robin. Weights are spread with smooth weighted round-robin: with weights 5 and 1 the light backend is used once every six requests, evenly, rather than receiving five in a row every sixth cycle. A backend at weight: -1 is left out of the rotation entirely and only tried when every weighted backend has failed.

On top of that, the backend that last answered for a given route, method and host is reused for two seconds. That keeps a page and the requests it triggers on the same instance, which matters for a backend holding any per-node state, and costs nothing when there is none. The entry is checked against the route's current backend list before it is used, so a changed configuration can never send traffic somewhere no longer listed.

When a backend fails

Connection tuning

Shared with every proxied route, from config.json: client_timeout bounds one attempt against a backend, keep_alive how long an idle connection is kept, and max_idle_per_host how many are kept per backend. backend_timeout bounds the exchange as a whole.

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"

Headers the proxy never relays #

Ten headers are stripped from every request before it reaches the backend, and from every response before it reaches the client. They describe one connection, not the message travelling over it, so copying them across a proxy boundary is meaningless at best.

This is not configurable. A proxy that relays them is a proxy two HTTP implementations can be made to disagree about — which is the entire mechanism behind request smuggling.

Connection            Keep-Alive
Content-Length        Proxy-Connection
Transfer-Encoding     Proxy-Authenticate
TE                    Proxy-Authorization
Trailer
Upgrade

RFC 9110 §7.6.1 calls these connection-specific. Each hop is expected to generate its own framing based on how it actually sends the message, not to copy what the previous hop said. ProxyAuth re-serialises every body it forwards, so it emits its own Content-Length or chunked framing and discards whatever arrived.

The one exception

A HEAD response keeps the backend's Content-Length. The body is empty by definition, so regenerating the header would produce 0 — but a client issuing HEAD is asking precisely how large the matching GET would be. Both proxy paths do this identically, so HEAD never answers differently depending on whether an egress proxy is in play.

Headers stripped for a different reason

Four more never reach the backend as the client sent them, not for framing but because ProxyAuth asserts them itself: X-User, X-User-Roles, X-User-Groups and, when forward_proxy_headers is on, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP and X-Forwarded-For.

A backend that trusts those headers cannot be fed a chosen value by a caller who simply sets them — see Sessions and Forwarding client info.

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.crt"
      key: "/etc/proxyauth/certs/client.key"

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.

The two files

A PEM certificate chain and its PEM private key — the pair an internal CA hands out — read by rustls:

Both paths must be readable by run_user, and the key by nobody else. There is no passphrase: an encrypted key has to be decrypted first — openssl rsa -in encrypted.key -out client.key. Leaving either path out, or pointing at an unreadable file, is treated as a certificate error (below).

basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth

$ openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
    -days 365 -out client.crt -extfile client.cnf

When the certificate cannot be used

It is a global setting in config.json. If a backend uses the certificate to decide who is calling, turn it on: a renamed file should be a failed request, not a request that quietly arrives as nobody.

A client is built once per certificate and key pair and cached, so a changed certificate is picked up at the next restart, not on the next request.

Path handling #

Rewriting with captures

A regex route can put named captures into the target path, and nowhere else: after substitution the rewritten host is compared with the configured one, and a request whose capture would have changed it is refused. A capture picks where in the path a request lands, never where it is sent.

- prefix: "/forum/topic"
  regex: '^/forum/topic/(?<id>[0-9]+)(?:-[a-z0-9-]+)?$'
  target: "http://127.0.0.1:9000/threads/{id}"

Keep capture classes narrow ([0-9]+, [a-z0-9-]+) rather than (?<x>.*): what a capture accepts is what ends up in the backend's path.

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.

routes:
  - prefix: "/partner"
    target: "https://api.partner.example"
    proxy: true
    proxy_config: "http://egress.internal:3128"

Every request on the route goes through that proxy — there is no bypass list. An https:// target is reached through a CONNECT tunnel, so the TLS session still terminates at the real backend and the egress proxy sees only the hostname.

Typical reasons to use it: a network where outbound traffic only leaves through a corporate proxy, or a partner who allow-lists a fixed egress address that is not the one ProxyAuth runs on.

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.

It can also gate route access directly now, the same way groups does. The two coexist without conflict: 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 also read-only for almost everything: db-add-user and db-delete-user 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

Database schema #

Seven tables, one trigger, two indexes — created automatically at startup and re-checked on every start, so there is no migration step to run by hand and no SQL file to keep in sync with the binary.

The shape mirrors the file-based User object exactly. That is deliberate: an account behaves identically whether it lives in config.json or here, and neither the proxy nor the CLI has a separate code path for the two.

The tables and how they relate

users

The only table the login path reads directly. Everything else hangs off it.

The child tables

Two kinds of deletion

The distinction is what makes a deletion propagate quickly instead of waiting for the next full scan.

Created for you, on every startup

Schema creation runs before the first scan, and is written to be safe to re-run: CREATE TABLE IF NOT EXISTS everywhere, plus explicit ALTER TABLE statements for the four columns added after the first release.

The trigger is dropped and recreated on each start, since neither engine offers a dependable CREATE TRIGGER IF NOT EXISTS. If a second instance recreates it in between, an "already exists" error is treated as success — the trigger being present is the only thing that matters.

The schema, written out

What ProxyAuth issues. Useful for review, for a managed database where the application account has no DDL rights, or simply to know what will appear.

CREATE TABLE IF NOT EXISTS users (
    id                   BIGSERIAL PRIMARY KEY,
    username             VARCHAR(255) NOT NULL UNIQUE,
    password             TEXT NOT NULL,
    otpkey               TEXT,
    created_at           TIMESTAMP NOT NULL DEFAULT now(),
    modified_at          TIMESTAMP NOT NULL DEFAULT now(),
    deleted              BOOLEAN NOT NULL DEFAULT FALSE,
    must_change_password BOOLEAN NOT NULL DEFAULT FALSE
);
CREATE INDEX IF NOT EXISTS idx_users_modified_at ON users (modified_at);

CREATE TABLE IF NOT EXISTS user_allow (
    id      BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    cidr    TEXT NOT NULL
);

CREATE TABLE IF NOT EXISTS user_roles (
    id      BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role    TEXT NOT NULL
);

CREATE TABLE IF NOT EXISTS groups (
    id   BIGSERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL UNIQUE
);

CREATE TABLE IF NOT EXISTS user_groups (
    id       BIGSERIAL PRIMARY KEY,
    user_id  BIGINT NOT NULL REFERENCES users(id)  ON DELETE CASCADE,
    group_id BIGINT NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
    UNIQUE (user_id, group_id)
);

CREATE TABLE IF NOT EXISTS user_email (
    id         BIGSERIAL PRIMARY KEY,
    user_id    BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    email      TEXT NOT NULL,
    is_primary BOOLEAN NOT NULL DEFAULT FALSE
);

CREATE TABLE IF NOT EXISTS deleted_users_log (
    id         BIGSERIAL PRIMARY KEY,
    username   VARCHAR(255) NOT NULL,
    deleted_at TIMESTAMP NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS idx_deleted_users_log_deleted_at
    ON deleted_users_log (deleted_at);

CREATE OR REPLACE FUNCTION log_deleted_user() RETURNS TRIGGER AS $$
BEGIN
    INSERT INTO deleted_users_log (username) VALUES (OLD.username);
    RETURN OLD;
END;
$$ LANGUAGE plpgsql;

DROP TRIGGER IF EXISTS trg_log_user_delete ON users;
CREATE TRIGGER trg_log_user_delete
    AFTER DELETE ON users
    FOR EACH ROW EXECUTE FUNCTION log_deleted_user();

CREATE TABLE IF NOT EXISTS users (
    id                   BIGINT AUTO_INCREMENT PRIMARY KEY,
    username             VARCHAR(255) NOT NULL UNIQUE,
    password             TEXT NOT NULL,
    otpkey               TEXT,
    created_at           TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    modified_at          TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
                                   ON UPDATE CURRENT_TIMESTAMP,
    deleted              BOOLEAN NOT NULL DEFAULT FALSE,
    must_change_password BOOLEAN NOT NULL DEFAULT FALSE,
    INDEX idx_users_modified_at (modified_at)
);

-- user_allow, user_roles, groups, user_groups and user_email are
-- identical to the PostgreSQL definitions above, with BIGSERIAL
-- replaced by BIGINT AUTO_INCREMENT.

CREATE TABLE IF NOT EXISTS deleted_users_log (
    id         BIGINT AUTO_INCREMENT PRIMARY KEY,
    username   VARCHAR(255) NOT NULL,
    deleted_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_deleted_users_log_deleted_at (deleted_at)
);

DROP TRIGGER IF EXISTS trg_log_user_delete;
CREATE TRIGGER trg_log_user_delete
    AFTER DELETE ON users
    FOR EACH ROW
    INSERT INTO deleted_users_log (username) VALUES (OLD.username);

How a read actually happens

Five separate queries, joined in memory rather than in SQL. string_agg and GROUP_CONCAT would each need their own dialect, and the row counts here are small enough that assembling the objects in the application costs less than maintaining two versions of one query.

SELECT id, username, password, otpkey, must_change_password
  FROM users WHERE deleted = FALSE;

SELECT user_id, cidr AS value FROM user_allow;
SELECT user_id, role AS value FROM user_roles;

SELECT user_groups.user_id, groups.name AS value
  FROM user_groups JOIN groups ON groups.id = user_groups.group_id;

SELECT user_id, email AS address, is_primary FROM user_email;

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.

An enrollment or reset patches it immediately anyway, alongside the real database write — specifically so a database outage occurring shortly afterward cannot make ProxyAuth 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. Replacing an enrolled second factor therefore 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.

Email templates #

Every email ProxyAuth sends is a plain-text file on disk under /etc/proxyauth/mail/templates/, with {{ }} placeholders substituted at send time. One file per purpose. Today that is password reset, the only flow that sends mail.

The file

Structure

The first line must be the subject, in this exact shape, and it is stripped from the body before sending:

Subject = "ProxyAuth Password Reset"
Hello {{ username }},

A password reset request has been initiated for your account.

Click the link below to set a new password:
{{ reset_link }}

This link is valid for a limited time.

If you did not request this, simply ignore this message — your
current password will keep working.

—
ProxyAuth Security System

Transport

Built from the smtp block, resolved per vhost when --vhost names one. The port decides the encryption, with no separate setting:

Credentials are always sent — username and password are not optional — and timeout_secs bounds the whole exchange.

What the link is worth

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]

Every hyphenated name also accepts an underscore — [user_agent] works exactly like [user-agent] — and five carry a shorter alias, for formats inherited from another proxy:

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

Why a socket rather than an endpoint

The socket lives at /opt/proxyauth/run/stats.sock, owner-only inside an owner-only directory. Those permissions are the authentication: whoever can read the file is already run_user or root on the machine. No admin token in a shell history, no TLS round-trip, nothing listening on the network.

The same figures from elsewhere

Both are outside the rate limits, so a monitoring system is never throttled during an incident, and both require "stats": true like the socket itself.

Startup checks #

Both configuration files accept keys they do not know, so an older file keeps loading on a newer binary. The flip side is that a typo produces a setting that silently does nothing. At startup ProxyAuth reports such keys, with the setting most likely meant, and prints the session policy it will actually apply.

warning: config.json: unknown key `refresh_token` is ignored — did you mean `session_refresh_interval_secs`?
warning: routes.yml › vhosts[0] (blog.example.com) › routes[2] (/admin): unknown key `requierd_login` is ignored — did you mean `required_login`?
session renewal every 900s, previous token accepted 30s more, sessions end 43200s after login
session renewal on api.example.com/v1: off (session_refresh_interval_secs = 0)

Lines go to standard error and to the application log. They are warnings: startup continues.

Unknown keys

Suggestions come from the words people naturally use first — refresh, renew, grace, cookie_ttl, login_page — then from spelling distance.

Session policy summary

One line for the global policy, one for each vhost or route that overrides it, and a warning when renewal is configured but can never happen:

warning: session renewal on /admin never happens: session_refresh_interval_secs (3600) is not shorter than token_expiry_seconds (3600)

If you set session_refresh_interval_secs and still read session renewal off, the value is not reaching the running binary: check the file that was actually loaded, the spelling, and that the service runs a 1.3.0 build.

config.json is rewritten losslessly

ProxyAuth rewrites config.json at startup when it has something to persist: a plaintext password replaced by its Argon2id hash, users sorted, a generated token_admin. Every setting is written back. Earlier versions left out several — among them smtp, trust_proxy_forward_for, ip_blocklists, run_user, run_group, max_body_size, backend_timeout, strict_mtls and page_change_password — which were therefore deleted from the file at that point.

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

Guided setup

All three show the block before writing it (default answer: no), back the file up as <file>.bak-<timestamp>, validate routes.yml with the server's own parser before committing, and print the block again afterwards.

Database-backed users

Accounts & access

TLS & certificates

Operations

Sessions with ProxyAuth #

ProxyAuth's own login system, served on every vhost that does not delegate identity to its backend. Two endpoints, /auth and /logout, and one setting — session_cookie — that decides which of two very different shapes they take.

This is the opposite direction from the OIDC provider. Here ProxyAuth authenticates the visitor and tells the backend who they are; there, the backend authenticates through ProxyAuth and manages its own sessions. A vhost does one or the other, never both.

One setting, two audiences

A browser and a script want incompatible things from a login. session_cookie is how you say which one this vhost serves, and every other difference follows from it.

The browser flow

The API flow

$ 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"

No login page, no cookie, no CSRF. The token is obtained once and presented on each call until expires_at passes.

What the backend receives

In both modes the backend is handed an identity, never a credential. The token stays between the client and ProxyAuth.

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

A backend behind a required_login route can therefore trust these headers without implementing any authentication of its own — which is the entire point of gating an app that has no login. Add forward_proxy_headers when it also needs the visitor's real address and the original Host.

POST /auth

GET /logout

Keeping a session alive

With session_refresh_interval_secs set, a browser session in use receives a fresh token at that interval, in a new Set-Cookie, on protected and public pages alike. The visitor never signs in again until the session is left idle past token_expiry_seconds or reaches session_max_lifetime_secs.

Requests without a valid session

A page opened on a required_login route without a valid session is sent to the login page with a 302; an API call gets 401; a signed-in account that is not allowed on the route gets 403. The full rules are in Login redirect.

On an OIDC vhost, neither applies

Where a vhost sets oidc:, both endpoints proxy straight through to the backend like any other path, and ProxyAuth's own session machinery steps aside entirely. A relying party such as Grafana has its own login and logout UI, and it is that UI visitors reach.

Admin API reference #

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