OAuth2 Proxy

MIT
Platform
Linux Windows macOS Docker
Licence
MIT Open source
OAuth2 Proxy

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.

Why OAuth2 Proxy is worth a look

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.

Key features

  • Two deployment shapes — run it as a standalone reverse proxy in front of a single app, or as forward-auth middleware for nginx auth_request, Traefik, Envoy and Apache, where it answers 202 or 401 and lets your existing proxy do the routing.
  • Many providers behind one interface — a generic OIDC client covers Keycloak, Authentik, Zitadel and any standards-compliant issuer, with dedicated implementations for Google, Microsoft Entra ID, GitHub, GitLab and login.gov that add provider-specific username and group handling.
  • Identity passed in headers — 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.
  • Stateless by default — sessions live in an encrypted, signed cookie, so there is no database to run; switch to the Redis backend when sessions must be shared across replicas or revocation has to be immediate.
  • Authorisation rules — restrict access by e-mail domain, allowed group or role, or an --authenticated-emails-file that can be reloaded without a restart, and exempt individual paths with skip-auth rules.
  • Operational endpoints built in — /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.
  • Branding — the sign-in page accepts your own banner text and custom templates instead of the stock page.

Standalone proxy or middleware

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.

Things worth knowing

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.

Where it fits

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.

Explore More Categories

Sign In

Register

Reset Password

Please enter your username or email address, you will receive a link to create a new password via email.