Skip to content

Flux de connexion

Comment une wakapp connecte un utilisateur avec Discovery, Keycloak et PKCE, et pourquoi elle ne connaît jamais son realm.

ConceptDeveloper

This page has not been translated yet and is shown in French.

Le flux de connexion d'une wakapp est un flux OAuth 2.0 « code d'autorisation » protégé par PKCE, précédé d'une étape propre à Wakastart : la résolution du realm par Discovery. Votre application fournit le nom d'hôte de sa propre page ; Wakastart en déduit tout le reste, environnement compris.

Définition

Le flux de connexion est l'enchaînement qui transforme une visite anonyme en session authentifiée :

  1. résolution : Discovery transforme le nom d'hôte de votre front, accompagné si besoin de l'adresse e-mail de l'utilisateur, en URL d'autorisation Keycloak ;
  2. authentification : Keycloak vérifie l'identité de l'utilisateur, par mot de passe ou via le fournisseur d'identité de son entreprise ;
  3. échange : votre serveur échange le code reçu contre des jetons ;
  4. contexte : l'API publique renvoie l'organisation, le profil et les droits de l'utilisateur.

Ce n'est pas un mécanisme de session propre à Wakastart : la session reste celle de Keycloak, avec ses jetons standard OpenID Connect. Discovery et l'API publique encadrent ce flux sans le remplacer.

Loading diagram…

Pourquoi ça existe

Une même wakapp tourne dans trois environnements, chacun servi par sa propre instance Keycloak, et chaque réseau de clients a son propre realm. Si l'application codait ces valeurs, il faudrait un build par environnement et par réseau, et une erreur de configuration pourrait envoyer un utilisateur de production vers l'instance de développement.

Discovery supprime ce couplage : le nom d'hôte du front porte déjà l'information. Votre code est identique en dev, en staging et en prod, et c'est la plateforme qui décide de l'instance, du realm et du référentiel d'utilisateurs à partir des hôtes IAM déclarés pour l'environnement. Chaque environnement a ses propres fiches utilisateurs : le nom d'hôte appelé décide lesquelles sont utilisées.

Comment ça marche

Les acteurs

ActeurRôleCe qu'il connaît
NavigateurSuit les redirections, porte le cookie de session de votre applicationRien de sensible
Serveur de votre wakappAppelle Discovery, Keycloak et l'API publique ; garde les jetonsLe nom d'hôte de son front, le code_verifier, les jetons
DiscoveryRésout le realm et construit l'URL d'autorisationLes hôtes IAM de toutes les applications
KeycloakAuthentifie l'utilisateur et émet les jetonsLes comptes, les mots de passe, les fournisseurs d'identité
API publiqueVérifie le jeton, contrôle qu'il a été émis pour votre application, renvoie le contexteLes organisations, profils et droits

PKCE, state et nonce

Les clients Keycloak des wakapps sont des clients publics : ils n'ont pas de secret. PKCE (Proof Key for Code Exchange) remplace ce secret. Votre serveur tire au hasard un code_verifier, n'envoie que son empreinte SHA-256 (code_challenge, méthode S256, la seule acceptée par Discovery) et ne présente le code_verifier qu'au moment de l'échange. Un code intercepté pendant la redirection est inutilisable sans lui.

state protège contre la falsification de requête : votre serveur compare la valeur reçue sur le retour à celle qu'il a envoyée. nonce, facultatif, est recopié par Keycloak dans l'id_token et protège contre le rejeu de ce dernier. Discovery recopie ces trois valeurs dans l'URL qu'il renvoie.

Un composant serveur est nécessaire

Discovery et l'API publique n'acceptent pas les appels directs depuis le navigateur d'une wakapp : leurs règles CORS ne l'autorisent pas. Votre application appelle donc ces services depuis son serveur, ou depuis la partie serveur de votre framework (routes d'API Next.js, Nuxt, SvelteKit, ou un petit backend à côté d'une SPA). C'est aussi la bonne pratique de sécurité : les jetons restent côté serveur, et le navigateur ne porte qu'un cookie de session HttpOnly.

Trois façons de résoudre le realm

Par nom d'hôtePar nom d'hôte et e-mailPar adresse e-mail
EndpointPOST /discover/start-login avec hostPOST /discover/start-login avec host et emailGET /discover/email?email=…&domain=…
QuandChaque client a son propre nom d'hôtePlusieurs clients d'un même réseau partagent le nom d'hôteUn portail commun à plusieurs réseaux
Ce que Discovery renvoieL'URL d'autorisation complète, prête à suivreLa même URL, ou la liste des clients à départagerLes comptes de l'utilisateur dans votre application : realm et identifiant client
Qui construit l'URLDiscoveryDiscoveryVotre application, avec sa variable KEYCLOAK_URL
EnvironnementCelui de l'hôte IAM de hostCelui de l'hôte IAM de hostCelui de l'hôte IAM de domain

Dans tous les cas, c'est le nom d'hôte du front qui désigne l'application et l'environnement : host pour start-login, domain pour /discover/email. Discovery ne cherche que les comptes de cette application, dans les fiches de cet environnement ; un utilisateur qui possède la même adresse dans une autre application n'apparaît pas.

Ce qu'il ne faut pas faire

  • N'envoyez jamais appId pour borner la résolution : c'est host ou domain qui désigne l'application, et votre application n'a pas à connaître son identifiant client.
  • N'appelez jamais POST /discover/start-login sans host : l'e-mail seul n'est plus accepté (400). L'e-mail ne sert qu'à départager les clients du réseau désigné par le nom d'hôte.
  • N'envoyez jamais le nom d'hôte d'un autre environnement : un build de dev qui envoie le nom d'hôte de production connecte ses utilisateurs sur les fiches de production.

Exemples

  • Un éditeur qui sert chaque client sur son sous-domaine. clinique-nord.mon-app.fr et clinique-sud.mon-app.fr sont deux hôtes IAM. La page de connexion appelle Discovery avec le nom d'hôte courant et redirige sans rien demander à l'utilisateur.
  • Un groupement de clients. Les cliniques d'un même réseau partagent rdv.groupe-sante.fr. Le serveur envoie le nom d'hôte et l'e-mail saisi ; si l'adresse existe chez deux cliniques, l'utilisateur choisit la sienne.
  • Un portail commun. Tous les clients se connectent sur portail.mon-app.fr. L'utilisateur saisit son e-mail, votre application appelle GET /discover/email avec domain=portail.mon-app.fr, puis propose un choix s'il a des comptes chez plusieurs clients.
  • Le même code dans trois environnements. dev.mon-app.fr est un hôte IAM de l'environnement dev : Discovery renvoie l'instance auth-dev.wakastart.app, sans changer une ligne de code.

Pour aller plus loin