OAuth2 Proxy — Reverse Proxy for Authentication with Any Provider

Introduction

OAuth2 Proxy is a lightweight reverse proxy that authenticates requests using OAuth2 providers before forwarding traffic to upstream services. It removes the need to implement authentication logic inside each application, letting teams centralize identity management at the infrastructure layer.

What OAuth2 Proxy Does

• Authenticates users via Google, GitHub, GitLab, Azure AD, Keycloak, and any OIDC-compliant provider
• Passes verified user identity (email, groups, tokens) to upstream services via HTTP headers
• Supports cookie-based sessions with configurable TTL and refresh
• Provides an authorization API endpoint for use with Nginx auth_request or Traefik ForwardAuth
• Handles sign-in, sign-out, and callback flows out of the box

Architecture Overview

OAuth2 Proxy runs as a standalone Go binary or container. Incoming requests hit the proxy first; unauthenticated users are redirected to the configured OAuth2 provider. After successful login, the provider redirects back with an authorization code. The proxy exchanges the code for tokens, creates a signed session cookie, and forwards requests to the upstream with identity headers attached. Session state can be stored in cookies, Redis, or a filesystem.

Self-Hosting & Configuration

• Deploy via Docker image, Helm chart, or pre-built binary from GitHub releases
• Configure providers via environment variables or a TOML/YAML config file
• Set OAUTH2_PROXY_UPSTREAMS to point at your backend services
• Use Redis for session storage in multi-replica deployments
• Place behind Nginx or Traefik and use auth_request / ForwardAuth for fine-grained route protection

Key Features

• Supports 15+ OAuth2/OIDC providers out of the box
• Sub-millisecond overhead per authenticated request
• Built-in skip-auth paths for health checks and public routes
• Group-based and email-domain-based access control
• Refresh tokens to extend sessions without re-login

Comparison with Similar Tools

• Keycloak — Full identity platform with user management; oauth2-proxy is lighter and adds auth to existing providers
• Authelia — Self-hosted 2FA portal; oauth2-proxy delegates authentication to external IdPs
• Pomerium — Identity-aware proxy with policy engine; oauth2-proxy is simpler with less configuration surface
• Traefik ForwardAuth — Traefik-native but limited; oauth2-proxy supports any reverse proxy

FAQ

Q: Can I protect multiple upstream services with one instance? A: Yes. Configure multiple upstreams with path-based routing or deploy in auth_request mode behind a reverse proxy.

Q: Does it support multi-factor authentication? A: MFA is handled by the upstream identity provider (e.g., Google, Azure AD). OAuth2 Proxy enforces whatever authentication the provider requires.

Q: How do I restrict access to specific users? A: Use --email-domain, --authenticated-emails-file, or --allowed-groups flags to control who can access protected resources.

Q: Can I use it without a reverse proxy in front? A: Yes. OAuth2 Proxy can serve as the primary entry point and proxy traffic directly to your upstream application.

Sources

• https://github.com/oauth2-proxy/oauth2-proxy
• https://oauth2-proxy.github.io/oauth2-proxy/