wiki/Catalogue-Self-Hosted/apps/app-oauth2-proxy.md

---
title: OAuth2 Proxy
created: 2026-06-06
updated: 2026-06-06
type: app
tags: [catalogue, reverse-proxy, authentication, authentification, sso, oidc, oauth2, go, cncf, securite]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Reverse+Proxy, https://github.com/oauth2-proxy/oauth2-proxy]
---
# 🔐 OAuth2 Proxy

> **Reverse proxy et middleware d'authentification** qui s'intercale devant vos apps pour les protéger par **OAuth2 / OIDC / SAML**. Projet **CNCF Sandbox**, supporte Google, Azure AD, GitHub, Okta, Keycloak, Authentik, et 50+ providers. Le standard de l'auth-as-a-sidecar.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [oauth2-proxy.github.io/oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) |
| **GitHub** | [oauth2-proxy/oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy) |
| **License** | MIT |
| **Langage** | Go |
| **Étoiles GitHub** | 14.5k ⭐ |
| **Dernière MAJ** | 2026-04-17 |
| **Catégorie** | [[cat-reverse-proxy|Reverse Proxy]], [[cat-authentication|Authentification]] |

## 📝 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)

```yaml
# 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

```yaml
# 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 Initiale

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

```ini
## /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 = ["alice@example.com", "bob@example.com"]  # 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`

## 🔄 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)

## Pages Liées
- [[cat-reverse-proxy]] — Catégorie Reverse Proxy
- [[cat-authentication|Authentification]] — Catégorie Authentification
- [[app-tinyauth]] — Alternative moderne
- [[app-traefik]] — forwardAuth middleware
- [[app-defguard]] — IDP complet
- [[comparatif-reverse-proxy]] — Comparaison détaillée