Mettre une application derrière un SSO avec oauth2-proxy
Protégez une application sans login avec OIDC et oauth2-proxy. Configurez forward auth avec nginx ou Traefik et évitez les pièges de cookies et de redirection.
Authentification déléguée : comment fournir le SSO à une application sans connexion
oauth2-proxy fournit une authentification unique à une application qui n’a pas de système de connexion. Cela fonctionne parce que le reverse proxy placé devant cette application intercepte chaque requête, demande à oauth2-proxy si elle contient une session valide, puis ne transmet la requête au backend que si la réponse est positive. Le code de l’application ne change jamais, car l’application ne voit pas ce contrôle.
Le contrôle ajoute une requête HTTP. Le proxy envoie une copie des en-têtes de la requête entrante à /oauth2/auth et lit le code d’état. Le code 202 indique que le contrôle a réussi : le proxy transmet alors la requête d’origine à l’application. Le code 401 indique qu’aucune session valide n’est présente : le proxy redirige alors le navigateur vers /oauth2/sign_in, qui affiche par défaut une page de connexion. /oauth2/start démarre une connexion OpenID Connect (OIDC) auprès de votre fournisseur d’identité ; skip_provider_button = true permet à /oauth2/sign_in de la démarrer automatiquement. OIDC est la couche d’identité construite au-dessus d’OAuth 2.0. Le fournisseur est celui que vous utilisez déjà pour les connexions.
Ce mécanisme porte un nom dans chaque reverse proxy. Nginx appelle la directive auth_request. Traefik appelle le middleware forwardAuth. Caddy l’écrit forward_auth. Le service qui répond à la sous-requête peut également être remplacé. oauth2-proxy est le choix courant, car il utilise directement OIDC et ne nécessite pas sa propre base de données.
Tracez la limite de confiance avant d’écrire la moindre configuration
Après un contrôle réussi, oauth2-proxy renvoie l’identité dans des en-têtes de réponse, puis le reverse proxy les recopie dans la requête envoyée à l’upstream. Avec set_xauthrequest activé, vous obtenez X-Auth-Request-User et X-Auth-Request-Email. L’application lit ces en-têtes et leur fait confiance.
C’est tout le modèle de sécurité. Il faut donc en expliciter la conséquence : tout ce qui peut ouvrir une connexion TCP vers le port de l’application peut définir lui-même ces en-têtes et se faire passer pour n’importe quel utilisateur. Un seul curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ suffit à contourner entièrement la protection s’il atteint directement l’application.
L’application ne doit donc être accessible qu’à travers le proxy. Dans Docker Compose, supprimez le mapping ports: du service de l’application et laissez celui-ci sur le réseau interne. Seul le conteneur du proxy pourra ainsi s’y connecter. Sur un hôte bare metal, liez l’application à 127.0.0.1:3000 au lieu de 0.0.0.0:3000. Vérifiez ensuite ce que vous avez réellement exposé :
sudo ss -tlnp | grep 3000Une ligne contenant 0.0.0.0:3000 signifie que l’application répond sur l’adresse IP publique et que votre protection est purement décorative. 127.0.0.1:3000 est le résultat attendu. Une règle de firewall constitue une seconde couche utile, mais l’adresse d’écoute est celle qui restera valable si un autre outil vide votre ruleset.
Installer oauth2-proxy
En octobre 2026, la version actuelle est v7.15.5, publiée le 1 octobre 2026. Elle corrige deux avis de sécurité critiques. L’un concerne un contournement de skip_auth_routes qui affecte toutes les versions postérieures à v7.5.0. N’installez donc aucune version plus ancienne. Installez le binaire et vérifiez le téléchargement :
cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --versionsha256sum -c doit afficher une ligne qui se termine par OK. S’il affiche FAILED, arrêtez-vous et téléchargez à nouveau le fichier au lieu d’exécuter le binaire.
Dans Docker, l’image est quay.io/oauth2-proxy/oauth2-proxy et vous devez figer le tag : quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Si vous laissez la valeur latest, une simple docker compose pull se transforme en mise à niveau imprévue du processus qui protège toutes les applications du serveur.
Générer le secret du cookie
Le cookie de session est chiffré, et cookie_secret est la clé. La clé de chiffrement doit faire exactement 16, 24 ou 32 octets, car elle devient une clé AES (Advanced Encryption Standard). oauth2-proxy accepte une valeur en base64 compatible avec les URL qui se décode en l’une de ces longueurs, ou un secret brut de l’une de ces longueurs. Dans le cas contraire, il refuse de démarrer et signale une erreur de démarrage concernant le secret du cookie. La commande ci-dessous produit une valeur de 44 caractères qui encode une clé de 32 octets.
openssl rand -base64 32 | tr -- '+/' '-_'Le tr n’est pas purement esthétique. Il convertit la base64 standard en alphabet compatible avec les URL utilisé par oauth2-proxy pour décoder le secret.
Deux règles s’appliquent à cette valeur. Utilisez un secret différent pour chaque déploiement. Si vous exécutez plusieurs instances d’oauth2-proxy derrière le même domaine, utilisez le même secret pour toutes, car un cookie chiffré par une instance doit pouvoir être lu par les autres.
Rédiger la configuration d’oauth2-proxy
Conservez les paramètres dans un fichier plutôt que dans une longue ligne de commande, afin que le secret client n’apparaisse jamais dans la sortie de ps.
# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true
provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"
redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]
email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]reverse_proxy = true indique à oauth2-proxy de faire confiance aux en-têtes X-Forwarded-* transmis par le proxy situé en amont. Sans ce paramètre, oauth2-proxy considère l’adresse du proxy comme l’adresse du client et peut déterminer à tort que la requête n’est pas arrivée en HTTPS.
trusted_proxy_ips limite les pairs autorisés à fournir ces en-têtes. Par défaut, toutes les sources sont approuvées. Cela n’est sûr ici que parce que http_address maintient oauth2-proxy sur 127.0.0.1. Si oauth2-proxy écoute plutôt sur un réseau Docker, définissez ce paramètre sur l’adresse de votre reverse proxy.
upstreams = ["static://202"] fait répondre oauth2-proxy par 202 pour une requête authentifiée, sans transmettre la requête. C’est exactement ce qu’exige l’authentification déportée, puisque le reverse proxy se charge du proxying. Dans l’autre architecture, oauth2-proxy se trouve directement dans le chemin des requêtes, avec upstreams = ["http://127.0.0.1:3000"] et sans auth_request. Cette configuration est plus simple pour une seule application, mais elle ne s’adapte pas à dix applications.
email_domains = ["*"] autorise toutes les adresses que votre fournisseur authentifiera. Limitez ce paramètre à votre propre domaine ou, mieux encore, restreignez l’accès avec une association de groupe dans le fournisseur, puisque c’est là que vous gérez déjà les utilisateurs.
Exécutez-le sous systemd avec son propre utilisateur :
# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target
[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true
[Install]
WantedBy=multi-user.targetsudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/pingL’affichage de /ping et de OK signifie que le processus a démarré et chargé sa configuration. Il s’agit du point de terminaison de santé d’oauth2-proxy et il ne demande jamais de session. Si aucune réponse n’est reçue, consultez journalctl -u oauth2-proxy -n 50, car une URL d’émetteur incorrecte et un secret de cookie de longueur invalide provoquent tous deux un échec au démarrage, qui est indiqué dans les journaux.
Enregistrez l’URI de redirection auprès de votre fournisseur
Créez une application OIDC auprès de votre fournisseur et définissez son URI de redirection sur la valeur exacte de redirect_url dans la configuration : https://app.example.com/oauth2/callback. Exacte signifie que le schéma, l’hôte, le port et le chemin correspondent caractère par caractère. Une barre oblique finale produit une URI différente.
C’est l’échec le plus fréquent de toute la configuration, et il se produit avant même qu’oauth2-proxy soit sollicité. Le fournisseur rejette la demande d’autorisation et affiche sa propre page d’erreur. Rien n’apparaît donc dans le journal d’oauth2-proxy. La barre d’adresse permet de l’identifier : le navigateur se trouve encore sur le domaine de votre fournisseur, et la chaîne de requête contient error=invalid_request ou la page nomme directement redirect_uri. Dans ce cas, corrigez l’enregistrement de l’application auprès du fournisseur, pas la configuration du proxy.
Copiez l’URL de l’issuer depuis le fournisseur au lieu de la saisir manuellement. oauth2-proxy ajoute /.well-known/openid-configuration à oidc_issuer_url et récupère ce document de découverte au démarrage. Vérifiez-le d’abord vous-même :
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400La présence d’un objet JSON contenant une clé authorization_endpoint constitue une première vérification. La valeur issuer du document doit également correspondre exactement à oidc_issuer_url. Une réponse 404 ou une page d’erreur HTML indique que l’URL est incorrecte. oauth2-proxy échouera lui aussi à démarrer avec cette même réponse 404. Si vous n’avez pas encore choisi de fournisseur, la comparaison de Keycloak, Authentik et Zitadel présente les compromis entre ces solutions, et l’exécution d’Authentik comme serveur SSO autonome détaille la partie fournisseur de cette configuration.
Nginx : auth_request
Nginx effectue l’authentification déléguée avec auth_request, qui lance une sous-requête interne et prend une décision selon son code d’état.
# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name app.example.com;
location /oauth2/ {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Auth-Request-Redirect $request_uri;
}
location = /oauth2/auth {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header Content-Length "";
proxy_pass_request_body off;
}
location / {
auth_request /oauth2/auth;
error_page 401 = @oauth2_signin;
auth_request_set $user $upstream_http_x_auth_request_user;
auth_request_set $email $upstream_http_x_auth_request_email;
proxy_set_header X-User $user;
proxy_set_header X-Email $email;
auth_request_set $auth_cookie $upstream_http_set_cookie;
add_header Set-Cookie $auth_cookie;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location @oauth2_signin {
return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}
}Trois détails justifient leur présence. proxy_pass_request_body off avec un Content-Length vide empêche nginx de transmettre un corps de requête au endpoint d’authentification, qui n’a besoin que des en-têtes.
L’association de auth_request_set $auth_cookie et add_header Set-Cookie renvoie un cookie de session renouvelé au navigateur. Sans elle, cookie_refresh ne fait discrètement rien, car nginx ignore le Set-Cookie de la sous-requête et le navigateur conserve l’ancienne valeur jusqu’à l’expiration de la session. Cette association gère un cookie. Les cookies de session répartis sur plusieurs valeurs nécessitent un traitement supplémentaire pour les autres parties, ou un stockage de session Redis.
error_page 401 = @oauth2_signin transforme un contrôle échoué en redirection vers la connexion. Sans cette directive, un visiteur non authentifié obtient une simple page 401 Authorization Required, sans possibilité de continuer.
Testez toujours la configuration avant de recharger nginx :
sudo nginx -t && sudo systemctl reload nginxSi les directives environnantes vous sont inconnues, l’anatomie d’une configuration de reverse proxy nginx présente la couche sous-jacente.
Traefik : middleware forwardAuth
Traefik a besoin de deux middlewares pour cette fonction. Le premier effectue le contrôle. Le second affiche la page de connexion lorsque le contrôle échoue.
# dynamic configuration
http:
middlewares:
oauth-auth:
forwardAuth:
address: https://oauth.example.com/oauth2/auth
trustForwardHeader: true
oauth-errors:
errors:
status:
- "401-403"
service: oauth-backend
query: "/oauth2/sign_in?rd={url}"Associez les deux au router placé devant votre application, avec oauth-errors avant oauth-auth, et publiez oauth2-proxy sur son propre router à l’adresse oauth.example.com, car le navigateur doit pouvoir atteindre /oauth2/sign_in et /oauth2/callback sans passer par le contrôle. Pour cet hôte de connexion distinct, définissez redirect_url sur https://oauth.example.com/oauth2/callback et enregistrez cette URI auprès du fournisseur.
Avec la configuration oauth2-proxy ci-dessus, /oauth2/sign_in affiche une page de connexion. Pour effectuer une redirection automatique, définissez skip_provider_button = true dans oauth2-proxy et ajoutez statusRewrites: {"401": 302} dans les paramètres errors de Traefik. Sans cette réécriture, Traefik renvoie la redirection automatique avec un statut 401 et le navigateur ne la suit pas. La réécriture seule ne lance pas le flux de connexion.
trustForwardHeader: true fait confiance aux en-têtes X-Forwarded-* entrants ; Traefik fournit l’hôte et l’URI d’origine à oauth2-proxy. Cette option est obsolète dans la documentation actuelle de Traefik. Définissez whitelist_domains pour couvrir également cet hôte. Sinon, oauth2-proxy supprime le paramètre rd, car il peut permettre une redirection ouverte, et tout le monde arrive sur / après la connexion. Un serveur Traefik se trouve généralement devant plusieurs applications à la fois, et router plusieurs applications Docker Compose avec une seule instance Traefik présente la structure des routers à laquelle cette configuration s’intègre.
Caddy : forward_auth
app.example.com {
handle /oauth2/* {
reverse_proxy 127.0.0.1:4180 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Uri {uri}
}
}
handle {
forward_auth 127.0.0.1:4180 {
uri /oauth2/auth
header_up X-Real-IP {remote_host}
copy_headers X-Auth-Request-User X-Auth-Request-Email
@error status 401
handle_response @error {
redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
}
}
reverse_proxy 127.0.0.1:3000
}
}L’ordre est important ici. Le bloc /oauth2/* vient en premier et ne contient aucun forward_auth, car un visiteur qui n’est pas connecté doit pouvoir atteindre les chemins de connexion et de callback. Si vous placez le contrôle devant ces chemins, la redirection de connexion se répète jusqu’à ce que le navigateur abandonne.
copy_headers transmet l’identité à la requête upstream. Il ne produit des valeurs que lorsque oauth2-proxy s’exécute avec set_xauthrequest = true. Le choix entre les proxies est une question distincte, et la comparaison de nginx, Caddy et Traefik l’examine.
Pourquoi la connexion revient-elle à la page de connexion ?
Vous vous connectez auprès du fournisseur, il vous redirige vers votre site, puis oauth2-proxy vous renvoie vers la page de connexion. Cette boucle signifie quʼoauth2-proxy nʼaccepte pas de session valide lors de la requête suivante. Le cookie de session peut être absent, ou présent mais ne pas passer la validation, par exemple si les instances utilisent des secrets de cookie différents. Ouvrez les outils de développement du navigateur, trouvez la requête vers /oauth2/callback qui suit la redirection depuis votre fournisseur, puis consultez son en-tête de réponse Set-Cookie. Si un cookie est défini à ce moment-là mais absent de la requête suivante, cʼest celui que le navigateur refuse. Sʼil est présent, recherchez dans le journal du serveur des erreurs de validation telles que cookie signature not valid et vérifiez que toutes les instances utilisent le même secret.
Lorsque le cookie qui disparaît est le cookie CSRF défini par oauth2-proxy lors de la redirection, la séquence ne boucle pas. Elle sʼarrête au callback, et le journal indique le cas :
No cookies were found in OAuth callback.ou, lorsquʼun autre cookie est bien arrivé mais pas celui attendu :
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF signifie falsification de requête intersite. Ce cookie permet dʼassocier un callback à la connexion qui lʼa déclenché. Le navigateur affiche une page dʼerreur 403 contenant :
Login Failed: Unable to find a valid CSRF token. Please try again.Les cookies absents ont les trois premières causes ci-dessous en commun ; un décalage dʼhorloge est une autre cause dʼéchec de validation. Vérifiez ces quatre points dans lʼordre.
cookie_secure = truealors que le navigateur a accédé au site en HTTP simple. Sauf sur localhost, un navigateur nʼenregistre pas un cookie marquéSecuresur une originehttp://. Il ne le renvoie donc jamais. Terminez correctement TLS (transport layer security), ou définissezcookie_secure = falseuniquement pour les tests sur localhost.- Une valeur
cookie_domainsqui ne couvre pas le nom dʼhôte affiché dans la barre dʼadresse..example.comcouvreapp.example.comet ne sʼapplique pas du tout àapp.example.net. - Le navigateur supprime le cookie. Une extension de confidentialité stricte ou le blocage des cookies tiers peut supprimer
_oauth2_proxy_csrfentre la redirection sortante et le callback, ou supprimer ensuite le cookie de session. - Décalage dʼhorloge. Si lʼhorloge du serveur avance fortement sur celle du fournisseur, le jeton dʼidentité peut sembler expiré et échouer à la validation.
timedatectldoit indiquerSystem clock synchronized: yes.
Une autre cause peut produire lʼerreur CSRF sans quʼaucun paramètre ne soit mal configuré. Par défaut, oauth2-proxy conserve un seul cookie CSRF. Deux onglets qui démarrent une connexion au même moment écrasent donc leurs cookies respectifs. cookie_csrf_per_request = true attribue à chaque connexion son propre cookie.
Observez le problème depuis le serveur au lieu de procéder par suppositions :
sudo journalctl -u oauth2-proxy -fChargez lʼapplication dans une fenêtre privée. Chaque requête est journalisée avec son statut. Un callback immédiatement suivi dʼune nouvelle redirection vers la page de connexion correspond à la boucle et apparaît dans le journal.
Chemins qui doivent contourner la connexion : API, webhooks et websockets
L’authentification déléguée part du principe qu’un navigateur possède un cookie. Les clients qui n’utilisent pas de navigateur échouent.
Un client d’API qui envoie Authorization: Bearer <token> ne possède pas de cookie. Les configurations du proxy ci-dessus l’envoient donc vers la page de connexion d’oauth2-proxy, sauf si l’authentification par bearer token est activée. Deux solutions propres sont possibles. Définir skip_jwt_bearer_tokens = true permet à oauth2-proxy d’accepter un bearer token JWT (JSON web token) valide provenant de l’issuer configuré, avec une audience acceptée pour ce client. C’est le bon choix lorsque vos clients d’API obtiennent déjà des tokens adaptés auprès du fournisseur. Le champ aud du token doit correspondre à client_id ou à une audience configurée avec extra_jwt_issuers. Sinon, excluez le chemin :
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]Chaque valeur est une expression régulière comparée au chemin décodé sans les paramètres de requête. Elle peut être précédée facultativement d’une méthode HTTP et de =. POST=^/webhook/ laisse le récepteur de webhook ouvert à POST, tandis qu’un utilisateur qui consulte le même chemin dans un navigateur atteint toujours la page de connexion, à condition que la requête d’authentification conserve la méthode d’origine. Les directives Nginx auth_request et Caddy forward_auth effectuent des vérifications GET. Dans ces configurations, les exclusions spécifiques à une méthode nécessitent donc un routage distinct au niveau du reverse proxy. Chaque entrée crée une brèche dans votre contrôle d’accès. Ancrez donc les expressions avec ^ et limitez-les autant que le permet l’appelant.
Utilisez v7.15.5 ou une version ultérieure avant de vous appuyer sur ces fonctions. Les versions ultérieures à v7.5.0 pouvaient être trompées et exclure un chemin protégé avec une requête utilisant des segments pointés, un double slash initial ou un point-virgule (avis GHSA-63jm-59jj-478j). L’ancrage des expressions n’empêchait pas ce problème. La version corrigée refuse d’exclure ces chemins ambigus. Vérifiez donc que vos routes publiques correspondent toujours après la mise à niveau.
Les websockets sont le cas le plus souvent mal compris. La requête d’upgrade est une requête HTTP GET ordinaire qui transporte les mêmes cookies que toute autre requête. Elle passe donc normalement le contrôle et ne nécessite aucune exclusion. Le problème vient du proxy situé autour. Sans les en-têtes Upgrade et Connection sur l’emplacement protégé, l’upgrade n’aboutit jamais et le client de l’application réessaie indéfiniment, avec un message WebSocket connection ... failed dans la console du navigateur. Exclure le chemin ne résout rien, car la requête a déjà été autorisée.
Une limite réelle s’applique toutefois. Le contrôle est effectué une seule fois, au moment de l’upgrade. Un websocket qui reste ouvert pendant plusieurs heures n’est jamais vérifié à nouveau. La suppression d’un utilisateur chez votre fournisseur ne ferme donc pas le socket qu’il possède déjà. Redémarrez l’application pour interrompre les connexions actives.
Stockage de session et cookie trop volumineux
Par défaut, toute la session est stockée dans le cookie et chiffrée avec votre cookie_secret. Cela permet à oauth2-proxy de rester stateless et ne nécessite aucun service supplémentaire. Cette approche a toutefois une limite, car les navigateurs plafonnent la taille d’un cookie à environ 4 KB. Lorsque l’ID token contient une longue liste de claims de groupes, oauth2-proxy répartit la session entre _oauth2_proxy_0, _oauth2_proxy_1, etc. Après quelques fragments, les en-têtes de requête deviennent suffisamment volumineux pour que nginx renvoie 400 Request Header Or Cookie Too Large avant même que l’application ne reçoive la requête.
Dans ce cas, déplacez la session côté serveur :
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"Le navigateur ne conserve alors qu’un ticket court, tandis que la session chiffrée est stockée dans Redis. En contrepartie, ce service doit rester disponible : si Redis s’arrête, oauth2-proxy ne peut plus charger les sessions ; si les données de session stockées sont perdues, tous les utilisateurs doivent se reconnecter. Le cookie store a également un inconvénient : deux requêtes qui actualisent la même session au même moment peuvent entrer en conflit et imposer une nouvelle authentification.
Ce que le forward auth ne vous apporte pas
C’est un contrôle à l’entrée. Il ne s’agit pas d’une autorisation à l’intérieur de l’application. Cette différence détermine si cette approche convient à votre cas.
Une fois l’utilisateur autorisé à passer, l’application voit ce qu’elle voyait auparavant. Si l’application possède ses propres rôles, le forward auth ne les renseigne pas, sauf si l’application prend en charge l’authentification par en-tête et associe un en-tête à un compte. Grafana le permet avec ses paramètres auth.proxy. La plupart des applications auto-hébergées ne le permettent pas. Tous les utilisateurs qui franchissent le contrôle sont donc la même identité pour l’application. Cette identité est souvent un administrateur.
Le forward auth ne protège pas non plus les propres jetons d’API de l’application. Un personal access token émis par l’application authentifie l’accès à l’application, pas à oauth2-proxy. Le jeton cesse donc de fonctionner dès que le contrôle est placé devant l’application. Si vous excluez le chemin d’API pour le réactiver, ce jeton devient le seul élément qui protège ce chemin. Vous faites alors fonctionner deux systèmes d’authentification sur un même service, et le SSO ne couvre que l’un des deux.
La révocation constitue la troisième limite. La suppression d’un utilisateur chez votre fournisseur empêche les nouvelles connexions, mais oauth2-proxy ne vérifie pas une session existante auprès du fournisseur avant l’échéance de cookie_refresh. Avec le refresh désactivé, le cookie de session reste valide jusqu’à son expiration, et cookie_expire vaut 168 heures par défaut. Une personne que vous venez de supprimer peut donc conserver une semaine d’accès. Définissez cookie_refresh sur une valeur courte, par exemple une heure. Lorsque le fournisseur refuse ce refresh parce que le refresh token de l’utilisateur n’est plus valide, oauth2-proxy supprime la session et force une nouvelle connexion lors de la prochaine requête qui tente le refresh. Tous les fournisseurs ne prennent pas en charge le refresh. Testez donc ce comportement avec le vôtre.
La trace d’audit s’arrête également au niveau du contrôle. oauth2-proxy journalise l’identité des personnes qui passent et l’heure de leur passage. L’application journalise une session sans nom. Si vous devez déterminer qui a modifié un paramètre, l’identité transmise par en-tête dans l’application constitue le minimum. De véritables comptes individuels sont la réponse honnête.
Payer pour le SSO est parfois la meilleure solution
L’authentification déléguée est le bon outil lorsqu’une application n’a aucun système de connexion, ou utilise un mot de passe partagé, et que vous voulez centraliser l’ajout et la suppression des utilisateurs. Sa mise en place prend un après-midi et ajoute un processus, mais elle fonctionne avec toute application qui utilise HTTP.
C’est le mauvais outil lorsque plusieurs personnes ont besoin de permissions différentes dans une même application. Une passerelle ne peut pas exprimer « Ana peut modifier les tableaux de bord et Bo peut seulement les consulter ». Si l’éditeur propose une offre SSO, la correspondance entre groupes et rôles est généralement ce que vous achetez réellement. La recréer avec des en-têtes et des règles de proxy est plus fragile que de la payer. Le modèle tarifaire derrière ces offres SSO mérite d’être lu avant de décider.
Toute application disposant d’un client mobile ou de bureau qui ne transmet pas les cookies du navigateur rencontrera la passerelle à chaque requête.
FAQ
Qu’est-ce que l’authentification forward ?
L’authentification forward est un mécanisme dans lequel le reverse proxy interroge un service d’authentification distinct pour chaque requête entrante avant de la transmettre au backend. Le proxy envoie les en-têtes de la requête à un endpoint tel que /oauth2/auth et lit le code d’état. 202 signifie que la requête est autorisée et que la requête d’origine est donc transmise à l’application. 401 signifie qu’aucune session valide n’a été trouvée et que le proxy redirige donc le navigateur vers la page de connexion. Nginx l’implémente avec la directive auth_request, Traefik avec le middleware forwardAuth et Caddy avec forward_auth.
Pourquoi oauth2-proxy me redirige-t-il vers la page de connexion en boucle ?
Le cookie de session est absent ou sa validation échoue. Chaque vérification ne trouve donc aucune session valide et vous renvoie vers la page de connexion. Les instances qui utilisent des secrets de cookie différents rejettent les cookies des autres instances. Une autre cause est cookie_secure = true sur un site auquel le navigateur accède en HTTP non chiffré, car, sauf sur localhost, un navigateur n’enregistre pas de cookie Secure sur une origine http://. Vérifiez également que la valeur cookie_domains couvre bien le nom d’hôte affiché dans la barre d’adresse. Consultez l’en-tête Set-Cookie de la réponse /oauth2/callback dans les outils de développement de votre navigateur pour identifier le cookie manquant. Si le cookie est renvoyé, recherchez les erreurs de validation dans le journal du serveur. Si le cookie CSRF est manquant, vous obtenez une page 403 indiquant Login Failed: Unable to find a valid CSRF token. Please try again. au lieu d’une boucle, et le journal contient No cookies were found in OAuth callback. lorsqu’aucun cookie n’a été reçu.
Comment autoriser un client API ou un webhook avec oauth2-proxy ?
Utilisez skip_auth_routes avec une expression régulière ancrée, éventuellement limitée à une seule méthode HTTP, par exemple POST=^/webhook/, et utilisez la version v7.15.5 ou une version ultérieure, qui corrige un contournement critique de ces exemptions. Les exemptions propres à une méthode nécessitent que la requête d’authentification conserve la méthode d’origine. Les exemples nginx et Caddy effectuent des vérifications GET ; gérez donc ces exemptions dans le routage du reverse proxy. Si vos clients API possèdent déjà des JWT valides émis par le fournisseur configuré et contenant une audience acceptée, skip_jwt_bearer_tokens = true accepte ces jetons à la place d’un cookie et maintient la protection du chemin. L’audience doit correspondre à client_id ou à une audience configurée avec extra_jwt_issuers. Tout ce qui figure dans skip_auth_routes est accessible sans authentification pour tout le monde. Gardez donc chaque expression aussi restrictive que le permet l’appelant.
oauth2-proxy fournit-il à l’application des permissions propres à chaque utilisateur ?
Non. C’est une barrière, pas un système d’autorisation. Il détermine qui peut accéder à l’application. Toutes les personnes qui y accèdent sont ensuite identiques pour l’application, sauf si celle-ci lit les en-têtes d’identité et les associe à des comptes. Grafana permet cette configuration avec ses paramètres auth.proxy. La plupart des applications auto-hébergées ne le permettent pas. Toutes les personnes qui franchissent la barrière utilisent donc la même identité que celle avec laquelle l’application s’exécute.
Quelqu’un peut-il contourner oauth2-proxy en définissant lui-même l’en-tête d’identité ?
Oui, s’il peut accéder directement à l’application. L’identité arrive dans un en-tête en clair tel que X-Auth-Request-Email, et l’application fait confiance à la valeur reçue. Toute personne capable d’ouvrir une connexion vers le port de l’application peut envoyer cet en-tête et se faire passer pour n’importe quel utilisateur. Liez l’application à 127.0.0.1, ou laissez-la sur un réseau Docker interne sans port publié, puis vérifiez-le avec sudo ss -tlnp.