OAuth 2.0 — social login (Authorization Code + PKCE, posture 2.1)

stable@nodefony/securitymis à jour 2026-09-07

Ton utilisateur clique « Se connecter avec GitHub », part chez GitHub, revient — et se retrouve connecté à ton application. Nodefony orchestre ce voyage avec la posture OAuth 2.1 (RFC 9700) : Authorization Code, PKCE, state anti-CSRF, iss anti-mix-up. Point clé : aucun jeton n’atteint le navigateur — le retour produit une session BFF, exactement la même qu’un login par mot de passe. Ancré sur OAuth2Service (oauth2.ts#OAuth2Service) et le controller BFF OAuth2Controller (OAuth2Controller.ts#OAuth2Controller).

📍 Documentation › Sécurité › OAuth2

🧠 Le modèle mental — deux allers-retours, un secret qui ne bouge pas#

Le social login n’est pas « GitHub nous donne l’utilisateur ». C’est deux voyages :

1. le navigateur va demander un accord chez le fournisseur et revient avec un ticket à usage unique (le code) ;
2. ton serveur seul échange ce ticket contre des jetons, sur un canal serveur-à-serveur.

L’analogie : le code est un ticket de vestiaire confié au client. Le manteau ne s’échange qu’au comptoir, sur présentation du ticket et du talon que le comptoir avait gardé (le code_verifier PKCE). Voler le ticket dans la poche du client ne suffit pas.

Deux propriétés se lisent sur ce schéma. Le secret d’échange (clientSecret, code_verifier) ne quitte jamais le serveur. Et le résultat n’est pas un jeton exposé au JavaScript : c’est un cookie de session opaque, révocable côté serveur.

📖 Lexique#

Qu’est-ce que c’est ? — et quelles failles ça ferme#

Déléguer le login à Google ou GitHub, c’est ne plus stocker de mots de passe : plus de fuite de hachages, plus de réinitialisation à gérer, un utilisateur qui n’invente pas un énième secret.

Mais OAuth mal implémenté est une fabrique à comptes usurpés. Quatre failles classiques, et ce qui les ferme ici :

• Vol de jeton via XSS — si un access_token transite par le navigateur, tout script injecté peut le lire. Fermé par construction : aucun jeton ne sort du serveur, le résultat est un cookie de session opaque (OAuth2Controller.ts#OAuth2Controller.constructor).
• Interception du code — un code capté (log de proxy, historique, redirection ouverte) est échangeable par l’attaquant. Fermé par PKCE : l’échange exige le code_verifier resté en session (OAuth2Service.createAuthorization(), oauth2.ts#OAuth2Service.createAuthorization).
• CSRF de login — un tiers force ta victime à terminer son flux à lui : elle se retrouve connectée sur le compte de l’attaquant, qui lit ensuite ce qu’elle y dépose. Fermé par le state comparé au retour (OAuth2Controller.callback(), OAuth2Controller.ts#OAuth2Controller.callback).
• Mix-up d’IdP — un code obtenu chez un fournisseur malveillant est présenté au callback d’un fournisseur de confiance. Fermé par la vérification de l’iss (oauth2.ts#OAuth2Service.listProviders) et par l’exigence « même fournisseur qu’à l’aller » côté controller (OAuth2Controller.ts#OAuth2Controller).

❗ Important

Le fournisseur social te dit qui est la personne. Il ne te dit rien de ses droits. Se connecter avec le compte Google d’un administrateur de Google ne rend administrateur de rien chez toi. Les rôles viennent de la ligne locale — voir la section Shadow User.

La vision Nodefony — un service sans transport, une session BFF#

Trois partis pris, tous vérifiables au code.

Le service ne touche ni HTTP ni session. OAuth2Service rend à l’appelant les éléments à persister (url, state, codeVerifier) et un simple { identifier } en sortie (IOAuthAuthorization, oauth2.ts#IOAuthAuthorization). Conséquence pratique : la logique OAuth se teste sans serveur, comme AuthFlow. Le transport (cookies, redirections 302) vit dans le controller BFF.

Le login social finit exactement comme un login classique. Le callback appelle AuthFlow.establishSessionFor() (authFlow.ts#AuthFlow.establishSessionFor), qui re-résout l’identité, vérifie que le compte est actif, régénère l’ID de session (anti-fixation, session.regenerateId(), authFlow.ts#AuthFlow.logout) et journalise l’événement d’audit. Il n’existe aucun authenticator oauth2 dans la chaîne du firewall : après le retour, c’est l’authenticator session qui identifie chaque requête, comme après un mot de passe.

Coût nul quand on ne s’en sert pas. Aucune dépendance tierce : le client OAuth 2.0 est écrit dans le module (OAuth2Client, oauth2Client.ts#OAuth2Client), et jose — seul recours externe, pour lire les claims de l’ID token — est importé paresseusement. Les fournisseurs sont construits une fois puis mémoïsés (OAuth2Service.#resolveProvider()) : c’est là, une seule fois par processus, que les points d’entrée d’un émetteur OIDC sont découverts. Un run qui sert (ports ouverts) les construit dès le boot, sans l’attendre ; une commande console ne touche jamais le réseau.

Une configuration fausse se montre au démarrage, pas au premier clic. Au boot, l’issuer de chaque fournisseur est confronté à ce que sa fabrique exige (checkProviderIssuer(), oauth2.ts) : absent alors que la fabrique l’a déclaré requis, ou qui n’est pas une URL d’émetteur valide (https, sans requête ni fragment — RFC 8414 §2), il interrompt le démarrage en nommant la clé (security.oauth2.providers.<nom>.issuer). Un émetteur injoignable, lui, n’est pas une faute de configuration : le boot continue, un WARNING le nomme, et son bouton quitte l’écran de connexion — le flux authorize reste ouvert. Une nouvelle tentative part au plus toutes les 30 s pendant que l’écran est affiché ; le bouton revient dès qu’elle réussit. Les routes sont montées dès que @nodefony/security est chargé (framework/index.ts#Framework.onKernelReady) : sans social login configuré, …/providers rend une liste vide, authorize rend 404 Unknown provider, et authorize/callback rendent 503 OAuth unavailable quand oauth2.enabled vaut false.

Au boot, la config est validée et les fournisseurs configurés sont confrontés au registre : un nom inconnu produit un WARNING, pas un échec fatal — OAuth2Service.#build() confronte les noms configurés à listOAuthProviders() (oauth2.ts#OAuth2Service) et le reste de l’application démarre, le bouton correspondant n’apparaît simplement pas.

🚀 Démarrage rapide#

Les secrets entrent par env.ts, la config les branche#

Un fournisseur n’est monté que si ses deux secrets sont présents : pas de bouton mort sur l’écran de login quand la variable manque.

Pourquoi ces deux noms n’ont pas de préfixe NF_, contrairement à la règle. Le préfixe dit à qui appartient la valeur, pas qui la lit — et GITHUB_CLIENT_ID vous est délivré par GitHub. Son nom est celui que la documentation du fournisseur, Auth.js et Passport emploient déjà : si votre application en a une, Nodefony la lit telle quelle plutôt que de vous faire recopier la même valeur sous un second nom, qui finirait par diverger. La base des callbacks, elle, n’est émise par personne : c’est un réglage que votre application se donne, donc NF_OAUTH_REDIRECT_BASE.

// nodefony/config/security.ts — le fragment du module, importé par le manifeste
import type { ConfigContext } from "nodefony";
import type { ISecurityConfigInput } from "@nodefony/security";
import type { env } from "../../env";

export const securityConfig = (ctx: ConfigContext<typeof env>) =>
  ({
    oauth2: {
      // Rôles posés à la CRÉATION du compte local, jamais réécrits ensuite.
      defaultRoles: ["ROLE_USER"],
      allowSignup: true, // false = un compte local déjà lié est exigé
      successRedirect: "/",
      failureRedirect: "/login?error=oauth",
      providers: {
        // Secrets absents → fournisseur non monté, bouton non affiché.
        ...(ctx.env.GITHUB_CLIENT_ID && ctx.env.GITHUB_CLIENT_SECRET
          ? {
              github: {
                clientId: ctx.env.GITHUB_CLIENT_ID,
                clientSecret: ctx.env.GITHUB_CLIENT_SECRET,
                redirectUri: `${ctx.env.NF_OAUTH_REDIRECT_BASE}/nodefony/security/api/oauth2/github/callback`,
              },
            }
          : {}),
      },
    },
  }) satisfies ISecurityConfigInput;

// env.ts — SEUL lecteur de process.env (catalogue typé, validé au boot).
// nodefony.config.ts — `ctx.env` EST ce catalogue (typé par le paramètre générique).
import { defineConfig, defineEnv, envString, use } from "nodefony";
import { securityConfig } from "./nodefony/config/security";

export const env = defineEnv({
  GITHUB_CLIENT_ID: envString({ optional: true }),
  GITHUB_CLIENT_SECRET: envString({ optional: true }),
  // Base des callbacks : doit correspondre EXACTEMENT à l'URL enregistrée chez
  // le fournisseur (RFC 9700 — comparaison de chaînes, pas de préfixe).
  NF_OAUTH_REDIRECT_BASE: envString({ default: "https://localhost:5152" }),
});

export default defineConfig<typeof env>((ctx) => ({
  modules: [
    "@nodefony/http",
    "@nodefony/framework",
    use("@nodefony/security", securityConfig(ctx)),
  ],
}));

Les routes sont FOURNIES — tu n’écris aucun controller#

mountOAuth2Routes() (OAuth2Controller.ts#mountOAuth2Routes) monte quatre routes sous /nodefony/security/api/oauth2 (OAuth2Controller.ts#OAuth2Controller.backchannelLogout) dès que le service oauth2 est enregistré, c’est-à-dire dès que @nodefony/security est chargé (framework/index.ts#Framework.onKernelReady) :

Ton écran de login n’a donc qu’un lien à poser :

<a href="/nodefony/security/api/oauth2/github/authorize"
  >Se connecter avec GitHub</a
>

⚠️ Attention

Ces routes portent bypassFirewall: true (OAuth2Controller.ts#mountOAuth2Routes) — elles sont le mécanisme d’authentification : l’utilisateur est anonyme pendant tout l’aller-retour. Les protéger créerait un interblocage (il faudrait être connecté pour pouvoir se connecter). La session anonyme ne porte que state/code_verifier, et son ID est régénéré à la promotion. Le canal arrière, lui, est appelé serveur à serveur : ni cookie, ni session, ni jeton CSRF — la signature du jeton de déconnexion est sa seule authentification.

Ce qu’on observe#

# 1) Démarrage : 302 vers le fournisseur + cookie de transit + state dans l'URL
curl -si -c /tmp/jar http://localhost:5151/nodefony/security/api/oauth2/github/authorize | head -3
# HTTP/1.1 302 Found
# Location: https://github.com/login/oauth/authorize?...&state=8f2c…
# Set-Cookie: nodefony-sessid=…; HttpOnly; SameSite=Lax

# 2) Retour du fournisseur (c'est le NAVIGATEUR qui suit ce lien) → session BFF
curl -si -b /tmp/jar -c /tmp/jar \
  "http://localhost:5151/nodefony/security/api/oauth2/github/callback?code=…&state=8f2c…" | head -2
# HTTP/1.1 302 Found
# Location: /

# 3) L'identité est résolue comme après un login classique
curl -s -b /tmp/jar http://localhost:5151/nodefony/security/api/auth/me
# {"user":{"id":"…","identifier":"jane@example.com","roles":["ROLE_USER"]}}

# 4) Ce que l'UI de login interroge pour n'afficher que des boutons vivants
curl -s http://localhost:5151/nodefony/security/api/oauth2/providers
# {"providers":[{"name":"github","label":"GitHub"}]}

Séquence identique prouvée de bout en bout sur serveur réel par oauth2-flow.test.ts (6 cas).

🏗️ Le flux, étape par étape#

Étape 1 — createAuthorization(provider)#

OAuth2Service.createAuthorization() (oauth2.ts#OAuth2Service.createAuthorization) fabrique trois choses :

1. un state aléatoire (anti-CSRF) ;
2. un code_verifier — seulement si le fournisseur pratique PKCE (usesPkce, oauth2.ts#OAuth2Service.getRedirects) ; null sinon (GitHub) ;
3. l’URL d’autorisation construite par l’adaptateur du fournisseur, avec les scopes effectifs (ceux de la config, sinon les scopes par défaut du fournisseur, oauth2.ts#OAuth2Service.rememberLogout).

Le controller pose les trois valeurs en session, persiste (session.save() — pas seulement en mémoire, OAuth2Controller.ts#IOAuth2Session.save), puis redirige en 302.

Étape 2 — le retour, validé avant tout appel réseau#

OAuth2Controller.callback() (OAuth2Controller.ts#OAuth2Controller.callback) travaille dans cet ordre, et l’ordre est la défense :

1. lire l’état de session, puis l’invalider immédiatement (OAuth2Controller.ts#oauth2FailureTarget) — le state est à usage unique : un rejeu du même retour échoue, même avec le bon cookie ;
2. comparer : code et state présents, state reçu ≡ state attendu, et fournisseur du callback ≡ fournisseur démarré (OAuth2Controller.ts#OAuth2Controller.authorize). Un seul écart → 302 vers l’écran d’échec avec reason=failed, sans jamais contacter le fournisseur ;
3. seulement ensuite, exchangeAndProvision().

Étape 3 — exchangeAndProvision(provider, code, verifier, iss)#

OAuth2Service.exchangeAndProvision() (oauth2.ts#OAuth2Service.exchangeAndProvision) enchaîne :

1. anti-mix-up — si le fournisseur annonce un émetteur attendu, l’iss reçu doit correspondre, et un iss absent est un rejet, pas une tolérance (oauth2.ts#OAuth2Service.listProviders) ;
2. échange du code sur le canal serveur, avec le code_verifier (validateAuthorizationCode, oauth2.ts#OAuth2Service.createAuthorization), puis lecture du profil (fetchProfile, oauth2.ts#OAuth2Service.exchangeAndProvision) ;
3. provisionnement du Shadow User avec la politique effective — rôles par défaut surchargeables par fournisseur (oauth2.ts#OAuth2Service.listDisplayProviders), allowSignup global (oauth2.ts#OAuth2Service.exchangeAndProvision).

Toute erreur de cette étape est convertie en échec uniforme par le controller (302 vers l’écran d’échec avec reason=failed) : le client ne distingue pas un iss invalide d’un échange refusé ou d’un signup interdit.

Les retours — from et back#

La page qui lance le flux dit deux choses à /authorize, que le serveur revalide en chemins locaux (safeRedirectPath, garde anti-redirection ouverte du cœur), garde en session avec le state et purge au callback :

back l’emporte sur failureRedirect parce qu’une application peut avoir PLUSIEURS écrans de connexion (la page par défaut, la console d’administration) : une seule adresse d’échec renverrait l’un chez l’autre. La page par défaut et la console l’envoient d’elles-mêmes, et NodefonyLogin.startProvider() pose la page courante.

L’écran d’échec reçoit reason et from (une reason ou un from déjà présents sont remplacés) : reason=access_denied dit une ANNULATION — l’écran se tait, l’utilisateur est revenu choisir une autre méthode —, toute autre valeur un échec à annoncer. Seuls les codes normalisés d’OAuth 2.0 et d’OpenID Connect sont recopiés, et seulement sous un state valide ; tout le reste devient failed (OAUTH2_FAILED_REASON, cœur).

🧑‍⚖️ Le Shadow User — l’identité locale, et pourquoi OAuth n’accorde aucun droit#

Nodefony ne « connecte pas un compte Google ». Il crée et retrouve une ligne locale liée au compte externe : le Shadow User. C’est cette ligne qui porte l’identifiant, les rôles, l’état actif/verrouillé — donc tout ce dont l’autorisation a besoin.

Le contrat s’appelle IOAuthUserProvisioner (IOAuthUserProvisioner.ts#IOAuthUserProvisioner) ; l’implémentation par défaut est UserService.provisionOAuthUser() (UserService.ts#UserService.provisionOAuthUser), en find-or-create :

⚠️ allowSignup: true (le défaut) + une zone sans roles = une zone ouverte à tout compte du fournisseur. Une zone qui n’exige aucun rôle laisse passer toute identité authentifiée ; avec la création à la volée, cela veut dire quiconque obtient un compte chez Google ou GitHub. Le pare-feu le signale au démarrage (WARNING), dans la console (openToSignup de la zone) et dans nodefony doctor --live — c’est un constat, pas une faute (findZonesOpenToSignup, openToSignup.ts#findZonesOpenToSignup). Deux gestes le soldent : roles: ["ROLE_USER"] sur la zone, qui ne change rien au comportement mais écrit l’intention, ou allowSignup: false, qui exige un compte préexistant.

Pourquoi l’e-mail ne lie jamais automatiquement un compte#

C’est le point le plus contre-intuitif, et c’est une décision de sécurité. Si un compte externe dont l’e-mail vaut admin@ton-domaine.fr liait automatiquement l’administrateur local, il suffirait de créer un compte chez un fournisseur laxiste avec cette adresse pour prendre le compte admin. La liaison par e-mail est donc refusée y compris quand le fournisseur certifie l’adresse (emailVerified reste informatif, IOAuthUserProvisioner.ts#IOAuthProfile.emailVerified).

Conséquence assumée : l’utilisateur qui avait un mot de passe et clique « avec GitHub » obtient un second compte. Le rattachement d’un compte externe à un compte existant est une action explicite, faite utilisateur déjà connecté — jamais un effet de bord du login.

L’identifiant du compte créé dérive de l’e-mail si le fournisseur en donne un, sinon d’une clé préfixée provider:providerId — jamais de collision entre fournisseurs (UserService.ts#UserService.provisionOAuthUser).

Les rôles sont posés à la création, et plus jamais#

defaultRoles s’applique au moment du create (UserService.ts#UserService.create). Un second login n’écrase rien : promouvoir quelqu’un dans ta base reste effectif, et modifier defaultRoles en config ne repeint pas les comptes existants. C’est la traduction de la règle « OAuth = authentification, pas autorisation » (oauth2.ts#OAuth2Service.listDisplayProviders, config.ts#loginPageSchema).

💡 Astuce

Un fournisseur social ne doit jamais figurer dans le chemin d’obtention d’un rôle privilégié. Le schéma de rôles de Nodefony distingue déjà ROLE_NODEFONY_* (plateforme) et ROLE_* (applicatif) — voir authorization.

Brancher sa propre politique#

Le provisioner est le service users s’il implémente la capability, détecté par duck-typing (OAuth2Service.#resolveProvisioner(), oauth2.ts#OAuth2Service.#resolveProvisioner). S’il ne l’implémente pas, le login échoue — jamais de création silencieuse par défaut. Une application qui veut sa propre politique (quota d’inscriptions, allowlist de domaines e-mail, rattachement à un tenant) implémente provisionOAuthUser() sur son service users : le profil normalisé IOAuthProfile (IOAuthUserProvisioner.ts#IOAuthProfile) lui donne provider, providerId, email, emailVerified, name et la charge brute raw.

🧩 Fournisseurs — catalogue et extension#

Un fournisseur est un adaptateur qui implémente IOAuthProvider (IOAuthProvider.ts#IOAuthProvider) : il masque les divergences (PKCE ou non, profil par ID token ou par appel d’API) derrière un contrat unique. Quatre sont livrés, résolus par nom via le registre oauthProviderRegistry.ts#OAuthProviderFactory.

Le paramètre iss — une règle à TROIS états, pas deux#

La RFC 9207 ajoute un paramètre iss à la réponse d’autorisation, pour qu’un client branché sur plusieurs fournisseurs ne confonde pas leurs réponses. Mais elle ne l’impose pas à tous : son §2.4 demande au client d’extraire iss « if the parameter is present », et son §2.3 fait ANNONCER ce support par les métadonnées de l’émetteur (authorization_response_iss_parameter_supported).

D’où trois cas, et non deux :

Exiger iss d’un serveur qui n’a jamais promis de l’émettre reviendrait à refuser un serveur conforme (Microsoft Entra n’annonce pas ce support). Ce n’est pas un relâchement : la défense anti-mix-up principale est ailleurs — chaque fournisseur a son URL de redirection propre (…/{provider}/callback) et le flux vérifie que le fournisseur de retour est celui qui a démarré, ce que la RFC 9700 §4.4.2.2 donne comme la protection de référence. iss est la seconde ceinture.

La politique est portée par le fournisseur (issuerPolicy, IOAuthProvider.ts#IOAuthProvider.issuerPolicy) et remplie par la découverte ; elle vaut null pour un fournisseur non-OIDC, qui ne relève pas de cette défense.

Découverte des points d’entrée (RFC 8414)#

Aucune URL de fournisseur n’est écrite en dur — sauf GitHub, qui ne publie pas de métadonnées. Les points d’entrée sont demandés à l’émetteur, une seule fois par processus, au premier login.

Cette règle n’est pas réécrite ici : la normalisation de l’émetteur, l’ordre normatif des URL bien connues (§3.1 : insertion oauth → insertion oidc → ajout oidc) et l’égalité stricte du §3.3 vivent dans le cœur (nodefony → src/oauth/authorizationServer.ts), qui s’en sert aussi pour PUBLIER nos propres métadonnées. metadata.ts n’ajoute que le transport : requête bornée, sans redirection suivie, avec un délai d’attente (discoverAuthorizationServer(), metadata.ts#discoverAuthorizationServer).

Deux refus valent d’être connus. Un document dont l’issuer diffère de celui demandé est rejeté sans se rabattre sur l’URL suivante — se rabattre masquerait un document hostile derrière un 404. Et un émetteur qui annonce ses méthodes PKCE sans y mettre S256 est refusé : lui envoyer un défi donnerait l’illusion de PKCE.

ℹ️ Note

Microsoft Entra : un locataire nommé (…/{tenant-id}/v2.0) se découvre normalement. Les points d’entrée common et organizations, eux, publient un issuer contenant le gabarit littéral {tenantid} — l’égalité du §3.3 le refuse, à raison. Le multi-locataire demande donc un adaptateur dédié, pas le builtin.

Enregistrer le sien — sans éditer le cœur#

Tout serveur OpenID Connect conforme est déjà supporté — Auth0, Okta, Authentik, Entra mono-locataire… — sans une ligne de code propre. Le builtin oidc suffit quand il n’y en a qu’un ; pour en nommer plusieurs, registerOAuthProvider() au chargement de ton module (avant le onBoot du service) :

import {
  registerOAuthProvider,
  createDiscoveredOidcProvider,
} from "@nodefony/security";

// Le nom sert de clé de configuration ET de `provider` du Shadow User ;
// l'émetteur vient de la config (`oauth2.providers.microsoft.issuer`).
registerOAuthProvider(
  "microsoft",
  (ctx) => createDiscoveredOidcProvider("microsoft", ctx),
  // Déclarer l'émetteur requis : son oubli refuse le démarrage au lieu
  // d'échouer au premier clic.
  { requiresIssuer: true },
);

La fabrique reçoit IOAuthProviderContext (oauthProviderRegistry.ts#IOAuthProviderContext) : les secrets et l’URL de callback issus de la config, rien d’autre. Elle peut être asynchrone — découvrir un émetteur est une opération de construction, faite une fois par processus.

Un fournisseur qui n’est pas OIDC (pas de métadonnées, pas d’ID token) demande un adaptateur : le protocole vient de OAuth2Client, la fabrique ne fait que lire le profil. C’est une centaine de lignes — github.ts en est le modèle.

Un fournisseur qui n’est pas OIDC (pas d’ID token, profil lu à son API) s’écrit comme GitHub (createGithubProvider(), github.ts#createGithubProvider) : OAuth2Client porte le protocole, la fabrique ne fait que le mapping du profil. Exemple sans réseau dans le dépôt : src/modules/test/nodefony/secure/oauthTestProvider.ts.

⚙️ Configuration#

Schéma Zod oauth2Schema (config.ts#oauth2Schema), branché sur la section oauth2 de la config du module (config.ts#securityConfigSchema). Table dérivée du schéma — les défauts sont ceux du code.

Par fournisseur (oauthProviderSchema, config.ts#oauthProviderSchema) :

Les surcharges par fournisseur permettent la cohabitation : un IdP de recette garde ses redirections et ses rôles pendant qu’un IdP de production pointe ailleurs.

🔐 Sécurité — jetons du fournisseur, révocation, attaques couvertes#

Les jetons du fournisseur ne sont pas conservés#

C’est un choix, et il a des conséquences à connaître. Les jetons obtenus à l’échange vivent dans la portée locale de l’échange (validateAuthorizationCode puis fetchProfile, oauth2.ts#OAuth2Service.exchangeAndProvision) : ils ne sont ni retournés, ni mis en session, ni persistés. Le profil normalisé qui traverse le système n’en contient aucun (IOAuthUserProvisioner.ts#IOAuthProfile).

• Conséquence 1 — la surface d’exposition est minimale : pas de coffre de jetons à protéger, pas de fuite possible par la base ni par la session.
• Conséquence 2 — l’application ne peut pas appeler l’API du fournisseur au nom de l’utilisateur plus tard (lire ses dépôts, envoyer un mail). Nodefony fait de l’authentification, pas de la délégation d’accès.
• Si tu as besoin de cette délégation : le seul endroit où les jetons sont visibles est le fetchProfile() de ton adaptateur (IOAuthProvider.ts#IOAuthProvider.fetchProfile) — c’est là que ton implémentation les capture et les persiste, sous ta responsabilité (chiffrement au repos, rotation, révocation).

Une exception, et une seule : l’ID token d’un fournisseur qui sait déconnecter. Quand le fournisseur publie un point de déconnexion (end_session_endpoint, lu par la découverte — Keycloak le fait), la session BFF retient, côté serveur, le nom du fournisseur, l’ID token et le claim sid. La console d’administration des sessions n’en montre rien. Le navigateur ne le voit qu’une fois, à la déconnexion, dans l’adresse logoutUrl (id_token_hint) : RP-Initiated Logout passe par une redirection du navigateur, la norme ne laisse pas d’autre chemin — la session locale est alors déjà détruite. Pourquoi : à la déconnexion, l’ID token est rejoué en id_token_hint — il désigne la session à fermer chez le fournisseur, qui sans lui demanderait une confirmation à chaque fois. Il n’ouvre aucun accès : ni l’API du fournisseur, ni un rafraîchissement. Le jeton d’accès et le jeton de rafraîchissement restent jetés. GitHub, ou un serveur OIDC sans point de déconnexion : rien n’est retenu.

Pour que le fournisseur puisse, à l’inverse, fermer lui-même ces sessions, le login retient aussi un index — fournisseur et sid, sans l’ID token — dans les métadonnées de la session (oauth2.ts#IFederatedLogoutHint.sid). Il est là parce que l’énumération des sessions efface les attributs, dans tous les stores : c’est la seule partie que le canal arrière peut lire en parcourant le parc. L’écran Sessions ne l’affiche pas (résumé construit par liste blanche).

Déconnexion demandée par le fournisseur — le canal arrière#

Quand l’utilisateur se déconnecte ailleurs — la console d’administration de Keycloak, une autre application du même SSO —, le fournisseur appelle l’application : POST …/oauth2/{provider}/backchannel-logout, avec un paramètre logout_token (OpenID Connect Back-Channel Logout 1.0). Le contrôleur (OAuth2Controller.ts#OAuth2Controller.callback) délègue au service (OAuth2Service.backchannelLogout(), oauth2.ts#OAuth2Service.backchannelLogout) :

1. La signature d’abord. Le jeton est vérifié par RemoteJwtVerifier (verifyClaims, RemoteJwtVerifier.ts#RemoteJwtVerifier.verifyClaims), avec les clés publiques du fournisseur découvertes à son jwks_uri : émetteur exact, audience = le clientId, iat, exp et jti exigés (oidc.ts#createDiscoveredOidcProvider). Les algorithmes sont ceux des ID tokens annoncés par le fournisseur, sans ceux à secret partagé (oidc.ts#createDiscoveredOidcProvider) — Keycloak annonce HS256, qui ferait d’une clé publique un secret de signature.
2. Le sens ensuite (readLogoutTokenClaims(), oidc.ts#readLogoutTokenClaims) : sub ou sid présent ; events qui le déclare jeton de déconnexion ; aucun nonce. C’est ce qui empêche un ID token, signé par la même clé, de passer pour un jeton de déconnexion.
3. Pas de rejeu : un jti déjà vu est refusé (oauth2.ts#OAuth2Service.backchannelLogout).
4. Les sessions désignées sont détruites par SessionsService.destroyWhere() (sessions-service.ts#SessionsService.destroyWhere) : celles ouvertes par ce fournisseur et qui portent le sid du jeton ; sans sid, toutes celles du compte lié au sub. Une session ouverte par mot de passe ou par un autre fournisseur n’est jamais touchée : le fournisseur ne ferme que ce qu’il a ouvert.

Réponses (norme §2.8) : 200 quand la déconnexion a eu lieu — ou n’avait plus lieu d’être ; 400 invalid_request pour un jeton refusé comme pour une déconnexion impossible (jeu de clés injoignable), la cause n’allant qu’au journal ; 404 fournisseur inconnu ; 501 fournisseur qui n’émet pas de jeton de déconnexion (GitHub). Toujours Cache-Control: no-store.

Les WebSockets portées par une session détruite se ferment au tick de revalidation du hub temps réel, au plus 30 secondes plus tard (RealtimeHub.ts#channelFamily), code 4001.

ℹ️ Note

L’anti-rejeu vit dans le processus. Plusieurs exemplaires : un jeton rejoué sur un autre exemplaire passe — et ne ferme que des sessions que le fournisseur a déjà déclarées closes. La borne est la durée de vie du jeton, que la norme recommande courte (§4).

Ce que « révoquer » veut dire ici#

La troisième ligne est le piège courant : une fois la session BFF ouverte, ton application ne redemande plus rien à GitHub — et Keycloak ne prévient que s’il connaît l’adresse du canal arrière. Pour couper l’accès, il faut agir localement (désactiver le compte ou détruire les sessions), pas chez le fournisseur.

Attaques couvertes, prouvées par les tests#

📜 Normes appliquées#

Flux exclus par posture 2.1, et donc absents du code : implicit (jeton en fragment d’URL) et password / ROPC (l’application verrait le mot de passe du fournisseur).

📡 Observabilité — Studio#

L’écran de connexion de Studio consomme directement le data plane : il interroge /nodefony/security/api/oauth2/providers et affiche tout ce que cette route lui rend — zéro bouton mort, et zéro fournisseur légitime masqué. Le clic déclenche la redirection vers authorize.

C’est le SERVEUR qui décide de la liste et des libellés, parce qu’il est le seul à lire la configuration. L’écran ne connaît que des icônes de marque, pour l’esthétique : un fournisseur qu’il ne reconnaît pas reçoit une icône neutre et reste affiché. Filtrer côté écran sur une table de marques masquerait précisément les fournisseurs qu’une application enregistre elle-même — Keycloak, ou un OIDC d’entreprise.

Retirer un bouton sans fermer le flux — hidden: true sur un fournisseur :

providers: {
  "test-oidc": { /* … */ hidden: true },   // absent de l'écran…
}

…mais /authorize continue de répondre 302 : masquer n’est pas désactiver. Les deux usages sont une fixture de développement qui pointe vers un serveur fictif (le bouton serait mort), et un fournisseur réservé à un point d’entrée particulier. Pour le désactiver vraiment, il faut le retirer de la configuration.

Le libellé vient de label, sinon il est dérivé du nom de la clé (keycloak → « Keycloak », oidc → « OIDC », mon-idp → « Mon Idp ») : un écran de connexion ne montre jamais un identifiant technique brut.

Côté suivi, chaque login réussi produit un événement d’audit auth / login.success via AuthFlow.establishSessionFor() (authFlow.ts#AuthFlow.establishSessionFor), consultable dans l’écran Audit. La session ouverte apparaît dans l’écran Sessions (IP et agent capturés à l’ouverture) ; le compte provisionné dans l’écran Users, avec ses rôles réels.

ℹ️ Note

L’événement d’audit du login social porte la raison oauth : le controller la passe à AuthFlow.establishSessionFor() (OAuth2Controller.ts#IOAuth2BffFlow.establishSessionFor), comme WebAuthn passe webauthn. federated n’est que la valeur par défaut d’un appelant qui n’a pas nommé son facteur (authFlow.ts#AuthFlow.establishSessionFor).

⚠️ Pièges (symptôme → cause → correction)#

🧪 Tests & couverture#

Trois familles couvrent le social login — les chiffres exacts vivent dans la carte de l’aperçu (régénérée depuis vitest, jamais figée ici) :

• unitaires — oauth2Service.test (boot, introspection, les deux étapes, anti-mix-up, provisioning fail-closed), oauthProviders.test (registre, helper OIDC, adaptateur GitHub avec e-mail public et privé), oauthProvisioner.test (find-or-create, JIT, signup interdit, non-liaison par e-mail) ;
• intégration — oauth2-flow.test : le flux complet sur serveur réel, du 302 d’authorize à l’identité résolue par /me, avec un fournisseur de test déterministe et sans réseau ; oauth2-keycloak.test : le même flux contre un vrai Keycloak, déconnexions comprises (les deux sens) ;
• attaque — oauth2-attack.test (rejeu du state, mix-up de fournisseur) et oauth.attack.test (collision d’e-mail avec un admin, élévation par re-login, collision d’identifiants entre fournisseurs).

Ce qui manque : aucun banc de charge dédié au social login (le flux est un chemin froid, deux requêtes par connexion), et aucun test contre un fournisseur réel autre que Keycloak.

Couverture : npm run coverage dans @nodefony/security. Campagnes d’attaque : skill nodefony-security-review (mode red/blue-team).

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : Sécurité — vue d’ensemble · Toute la documentation

• 🧭 Pages sœurs : Authenticators · Jetons

• La session produite par le login → session · authenticators

• Ce qui décide des droits une fois connecté → authorization

• Les autres facteurs sans mot de passe → webauthn · totp

• Jetons d’API pour les machines (le pendant non-humain) → tokens

• Vue d’ensemble du module → index · Termes transverses → lexique