Flux de connexion
Comment une wakapp connecte un utilisateur avec Discovery, Keycloak et PKCE, et pourquoi elle ne connaît jamais son realm.
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 :
- 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 ;
- authentification : Keycloak vérifie l'identité de l'utilisateur, par mot de passe ou via le fournisseur d'identité de son entreprise ;
- échange : votre serveur échange le code reçu contre des jetons ;
- 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.
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
| Acteur | Rôle | Ce qu'il connaît |
|---|---|---|
| Navigateur | Suit les redirections, porte le cookie de session de votre application | Rien de sensible |
| Serveur de votre wakapp | Appelle Discovery, Keycloak et l'API publique ; garde les jetons | Le nom d'hôte de son front, le code_verifier, les jetons |
| Discovery | Résout le realm et construit l'URL d'autorisation | Les hôtes IAM de toutes les applications |
| Keycloak | Authentifie l'utilisateur et émet les jetons | Les comptes, les mots de passe, les fournisseurs d'identité |
| API publique | Vérifie le jeton, contrôle qu'il a été émis pour votre application, renvoie le contexte | Les 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ôte | Par nom d'hôte et e-mail | Par adresse e-mail | |
|---|---|---|---|
| Endpoint | POST /discover/start-login avec host | POST /discover/start-login avec host et email | GET /discover/email?email=…&domain=… |
| Quand | Chaque client a son propre nom d'hôte | Plusieurs clients d'un même réseau partagent le nom d'hôte | Un portail commun à plusieurs réseaux |
| Ce que Discovery renvoie | L'URL d'autorisation complète, prête à suivre | La même URL, ou la liste des clients à départager | Les comptes de l'utilisateur dans votre application : realm et identifiant client |
| Qui construit l'URL | Discovery | Discovery | Votre application, avec sa variable KEYCLOAK_URL |
| Environnement | Celui de l'hôte IAM de host | Celui de l'hôte IAM de host | Celui 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
appIdpour borner la résolution : c'esthostoudomainqui désigne l'application, et votre application n'a pas à connaître son identifiant client. - N'appelez jamais
POST /discover/start-loginsanshost: 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.fretclinique-sud.mon-app.frsont 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 appelleGET /discover/emailavecdomain=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.frest un hôte IAM de l'environnement dev : Discovery renvoie l'instanceauth-dev.wakastart.app, sans changer une ligne de code.
Pour aller plus loin
- Discovery : le service et ses réponses en détail.
- Instances Keycloak et hôtes IAM : ce qui fait reconnaître votre nom d'hôte.
- Jetons et sessions : ce que contiennent les jetons et combien de temps ils vivent.
- Intégrer la connexion dans une application serveur.