# OAuth2 Proxy

> Reverse proxy for authenticating requests via OAuth2.

- Category: Security & Networking
- Difficulty: intermediate
- Components: oauth2-proxy
- Tags: oauth2-proxy, authentication, sso, proxy
- Source: https://docker.recipes/security/oauth2-proxy

## Overview

OAuth2-Proxy is an open-source reverse proxy and static file server that provides authentication using providers like GitHub, Google, Azure AD, and any OpenID Connect-compatible service. Originally developed by Bitly and now maintained by the OAuth2-Proxy community, it acts as a gatekeeper between users and your applications, handling the entire OAuth2/OIDC authentication flow while keeping your backend services completely unaware of authentication complexity. OAuth2-Proxy validates user sessions, manages cookies, and forwards authenticated requests to upstream services with user headers attached.

This configuration establishes OAuth2-Proxy as a protective layer in front of your applications, intercepting all incoming requests and redirecting unauthenticated users through the OAuth2 flow with your chosen provider. Once authenticated, OAuth2-Proxy maintains user sessions via encrypted cookies and transparently proxies requests to your upstream services, injecting user identity headers that your applications can consume. The proxy handles token refresh, session validation, and logout flows automatically.

This setup is ideal for developers and organizations wanting to add enterprise-grade authentication to internal tools, development environments, or any web application without modifying application code. OAuth2-Proxy excels in scenarios where you need to quickly secure legacy applications, protect development instances, or implement organization-wide SSO across multiple services while maintaining the flexibility to use various OAuth2 providers.

## Features

- Multi-provider OAuth2/OIDC support including GitHub, Google, Azure AD, Keycloak, and custom OIDC providers
- Encrypted cookie-based session management with configurable expiration and refresh
- Upstream request forwarding with injected user identity headers (X-Forwarded-User, X-Forwarded-Email)
- Email domain filtering and whitelist/blacklist capabilities for access control
- Integration with reverse proxy auth modules (nginx auth_request, Traefik ForwardAuth)
- Configurable upstream routing with support for multiple backend services
- Built-in static file serving for custom login pages and error handling
- Comprehensive logging and metrics endpoints for monitoring authentication events

## Use cases

- Protecting internal development tools and staging environments with GitHub organization authentication
- Adding Google Workspace SSO to legacy applications without code modifications
- Securing self-hosted services like Grafana, Jenkins, or documentation sites behind corporate identity providers
- Implementing email domain-based access control for SaaS applications in multi-tenant environments
- Creating authentication gateways for microservices architectures with centralized user management
- Protecting API endpoints and webhooks with OAuth2 bearer token validation
- Building secure access to homelab services using external OAuth2 providers

## Prerequisites

- OAuth2 application registration with your chosen provider (GitHub App, Google OAuth2 client, etc.)
- Client ID and Client Secret from your OAuth2 provider configuration
- Minimum 512MB RAM allocation for OAuth2-Proxy container operations
- Port 4180 available for OAuth2-Proxy HTTP listener
- SSL/TLS termination configured upstream (OAuth2 providers require HTTPS redirect URIs)
- Understanding of your target upstream service URLs and routing requirements

## docker-compose.yml

```yaml
services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:latest
    container_name: oauth2-proxy
    restart: unless-stopped
    environment:
      OAUTH2_PROXY_PROVIDER: github
      OAUTH2_PROXY_CLIENT_ID: ${CLIENT_ID}
      OAUTH2_PROXY_CLIENT_SECRET: ${CLIENT_SECRET}
      OAUTH2_PROXY_COOKIE_SECRET: ${COOKIE_SECRET}
      OAUTH2_PROXY_EMAIL_DOMAINS: "*"
      OAUTH2_PROXY_UPSTREAMS: http://upstream:8080
      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
    ports:
      - "4180:4180"
```

## .env

```bash
CLIENT_ID=github-client-id
CLIENT_SECRET=github-client-secret
COOKIE_SECRET=generate-32-char-secret
```

## Usage notes

- Docs: https://oauth2-proxy.github.io/oauth2-proxy/
- Auth proxy on port 4180 - point reverse proxy here
- Generate COOKIE_SECRET: openssl rand -base64 32 | head -c 32
- Supports GitHub, Google, Azure, Keycloak, any OIDC provider
- Set OAUTH2_PROXY_UPSTREAMS to your protected service
- Use with nginx auth_request or Traefik forwardAuth middleware

## Troubleshooting

- Invalid client: oauth2: cannot fetch token - Verify CLIENT_ID and CLIENT_SECRET match your OAuth2 provider application settings exactly
- Cookie domain mismatch errors: Configure OAUTH2_PROXY_COOKIE_DOMAIN to match your external hostname or use cookie-domain flag
- Upstream connection refused: Ensure OAUTH2_PROXY_UPSTREAMS points to accessible service URLs and containers can communicate via Docker network
- OIDC discovery failed: For custom providers, manually configure OAUTH2_PROXY_OIDC_ISSUER_URL and verify .well-known/openid_configuration endpoint accessibility
- Authentication loop redirects: Check that your OAuth2 provider's authorized redirect URI exactly matches your OAuth2-Proxy external URL including https scheme
- 403 Forbidden after authentication: Verify OAUTH2_PROXY_EMAIL_DOMAINS setting allows your user's email domain or set to '*' for testing

