IREX - OAuth2-Proxy avec Keycloak : de l'architecture au déploiement en production

1. Introduction

Ici, nous allons ouvrir le capot. Comment OAuth2-Proxy intercepte-t-il les requêtes ? Que se passe-t-il précisément entre le navigateur, Nginx, OAuth2-Proxy et Keycloak ? Comment le déployer en quelques minutes avec Docker ?

Ce guide s'adresse à toute personne qui souhaite comprendre et mettre en œuvre OAuth2-Proxy dans un environnement réel, avec Keycloak comme fournisseur d'identité principal.

2. Le flux d'authentification

Avant de configurer quoi que ce soit, il est essentiel de comprendre ce qui se passe réellement sous le capot. Cette section décrit l'architecture mise en place et le chemin précis qu'emprunte chaque requête, de l'utilisateur jusqu'à l'application protégée.

2.1 Architecture générale : Nginx, OAuth2-Proxy et Keycloak

Imaginons une instance Prometheus sur https://prometheus.monentreprise.com à protéger avec Keycloak. La chaîne de traitement est la suivante :

Navigateur → Nginx (reverse proxy SSL) → OAuth2-Proxy → Prometheus
OAuth2-Proxy ↔ Keycloak (vérification OIDC)

• Nginx : point d'entrée unique. Il termine le TLS et transmet toutes les requêtes à OAuth2-Proxy.
• OAuth2-Proxy : le gardien. Il vérifie l'authentification à chaque requête et déclenche le flux Keycloak si nécessaire.
• Keycloak : le fournisseur d'identité. Il valide les identifiants et émet les tokens selon OpenID Connect.
• Prometheus : l'application protégée. Elle reçoit les requêtes comme si elles venaient directement de l'utilisateur.

2.2 Flux détaillé — premier accès

1. L'utilisateur saisit https://prometheus.monentreprise.com dans son navigateur.
2. Nginx transmet la requête à OAuth2-Proxy sur le port 4180.
3. OAuth2-Proxy ne détecte aucun cookie valide. Il génère un paramètre state aléatoire (protection anti-CSRF) et redirige vers Keycloak avec une redirect_uri de retour.
4. Keycloak affiche sa page de connexion. L'utilisateur saisit ses identifiants.
5. Keycloak redirige vers /oauth2/callback avec un code d'autorisation temporaire.
6. OAuth2-Proxy échange ce code contre un access token et un id token — c'est le flux Authorization Code (RFC 6749).
7. OAuth2-Proxy valide la signature via la clé JWKS de Keycloak et crée un cookie de session chiffré (AES-GCM).
8. La requête est transmise à Prometheus. L'utilisateur accède à l'interface.

Pour l'utilisateur, cette mécanique est totalement transparente. Il n'a vu qu'une page de connexion Keycloak.

Flux détaillé — accès suivants et refresh silencieux

1. OAuth2-Proxy détecte le cookie existant et vérifie sa validité (expiration, signature HMAC).
2. Si valide, la requête est immédiatement transmise à Prometheus sans redirection.
3. Si expiré mais le refresh token encore valide, OAuth2-Proxy déclenche un refresh silencieux auprès de Keycloak.
4. Si les deux tokens sont expirés, l'utilisateur est redirigé vers Keycloak pour une nouvelle authentification.

3. Déploiement et sécurisation

Cette étape concrétise la stratégie de défense en s'appuyant sur une infrastructure conteneurisée, où l'orchestration des services et la gestion des accès deviennent les piliers de la résilience du système.

3.1 Déploiement concret : Docker + Nginx + Keycloak

Nous supposons que Keycloak est déjà en place avec un realm ACRA et un client prometheus-client.

Étape 1 — Créer le client dans Keycloak

• ID client : prometheus-client, type d'accès : confidential.
• Redirect URI : https://prometheus.monentreprise.com/oauth2/callback.
• Récupérez le client secret dans l'onglet Credentials.

Étape 2 — Générer le cookie secret

openssl rand -base64 32

Conservez cette valeur. Elle chiffre les cookies de session. Ne la commitez jamais dans Git.

Étape 3 — Lancer OAuth2-Proxy avec Docker

Étape 4 — Configurer Nginx comme reverse proxy

Nginx termine le TLS et transmet tout le trafic à OAuth2-Proxy, qui décide si la requête atteint Prometheus ou repart vers Keycloak.

Étape 5 — Vérifier le bon fonctionnement

# Vérifier qu'OAuth2-Proxy répond
curl -I http://localhost:4180/ping

# Résultat attendu
HTTP/1.1 200 OK

# Vérifier les logs en cas de problème
docker logs oauth2-proxy --tail 50

3.2 Les autres fournisseurs OIDC supportés

OAuth2-Proxy supporte nativement de nombreux fournisseurs via le paramètre --provider :

• Keycloak (open source, auto-hébergé) : choix privilégié en entreprise pour sa gestion des rôles et sa compatibilité LDAP/Active Directory.
• Google : idéal avec Google Workspace, configuration immédiate via la Google Cloud Console.
• Azure Active Directory : adapté aux environnements Microsoft 365, avec support des groupes Azure AD.
• Auth0 : service cloud clé en main pour les environnements SaaS.

Quel que soit le fournisseur, le flux reste identique. Seuls les paramètres (URL d'émetteur, client ID, client secret) changent.

3.3 Sécurité, bonnes pratiques et limites

Quelques bonnes pratiques à respecter :

• Toujours utiliser HTTPS. Sans TLS, les cookies peuvent être interceptés (attaque man-in-the-middle).
• Générer un cookie secret fort avec openssl rand -base64 32. Sa compromission permettrait de forger des sessions.
• Ne jamais versionner les secrets. Utilisez des variables d'environnement ou un gestionnaire comme HashiCorp Vault.
• Désactiver --ssl-insecure-skip-verify en production. Toléré en développement uniquement, c'est une faille grave en production.

Limites à connaître :

• Pas de Single Logout natif : la révocation des sessions se fait directement depuis Keycloak.
• Pas d'autorisation granulaire : une fois authentifié, l'utilisateur accède à toute l'application. Pour un contrôle fin par rôle, un composant comme OPA est nécessaire.

Malgré ces limites, OAuth2-Proxy reste la solution la plus rapide pour sécuriser des applications sans OIDC natif.

4. Conclusion

Si vous gérez des outils comme Prometheus, Zabbix, Jenkins ou Grafana, l'intégration d'OAuth2-Proxy est l'une des mesures de sécurité les plus rapides à mettre en œuvre. En quelques minutes, vous obtenez :

• Une authentification centralisée et unifiée (SSO)
• Un support natif de Keycloak, Google, Azure AD, Auth0 et bien d'autres
• Des sessions sécurisées par cookie chiffré (AES-GCM)
• Une intégration totalement transparente pour les utilisateurs finaux
• Aucune modification du code de l'application protégée

5. Voir aussi

• OAuth2-Proxy : le gardien silencieux de vos applications sans authentification
• OAuth2 Proxy : la clé pour connecter Keycloak aux services non authentifiés