docker.recipes

OAuth2 Proxy

intermediate

Reverse proxy for authenticating requests via OAuth2.

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.

Key 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

Common Use Cases

  • 1Protecting internal development tools and staging environments with GitHub organization authentication
  • 2Adding Google Workspace SSO to legacy applications without code modifications
  • 3Securing self-hosted services like Grafana, Jenkins, or documentation sites behind corporate identity providers
  • 4Implementing email domain-based access control for SaaS applications in multi-tenant environments
  • 5Creating authentication gateways for microservices architectures with centralized user management
  • 6Protecting API endpoints and webhooks with OAuth2 bearer token validation
  • 7Building 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  oauth2-proxy: 
3    image: quay.io/oauth2-proxy/oauth2-proxy:latest
4    container_name: oauth2-proxy
5    restart: unless-stopped
6    environment: 
7      OAUTH2_PROXY_PROVIDER: github
8      OAUTH2_PROXY_CLIENT_ID: ${CLIENT_ID}
9      OAUTH2_PROXY_CLIENT_SECRET: ${CLIENT_SECRET}
10      OAUTH2_PROXY_COOKIE_SECRET: ${COOKIE_SECRET}
11      OAUTH2_PROXY_EMAIL_DOMAINS: "*"
12      OAUTH2_PROXY_UPSTREAMS: http://upstream:8080
13      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
14    ports: 
15      - "4180:4180"

.env Template

.env
1CLIENT_ID=github-client-id
2CLIENT_SECRET=github-client-secret
3COOKIE_SECRET=generate-32-char-secret

Usage Notes

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

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  oauth2-proxy:
5    image: quay.io/oauth2-proxy/oauth2-proxy:latest
6    container_name: oauth2-proxy
7    restart: unless-stopped
8    environment:
9      OAUTH2_PROXY_PROVIDER: github
10      OAUTH2_PROXY_CLIENT_ID: ${CLIENT_ID}
11      OAUTH2_PROXY_CLIENT_SECRET: ${CLIENT_SECRET}
12      OAUTH2_PROXY_COOKIE_SECRET: ${COOKIE_SECRET}
13      OAUTH2_PROXY_EMAIL_DOMAINS: "*"
14      OAUTH2_PROXY_UPSTREAMS: http://upstream:8080
15      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
16    ports:
17      - "4180:4180"
18EOF
19
20# 2. Create the .env file
21cat > .env << 'EOF'
22CLIENT_ID=github-client-id
23CLIENT_SECRET=github-client-secret
24COOKIE_SECRET=generate-32-char-secret
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/oauth2-proxy/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

oauth2-proxy

Tags

#oauth2-proxy#authentication#sso#proxy

Category

Security & Networking

Related Recipes

Ad Space