IREX - Sécurisation d'applications sans support OIDC natif via OAuth2-Proxy - Partie 2

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 ? Quelles sont les règles de sécurité à respecter impérativement ?

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

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

Avant d'entrer dans les détails du flux, posons l'architecture. Imaginons que vous ayez une instance Prometheus accessible sur https://prometheus.monentreprise.com que vous souhaitez protéger avec Keycloak.

La chaîne de traitement mise en place est la suivante :

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

Chaque composant a un rôle précis :

• Nginx : point d'entrée unique. Il termine le TLS (déchiffrement HTTPS) et transmet toutes les requêtes à OAuth2-Proxy. Il ne parle jamais directement à Prometheus.
• OAuth2-Proxy : le gardien. Il vérifie l'authentification à chaque requête. Si l'utilisateur est authentifié, il transmet la requête à Prometheus. Sinon, il déclenche le flux de connexion Keycloak.
• Keycloak : le fournisseur d'identité. Il gère les utilisateurs, valide les identifiants, et émet les tokens selon le standard OpenID Connect.
• Prometheus : l'application protégée. Elle ne sait pas qu'OAuth2-Proxy existe. Elle reçoit les requêtes comme si elles venaient directement de l'utilisateur.

2.2 Flux détaillé — premier accès

Voici ce qui se passe, étape par étape, lorsqu'un utilisateur accède pour la première fois à l'application protégée :

1. L'utilisateur saisit https://prometheus.monentreprise.com dans son navigateur.
2. Nginx reçoit la requête HTTPS et la transmet à OAuth2-Proxy sur le port 4180.
3. OAuth2-Proxy ne détecte aucun cookie de session valide. Il génère un paramètre state aléatoire (protection anti-CSRF, Cross-Site Request Forgery) et redirige l'utilisateur vers Keycloak avec une redirect_uri de retour.
4. Keycloak affiche sa page de connexion. L'utilisateur saisit ses identifiants.
5. Keycloak valide les identifiants et redirige l'utilisateur vers https://prometheus.monentreprise.com/oauth2/callback avec un code d'autorisation temporaire (valable quelques secondes seulement).
6. OAuth2-Proxy intercepte ce callback et envoie une requête confidentielle à Keycloak pour échanger le code contre un access token et un id token. C'est le flux Authorization Code, défini par la RFC 6749.
7. OAuth2-Proxy valide la signature du token via la clé publique JWKS de Keycloak, extrait les informations de l'utilisateur (email, rôles), et crée un cookie de session chiffré (AES-GCM) dans le navigateur.
8. La requête initiale vers Prometheus est enfin transmise. 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. Pour Prometheus, elle n'a rien vu du tout.

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

Lors des accès suivants, le comportement est radicalement différent et beaucoup plus rapide :

1. OAuth2-Proxy détecte le cookie de session existant dans la requête et vérifie sa validité (expiration, signature HMAC).
2. Si le cookie est valide, la requête est immédiatement transmise à Prometheus sans aucune redirection vers Keycloak. Aucune interaction supplémentaire n'est nécessaire.
3. Si le cookie est expiré mais que le refresh token est encore valide, OAuth2-Proxy déclenche un refresh silencieux auprès de Keycloak : il obtient un nouveau access token sans que l'utilisateur ait à se reconnecter.
4. Si les deux tokens sont expirés, OAuth2-Proxy redirige l'utilisateur vers Keycloak pour une nouvelle authentification complète.

Cette gestion automatique du cycle de vie des tokens est l'un des grands avantages d'OAuth2-Proxy : l'utilisateur bénéficie d'une session longue durée sans jamais devoir se reconnecter manuellement, tant que son compte est actif dans Keycloak.

3. Déploiement et sécurisation

3.1 Déploiement concret : Docker + Nginx + Keycloak

Voici comment déployer OAuth2-Proxy en pratique. Nous supposons que Keycloak est déjà en place et qu'un realm nommé ACRA a été configuré avec un client prometheus-client.

Étape 1 — Créer le client dans Keycloak

Dans l'interface Keycloak :

• Créez un client avec l'ID prometheus-client.
• Type d'accès : confidential.
• Redirect URI valide : 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 sert à chiffrer les cookies de session côté client. Ne la commitez jamais dans un dépôt 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. C'est OAuth2-Proxy qui décide ensuite si la requête est autorisée à atteindre Prometheus ou si elle doit être redirigée 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 n'est pas lié à Keycloak. Il supporte nativement une large gamme de fournisseurs d'identité via le paramètre --provider :

• Keycloak (open source, auto-hébergé) : le choix privilégié en entreprise pour sa richesse fonctionnelle, sa gestion des rôles et sa compatibilité LDAP/Active Directory.
• Google : idéal si votre organisation utilise Google Workspace. La configuration est quasi immédiate via la Google Cloud Console.
• Azure Active Directory (Microsoft) : adapté aux environnements Microsoft 365, avec support des groupes Azure AD.
• Auth0 : service cloud clé en main, apprécié pour sa simplicité de mise en œuvre dans les environnements SaaS.

Quel que soit le fournisseur choisi, le flux reste identique du point de vue d'OAuth2-Proxy. Seuls les paramètres de configuration (URL d'émetteur, client ID, client secret) changent.

3.3 Sécurité, bonnes pratiques et limites

Quelques bonnes pratiques à respecter :

• Toujours utiliser HTTPS. OAuth2-Proxy n'émet des cookies avec le flag Secure que si le site est servi en HTTPS. Sans TLS, les cookies de session peuvent être interceptés par un attaquant sur le réseau (attaque de type man-in-the-middle).
• Générer un cookie secret cryptographiquement fort avec openssl rand -base64 32. Ce secret est utilisé pour chiffrer et signer les cookies (AES-GCM + HMAC). Sa compromission permettrait à un attaquant de forger des sessions valides.
• Ne jamais versionner les secrets (client secret Keycloak, cookie secret). Utilisez des variables d'environnement, un fichier .env ignoré par Git, ou un gestionnaire de secrets comme HashiCorp Vault ou les Kubernetes Secrets.
• Désactiver --ssl-insecure-skip-verify en production. Ce paramètre désactive la vérification du certificat TLS de Keycloak. Il est toléré en environnement de développement avec des certificats auto-signés, mais constitue une faille de sécurité grave en production.

Limites à connaître :

• Pas de Single Logout (SLO) natif : OAuth2-Proxy ne propage pas la déconnexion à l'ensemble des applications. Pour révoquer toutes les sessions d'un utilisateur, il faut agir directement depuis Keycloak (invalidation de session côté serveur).
• Pas d'autorisation granulaire : OAuth2-Proxy vérifie que l'utilisateur est authentifié, mais ne gère pas les droits d'accès au niveau des ressources. Une fois connecté, l'utilisateur accède à toute l'application. Pour un contrôle plus fin (par rôle, par groupe), il faut compléter avec des vérifications applicatives ou un composant dédié comme OPA (Open Policy Agent).

Malgré ces limites, pour l'immense majorité des cas d'usage en entreprise, OAuth2-Proxy constitue la solution la plus rapide et la plus efficace pour sécuriser des applications sans authentification OIDC native.

4. Conclusion

Si vous gérez des outils comme Prometheus, Zabbix, Jenkins ou Grafana dans un environnement professionnel ou académique, l'intégration d'OAuth2-Proxy est probablement l'une des mesures de sécurité les plus rapides et les plus efficaces que vous puissiez mettre en œuvre.

En quelques minutes de configuration, 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

• IREX – OAuth2-Proxy : sécuriser des applications sans support OIDC natif (Partie 1)