# Flux de connexion

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

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](/v1.0/glossaire#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](/v1.0/glossaire#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.

```mermaid
sequenceDiagram
  autonumber
  participant S as Serveur de la wakapp
  participant D as Discovery
  participant K as Keycloak
  Note over S: code_verifier = 32 octets aléatoires<br/>code_challenge = BASE64URL(SHA-256(code_verifier))<br/>state = valeur aléatoire
  S->>D: POST /discover/start-login<br/>{ host, redirectUri, state, codeChallenge, codeChallengeMethod: "S256" }
  D-->>S: { keycloakUrl } (instance, realm, client_id, code_challenge inclus)
  S->>K: redirection du navigateur vers keycloakUrl
  K-->>S: GET /api/auth/callback?code=…&state=…
  Note over S: state reçu = state envoyé ?
  S->>K: POST /realms/<realm>/protocol/openid-connect/token<br/>{ code, code_verifier, redirect_uri, client_id }
  K-->>S: access_token, refresh_token, id_token
```

## Pourquoi ça existe

Une même wakapp tourne dans trois [environnements](/v1.0/glossaire#environnement), 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](/v1.0/glossaire#hôte-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.

:::warning[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

- [Discovery](/v1.0/concepts/discovery) : le service et ses réponses en détail.
- [Instances Keycloak et hôtes IAM](/v1.0/authentification/instances-keycloak-et-hotes-iam) : ce qui fait reconnaître votre nom d'hôte.
- [Jetons et sessions](/v1.0/authentification/jetons-et-sessions) : ce que contiennent les jetons et combien de temps ils vivent.
- [Intégrer la connexion dans une application serveur](/v1.0/authentification/integrer-la-connexion-application-serveur).
