Vouch Proxy and the auth_request module: putting one login in front of every Nginx site

The problem Vouch Proxy solves for Nginx operators

Nginx can already forward a request to a subrequest handler and reject it if that handler returns anything other than 2xx. That is the whole of the auth_request module. What it does not give you is a login flow: there is no session, no redirect to an identity provider, no callback endpoint, no cookie. Vouch Proxy fills exactly that gap. It is a separate Go process that answers the auth subrequest, and when the request carries no valid session it drives the browser to an OAuth or OIDC provider and back.

The intended reader runs several applications behind one Nginx instance, typically at app1.yourdomain.com and app2.yourdomain.com, and wants a single login to cover all of them. The README is explicit that Vouch can protect all of your websites at once and that it can be used as a Single Sign On solution for web applications in the same domain. The second half of that sentence is the constraint that decides most deployments.

It is not a user directory. Vouch does not store accounts, and it does not replace the IdP. It reads what the provider returns and, if configured to, passes the visitor's email, name and other information, including access tokens, to the protected application as HTTP headers. The README notes that this can replace application user management entirely, which is a larger commitment than it first appears: once the app trusts a header, anything that can reach the app directly can forge it.

How the auth subrequest and the shared cookie fit together

Every protected request goes through Nginx first. Nginx issues an internal subrequest to Vouch's /validate endpoint. Vouch checks the session cookie, and on success the original request proceeds; on failure the browser is sent to the provider. The README states that if Vouch runs on the same host as the Nginx reverse proxy, the response time from /validate to Nginx should be less than 1ms. That number is a claim about a loopback subrequest, not a benchmark of the whole login path, and the round trip to Google or Okta dominates anything a user notices.

The mechanism that makes this work across subdomains is the cookie domain. Vouch relies on sharing a cookie between the Vouch server and the application it protects, so Vouch typically runs at vouch.yourdomain.com while apps run at app1.yourdomain.com and app2.yourdomain.com. The protected domain is .yourdomain.com, and the README says the cookie must be set in that domain by putting yourdomain.com into vouch.domains, or sometimes by setting vouch.cookie.domain to yourdomain.com. Those two settings are the usual source of a login that succeeds and then immediately loops.

The service is built from a small set of Go dependencies: Viper for configuration, gorilla/sessions for the cookie session, golang-jwt for tokens, and golang.org/x/oauth2 for the provider handshake. PKCE support comes from a dedicated verifier package in the module list, which matters for public clients. Beyond login, the repository points at an OpenResty example for advanced authorization, which is where you would go if a plain boolean answer from /validate is not enough.

Installing Vouch Proxy from the scratch Docker image

The repository ships a Dockerfile that builds a static binary and copies it into a scratch image, so the runtime container has no shell and no package manager. It copies the CA certificates, the passwd and group files, and the vouch-proxy binary, then sets USER vouch. The exposed port is 9090, the entrypoint is /vouch-proxy, and a healthcheck runs the binary with -healthcheck every minute. There are no release artifacts listed, so building the image from the repository is the path the Dockerfile describes.

docker build -t vouch-proxy .
docker run -p 9090:9090 -v "$PWD/config:/config" vouch-proxy

The README's own install sequence starts by copying a provider example into place. The repository lists example files for Google, GitHub, GitHub Enterprise, Slack, Twitch, Discord, SecureAuth, Gitea, Keycloak and Pocket ID, so pick the one matching your provider rather than editing a blank file.

cp ./config/config.yml_example_$OAUTH_PROVIDER ./config/config.yml

Then create OAuth credentials at the provider's console and direct the callback URL to the Vouch Proxy /auth endpoint. That last instruction is easy to skim past and is the first thing to check when the provider returns an error. After that you configure Nginx, and the README's example assumes Nginx, vouch.yourdomain.com and protectedapp.yourdomain.com all run on the same server, both served over https with valid certificates. If you are not using TLS, the README says to change the listen directive to port 80 and adjust vouch.cookie.secure. Configuration can also be supplied through environment variables, which is what the Kubernetes ingress section and most container deployments rely on.

Where the shared-cookie model breaks

The parent-domain requirement is not a detail you can work around with configuration. If your applications sit on unrelated domains, or if some live on a domain you do not control, there is no cookie scope that covers both Vouch and the app, and the login will not carry over. That rules out a certain class of multi-tenant or customer-domain setups entirely.

The README has a troubleshooting section dedicated to the infinite redirect loop that returns you to your IdP, which tells you how common the failure is. Loops of that shape usually mean the cookie was not set on the domain Nginx is serving, or that vouch.cookie.secure is on while the site is served over plain HTTP. The related search phrase vouch proxy 400 bad request points at the same neighborhood: a callback or validate request arriving with parameters the provider or Vouch will not accept.

There is also a structural limitation worth naming. Vouch answers one question, whether the visitor is logged in, and the answer is cached in a cookie for several hours. The README says access is allowed for several hours after login, with every request checked by Vouch to confirm it is valid. That is session validation, not authorization. If you need per-request policy, group membership checks against a directory, or route-level rules that change minute to minute, the OpenResty example is the documented escape hatch, and you should expect to write that logic yourself. Vouch will not do it for you.

Vouch Proxy against oauth2-proxy and Authelia

The comparison people actually search for is vouch proxy vs oauth2 proxy, and the difference is architectural rather than a matter of features. oauth2-proxy is a general-purpose reverse-proxy companion that speaks to more than just Nginx, ships its own configuration surface, and is commonly deployed in front of ingress controllers. Vouch is narrower by design: it exists to be the auth_request target for Nginx and to share a cookie across subdomains of one parent domain. If your edge is Nginx and your apps are subdomains, Vouch's smaller surface is an advantage. If your edge is something else, or you want one tool that covers several proxy frontends, Vouch's focus becomes a limitation.

Authelia is a different shape again. It is an authentication and authorization server with its own user database and second-factor support, so it can act as the identity source rather than only as a client of one. Vouch never stores users; it delegates that to Google, Okta, Keycloak, Gitea, Pocket ID or whichever provider you configure. Choose Vouch when the IdP already exists and you only need the gate. Choose Authelia when you want the gate and the directory in one process.

The related searches also list vouch proxy traefik and vouch-proxy caddy. Those are honest questions about whether the auth_request trick travels. It does not travel unchanged: the mechanism depends on Nginx's auth_request module, and the configuration examples are Nginx configurations. Running Vouch behind a different proxy means reproducing that subrequest behaviour in the other proxy, which the repository does not document.

Maintenance, licence and the cost of upgrading

The last push to the repository was on 2026-07-03, roughly two and a half months before this article, so the project is not dormant. It is not archived. There are no recent releases listed, which means the practical upgrade path is rebuilding from the master branch or from a tag you select yourself rather than pulling a versioned artifact. That has a real cost: you own the build, and you should pin a commit rather than tracking master if you are running this in production.

Building is a two-stage Docker build with a Go toolchain, and the module file pins go 1.25.0 with a toolchain line at go1.26.2. The base image in the Dockerfile is golang:1.26. Upgrading therefore means rebuilding the image whenever you want dependency updates, and the scratch runtime means you cannot patch anything inside the container. There is no shell to debug with, which is a deliberate trade for a small attack surface.

The project is MIT licensed. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained, but it comes with no warranty. Nothing here describes a trademark policy or any additional terms, and none of this is legal advice. If you redistribute a modified Vouch Proxy, keep the LICENSE file intact in the source you ship.

Editorial conclusion

Adopt Vouch Proxy when Nginx already terminates TLS for several subdomains under one parent domain and you want IdP login without touching each application. Do not adopt it if your services live on unrelated domains, if you need per-request authorization decisions beyond login, or if you cannot run a second process beside Nginx. Before rolling it out, verify that vouch.domains and vouch.cookie.domain actually cover every hostname you intend to protect, and confirm your IdP callback points at the /auth endpoint.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. vouch/vouch-proxy on GitHub