Vouch Proxy

Last reviewed Sep 13, 2026 · 788 words

Vouch Proxy puts an OAuth or OpenID Connect login page in front of any site your nginx serves, in about 20 lines of nginx config and one YAML file, and it uses 64 MB of RAM doing it. It stores no users, sets no passwords and has no admin panel: it asks Google, GitHub, Keycloak, Authentik or another provider "who is this", writes the answer into a signed cookie, and tells nginx yes or no on every request. That narrowness is the reason to choose it and the reason it will not be enough for some setups.

The mechanism is nginx auth_request

nginx has a directive, auth_request, that makes a subrequest to another URL before serving a location and only proceeds if that subrequest returns 200. Vouch listens on port 9090 and answers /validate with 200 when the request carries a valid cookie and 401 when it does not. On 401, nginx redirects the browser to Vouch's /login, which bounces through the provider, sets the cookie for your domain, and sends the user back where they started.

server {
    server_name app.example.com;
    auth_request /validate;
    location = /validate {
        proxy_pass http://127.0.0.1:9090/validate;
        proxy_set_header Host $http_host;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        auth_request_set $auth_resp_jwt $upstream_http_x_vouch_jwt;
        auth_request_set $auth_resp_err $upstream_http_x_vouch_err;
        auth_request_set $auth_resp_failcount $upstream_http_x_vouch_failcount;
    }
    error_page 401 = @error401;
    location @error401 {
        return 302 https://vouch.example.com/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&X-Vouch-Token=$auth_resp_jwt&error=$auth_resp_err;
    }
    location / {
        auth_request_set $auth_user $upstream_http_x_vouch_user;
        proxy_set_header X-Vouch-User $auth_user;
        proxy_pass http://127.0.0.1:3000;
    }
}

Copy that per site, change the upstream, done. The X-Vouch-User header carries the authenticated email into the app behind it, which is enough for apps like Grafana or Miniflux that accept a trusted header as identity.

One YAML, one provider, two settings that matter

The config lives at config/config.yml in the container quay.io/vouch/vouch-proxy. Set vouch.domains to the domains you protect (only cookies for those hosts are honoured), oauth.provider to google, github, oidc or one of the other built-ins, plus the client ID, secret and callback URL registered with that provider. Then decide who is allowed: vouch.allowAllUsers: true lets anyone with a Google account through, which is almost never what you want, so use vouch.whiteList with a list of emails, or for OIDC providers, restrict by group claim through vouch.teamWhitelist. vouch.cookie.domain must be the parent domain (example.com) so one login covers every subdomain, and this is the single most common misconfiguration: leave it as vouch.example.com and users log in successfully then get sent straight back to the login page.

What Vouch does not do, on purpose

It has no local users, so it cannot be your only identity source; a homelab with no external provider needs Keycloak or Authentik behind it, at which point Authentik's own embedded outpost can play the Vouch role. It has no per-app policy beyond the global allow list, so you cannot say "admins only for this host" without running a second Vouch instance. It does no 2FA itself, relying entirely on the provider. It does not proxy traffic; it only answers yes or no, so it only works with a reverse proxy that supports forward auth, which means nginx, Caddy's forward_auth, and Traefik's ForwardAuth middleware, all of which are covered in the reverse proxy showdown.

Authelia and oauth2-proxy are the siblings to weigh

Within the identity category, three tools solve this same problem. oauth2-proxy is the bigger project by a wide margin, does the same OAuth gate, and can also run as a full reverse proxy in front of the app; pick it if you want a larger community and Kubernetes examples. Authelia adds what Vouch lacks: its own user file or LDAP backend, TOTP and WebAuthn 2FA, and per-domain access rules, at the cost of a Redis dependency and a longer config. The Authelia vs Authentik piece covers the full-IdP end of the spectrum. Vouch wins only when the requirements are exactly "Google login, allow these 6 emails, nginx already installed".

What I'd do

If I already had nginx and my users all have Google or GitHub accounts: Vouch on the same host, whiteList of emails, cookie.domain set to the apex, the nginx snippet above as an include file. Six services protected in an evening, near-zero memory, nothing to upgrade more than twice a year. If I needed local accounts, groups, or 2FA under my control, I would skip it and go straight to Authelia, because retrofitting those onto Vouch means running a second product anyway.