OAuth2 Proxy is a reverse proxy that adds OAuth2 and OpenID Connect single sign-on to applications that have no login of their own. It sits in front of the app, checks every request for a valid session, and either forwards it upstream with the signed-in user’s identity attached as HTTP headers, or sends the visitor to an identity provider — Google, Microsoft Entra ID, GitHub, login.gov or any generic OIDC issuer — and back again.
It is written in Go and shipped as a single static binary alongside distroless container images, so a deployment is one container and a handful of flags rather than an identity platform to operate.
Most self-hosted web apps either ship with no authentication at all or with an account system of their own, which means the same password is re-issued for every internal dashboard, wiki and metrics UI. OAuth2 Proxy turns that around: identity stays with the provider you already run, and the apps behind it simply trust the headers it forwards. For a homelab or a small team it is the shortest path from “anyone who can reach the port” to “only members of the ops group”. It is also a long-running, community-governed project with a steady release line that keeps its Go toolchain and dependencies current and patches security issues promptly.
auth_request, Traefik, Envoy and Apache, where it answers 202 or 401 and lets your existing proxy do the routing.X-Forwarded-User, X-Forwarded-Groups, X-Forwarded-Email and X-Forwarded-Preferred-Username reach the upstream application, and --set-xauthrequest adds the equivalent X-Auth-Request-* response headers for nginx so the app behind the proxy can do its own authorisation.--authenticated-emails-file that can be reloaded without a restart, and exempt individual paths with skip-auth rules./ping and /ready for health checks, a Prometheus /metrics endpoint, and a --config-test flag that validates a configuration file and exits, which makes it easy to gate a deployment in CI.In standalone mode OAuth2 Proxy is the web server: it terminates the request, and everything that arrives with a valid session is proxied to the upstream address you configure. In middleware mode it is called on every request by the proxy already in front of your stack, and only answers yes or no — the interesting part is that the same binary covers both, so a homelab can start with one app and later move to a Traefik ForwardAuth or nginx auth_request setup without changing the authentication layer.
There is no admin UI and no user database: users, groups and passwords stay with the identity provider, and OAuth2 Proxy only decides who gets through. Configuration is flags, environment variables or a TOML file, and each protected app still needs an OAuth application registered with the provider to obtain a client ID, a client secret and a callback URL (/oauth2/callback by default). When it runs behind another reverse proxy, enable --reverse-proxy and set --trusted-proxy-ip to the proxy hops you actually control — without that, a client able to reach the port directly may be able to spoof X-Forwarded-* headers. Signing out only clears its own cookie, so redirect to the provider’s end-session endpoint when a real sign-out is what you need.
OAuth2 Proxy is a gate, not an identity provider. If you still need to issue identities — users, groups, MFA devices, OIDC clients — pair it with a self-hosted IdP such as Rauthy, Kanidm or GLAuth, and let OAuth2 Proxy enforce per-application access in front of them.