OAuth2 Proxy

Description

OAuth2 Proxy est un outil flexible qui peut fonctionner de deux manières :

1. Comme reverse proxy autonome : il intercepte les requêtes, redirige vers le provider OAuth pour login, et ne laisse passer que les utilisateurs authentifiés.
2. Comme middleware : intégré à un reverse proxy existant (Nginx, Caddy, Traefik, HAProxy) via le mécanisme auth_request ou auth_jwt.

Caractéristiques :

• ✅ Support de 50+ providers : Google, Azure (Entra ID), Microsoft, GitHub, GitLab, Okta, Auth0, Keycloak, Authentik, Keycloak, login.gov, etc.
• ✅ OIDC, OAuth2, SAML : supporte tous les standards modernes
• ✅ Groupes et domaines : restrictions par email domain, groupes AD, rôles
• ✅ Headers d'identité : forward X-Forwarded-User, X-Forwarded-Email, X-Forwarded-Groups aux apps upstream
• ✅ Cookie sécurisé + session : gestion des sessions côté serveur
• ✅ CNCF Sandbox project : gouvernance open source saine
• ✅ Multi-plateforme : binaires (Linux/macOS/Windows/ARM/ppc64le/s390x), Docker (distroless)
• ✅ Reverse proxy ou middleware : s'adapte à toutes les architectures

Positionnement : c'est l'alternative "light" à Authentik/Authelia. Authentik/Authelia sont des IDP complets (Identity Provider), OAuth2 Proxy est un consommateur d'IDP — il ajoute l'auth devant une app qui n'en a pas, en s'appuyant sur un IDP existant (Google, Microsoft, Keycloak...).

Cas d'usage typique :

• Vous avez une app "self-hosted" (Grafana, Jenkins, WikiJS...) qui n'a pas d'auth native ou une auth locale faible → vous mettez OAuth2 Proxy devant
• Vous voulez éviter de gérer 50 comptes locaux → vous centralisez via Google/Azure AD
• Vous utilisez Traefik et voulez ajouter de l'auth sur un sous-domaine → forwardAuth middleware

Public cible : admins qui veulent centraliser l'auth sans monter un IDP complet, ou qui ont déjà un IDP (Keycloak, Authentik) et veulent un client simple devant leurs apps.

Installation

Option 1 : Docker Compose (standalone reverse proxy)

# docker-compose.yml
version: '3.8'
services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.2
    container_name: oauth2-proxy
    restart: unless-stopped
    command: --config=/etc/oauth2-proxy.cfg
    volumes:
      - ./oauth2-proxy.cfg:/etc/oauth2-proxy.cfg:ro
    ports:
      - "4180:4180"  # Port par défaut
    networks:
      - proxy
    environment:
      - OAUTH2_PROXY_CLIENT_ID=your-client-id
      - OAUTH2_PROXY_CLIENT_SECRET=your-client-secret
      - OAUTH2_PROXY_COOKIE_SECRET=random-32-bytes

networks:
  proxy:
    name: proxy

Variante Traefik (forwardAuth middleware) — la plus courante

# docker-compose.yml
version: '3.8'
services:
  traefik:
    image: traefik:v3.0
    restart: unless-stopped
    # ... config Traefik classique
    command:
      # ... vos autres options

  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.2
    container_name: oauth2-proxy
    restart: unless-stopped
    volumes:
      - ./oauth2-proxy.cfg:/etc/oauth2-proxy.cfg:ro
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.oauth2-proxy.entrypoints=websecure"
      - "traefik.http.routers.oauth2-proxy.rule=Host(`auth.example.com`)"
      - "traefik.http.routers.oauth2-proxy.tls.certresolver=letsencrypt"
      - "traefik.http.services.oauth2-proxy.loadbalancer.server.port=4180"

  # App protégée
  grafana:
    image: grafana/grafana
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.grafana.rule=Host(`grafana.example.com`)"
      - "traefik.http.routers.grafana.entrypoints=websecure"
      - "traefik.http.routers.grafana.tls.certresolver=letsencrypt"
      - "traefik.http.routers.grafana.middlewares=oauth2@docker"
      - "traefik.http.middlewares.oauth2.forwardauth.address=http://oauth2-proxy:4180"
      - "traefik.http.middlewares.oauth2.forwardauth.trustHeaders=true"
      - "traefik.http.middlewares.oauth2.forwardauth.authResponseHeaders=X-Forwarded-User,X-Forwarded-Email,X-Forwarded-Groups"

networks:
  proxy:
    name: proxy

Configuration

Fichier oauth2-proxy.cfg (exemple pour Google) :

## Alternatives

### Open Source
- [[app-tinyauth]] — Plus moderne, UI intégrée, supporte LDAP/OAuth2
- [[app-defguard]] — IDP complet + VPN (WireGuard)
- [[app-authman]] — Gestion d'identités alternative
- **Authelia** — IDP + reverse proxy auth, plus complet mais plus complexe
- **Authentik** — IDP full-featured (Identity Provider)
- **Keycloak** — IDP enterprise-grade (Red Hat)
- **PocketID** — OIDC provider simple, Go

### Propriétaires
- **Cloudflare Access** — Auth as a service (Zero Trust)
- **Okta Workforce** — IDP enterprise payant
- **Auth0** — IDP-as-a-service
- **Microsoft Entra ID** (ex Azure AD) — IDP Microsoft

## Sécurité

- **Cookie sécurisé HttpOnly + SameSite** : protection CSRF/XSS
- **Validation JWT** côté provider
- **Rotation automatique** des sessions
- **Whitelisting email/domaine** : restreindre l'accès à votre org
- **Headers d'audit** : trace `X-Forwarded-User` pour les logs
- **Distroless image** : surface d'attaque minimale
- **CNCF Sandbox** : gouvernance et audit de sécurité

> ⚠️ **OAuth2 Proxy n'est PAS un IDP** : il ne fournit pas d'auth aux apps upstream, il délègue à un IDP. Pour un IDP self-hosted complet, voir Authentik/Keycloak/Authelia.

## Ressources

- [Documentation officielle](https://oauth2-proxy.github.io/oauth2-proxy/)
- [Liste des providers](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/)
- [Slack Gopher #oauth2-proxy](https://gophers.slack.com/archives/CM2RSS25N)
- [CNCF Sandbox](https://www.cncf.io/projects/oauth2-proxy/)
- [Exemples d'intégration](https://github.com/oauth2-proxy/oauth2-proxy/tree/master/contrib)

## /etc/oauth2-proxy.cfg

# Provider
provider = "google"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

# Cookie secret (générer : openssl rand -base64 32)
cookie_secret = "RANDOM_32_BYTES_BASE64"
cookie_name = "_oauth2_proxy"
cookie_secure = true
cookie_domains = [".example.com"]

# Email restrictions
email_domains = ["example.com"]  # Restreint au domaine corporate
# Ou :
# emails = ["[email protected]", "[email protected]"]  # Whitelist

# Upstreams
http_address = "0.0.0.0:4180"
upstreams = ["static://200"]

# Headers
set_xauthrequest = true
set_authorization_header = true
pass_access_token = true

# Provider specific (Google)
google_workspace_domains = ["example.com"]

1. Créer un OAuth Client sur votre provider (Google Cloud Console, Azure Portal, Keycloak...)
2. Callback URL à enregistrer : https://oauth2-proxy.example.com/oauth2/callback
3. Générer cookie_secret : openssl rand -base64 32
4. Lancer et tester sur une app
5. Vérifier les headers : X-Forwarded-User, X-Forwarded-Email, X-Forwarded-Groups