OAuth2 Proxy: OIDC Authentication Reverse Proxy

What OAuth2 Proxy is

OAuth2 Proxy is an open-source tool that puts OAuth2 and OpenID Connect authentication in front of web applications that have none of their own. The README describes two ways to run it: as a standalone reverse proxy that intercepts requests and redirects users to an identity provider, or as a middleware component plugged into an existing reverse proxy or load balancer so one instance can handle authentication for many applications. The documentation's one-line summary is a reverse proxy and static file server that authenticates users through providers such as Google and GitHub and validates accounts by email, domain or group.

It works with a generic OIDC client or with provider-specific implementations for Google, Microsoft Entra ID, GitHub, login.gov and others. The specialised providers can pull extra details about a user, such as a preferred username and group membership, and pass them on to upstream applications as HTTP headers. That lets an internal dashboard, admin console or legacy app trust a header instead of implementing login itself.

The project has a long history. The repository was forked from bitly/OAuth2_Proxy on 27 November 2018, and versions v3.0.0 and later come from the fork. It was hosted as pusher/oauth2_proxy until it was renamed to oauth2-proxy/oauth2-proxy on 29 March 2020. Today it is a Cloud Native Computing Foundation Sandbox project.

How OAuth2 Proxy works

The behaviour page lays out the request flow. Every request passing through the proxy to an upstream requires authentication, except the proxy's own endpoints and any routes exempted with --skip-auth-route. An unauthenticated browser request is redirected to the identity provider's login page; a request with an Accept: application/json header gets a 401 Unauthorized instead. After the user signs in, the OAuth tokens are stored in the configured session store and a cookie is set.

What happens next depends on the deployment mode. In proxy mode the authenticated request is forwarded to the configured upstream with user information and authentication headers added. In middleware mode OAuth2 Proxy only returns a status code for another proxy, such as Nginx or Traefik, to act on. The /oauth2/auth endpoint exists for this: it returns 202 Accepted or 401 Unauthorized and is designed for the Nginx auth_request directive.

Sessions are stored in one of two backends. The default cookie store keeps all session data in signed, encrypted client-side cookies, which makes the proxy completely stateless; the trade-off, according to the docs, is that it cannot lock sessions, so concurrent refreshes can conflict and force users to sign in again. The Redis store instead sends the browser a short ticket and stores the session in Redis, encrypted with a secret that is unique to each session.

Upstreams can be HTTP or HTTPS servers, unix sockets, file:// paths for static files or static:// responses with a fixed status code. Routing is based on the path: an upstream URL without a trailing slash matches one exact path, one with a trailing slash matches everything under that prefix, and when several match, the longest path wins.

Key features

• Many identity providers: the provider list covers ADFS, Bitbucket, Cidaas, Cisco Duo, DigitalOcean, Facebook, Gitea, GitHub, GitLab, Google (the default), Keycloak OIDC, LinkedIn, login.gov, Microsoft Entra ID, Nextcloud, SourceHut and generic OpenID Connect.
• Email and domain rules: allow a company domain with --email-domain, a list of individual addresses with --authenticated-emails-file, or everyone with --email-domain=*.
• Identity headers for upstreams: X-Forwarded-User, X-Forwarded-Email, X-Forwarded-Groups and X-Forwarded-Preferred-Username, plus optional access-token and ID-token forwarding.
• Response headers for auth_request mode: --set-xauthrequest returns X-Auth-Request-User, groups, email and preferred-username headers for the front proxy to copy.
• Cookie or Redis sessions: stateless by default, server-side when tokens get large.
• Multiple upstreams: path-based routing to several backends, static files and fixed responses from one instance.
• Flexible configuration: command-line options, environment variables or a config file, in that order of precedence.
• Config validation: --config-test runs the same validation as startup and exits with code 1 on errors, which suits CI pipelines.
• Operational endpoints: /ping for health checks, /ready for backend connectivity such as Redis, and an optional Prometheus /metrics endpoint.
• Wide platform support: release binaries for all major architectures plus ppc64le and s390x, distroless container images since v7.6.0 with -alpine variants, and an official Helm chart.
• Integration guides: the docs include setups for Nginx, Traefik, Caddy, Kubernetes Dashboard and Headlamp.

Getting started with OAuth2 Proxy

The installation guide offers prebuilt binaries from GitHub Releases (the docs name v7.15.5 as the current release), container images on quay.io, a Helm chart, or installing the latest release with Go:

go install github.com/oauth2-proxy/oauth2-proxy/v7@latest

Prebuilt binaries can be checked against the checksum file published with each release:

sha256sum -c sha256sum.txt

Next, register an OAuth application with your provider, using a redirect URI on the domain OAuth2 Proxy will run on. A cookie secret is required; the configuration overview gives several ways to generate one, including:

openssl rand -base64 32 | tr -- '+/' '-_'

The OpenID Connect guide uses a local Dex instance as its example provider and runs OAuth2 Proxy with these arguments:

--provider oidc
--provider-display-name "My OIDC Provider"
--client-id oauth2-proxy
--client-secret proxy
--redirect-url http://127.0.0.1:4180/oauth2/callback
--oidc-issuer-url http://127.0.0.1:5556/dex
--cookie-secure=false
--cookie-secret=secret
--email-domain kilgore.trout

Visiting http://127.0.0.1:4180 then triggers the login flow. Those values are for local testing only; production needs a real secret and secure cookies. Before rolling out a config change, validate it without starting the server:

oauth2-proxy --config /etc/oauth2-proxy.cfg --config-test

For Nginx, the integration guide shows a server block that proxies /oauth2/ to OAuth2 Proxy on port 4180 and protects other locations with auth_request /oauth2/auth. That mode requires the --reverse-proxy option.

Use cases

• Internal tools behind company SSO: put dashboards, admin panels or staging sites behind Google Workspace, Entra ID or GitHub sign-in restricted to your domain.
• Kubernetes ingress authentication: run it alongside ingress-nginx, which the Nginx guide covers with annotations, to protect several services at once.
• Legacy apps without login: forward the authenticated user's email and groups as headers to an app that can read them.
• Protected static sites: serve documentation or build artifacts from file:// upstreams only to signed-in users.
• Group-based access: with providers that expose groups, pass them upstream so applications can map them to roles.

How OAuth2 Proxy compares

OAuth2 Proxy is not an identity provider. It relies on one, such as Google, Entra ID, Keycloak or Dex, all named in its docs, and enforces the result at the edge. That separation is the main reason to choose it: you keep your existing identity system and add authentication to applications without code changes. Self-hosted identity providers such as Keycloak, Authentik or Pocket ID solve a different problem, user storage and sign-in, and are often deployed together with a proxy like this one.

Some reverse proxies offer forward-authentication hooks, and the integration guides show OAuth2 Proxy filling that role behind Nginx, Traefik and Caddy rather than replacing them. If your proxy or platform already provides built-in OIDC enforcement that meets your needs, a separate component may be unnecessary.

Things to know before adopting OAuth2 Proxy

• License: MIT, so there are no copyleft obligations.
• Trust forwarded headers carefully: when --reverse-proxy is enabled, set --trusted-proxy-ip. The docs warn that if it is unset, OAuth2 Proxy currently trusts all source IPs for backwards compatibility, so a client that reaches it directly may spoof forwarded headers.
• Sign-out is local: /oauth2/sign_out only clears OAuth2 Proxy's own cookies; users stay signed in at the provider unless you also redirect to the provider's sign-out page.
• Deprecated providers: the original Keycloak and Microsoft Azure providers are marked deprecated in favour of Keycloak OIDC and Microsoft Entra ID.
• Multiple providers: the docs state the feature to configure multiple providers is not complete.
• Upgrade old versions: the README strongly recommends upgrading anything older than v6.0.0 because of an open redirect vulnerability.
• Nightly images are not for production: images built from master are published separately and are considered unstable.
• Volunteer-run: the maintainers note review times vary and they favour stability, so changes can take a while to merge.

Project activity

As of October 2026 the repository has about 15,200 stars and 2,200 forks. It was created on GitHub in September 2017, is written in Go, is licensed under MIT and had commits in October 2026. The README lists the SAP Open Source Program as a sponsor and points users to the #oauth2-proxy channel on the CNCF Slack. The code is at github.com/oauth2-proxy/oauth2-proxy and the documentation is at oauth2-proxy.github.io/oauth2-proxy.