Connecter par e-mail plusieurs clients sur un même nom d'hôte
Départager les clients d'un réseau par l'e-mail avec start-login, ou retrouver les comptes d'une adresse avec GET /discover/email et construire l'URL Keycloak.
- Durée
- 25 min
Quand plusieurs clients se connectent sur le même nom d'hôte, par exemple un portail portail.mon-app.fr, le nom d'hôte ne suffit plus à désigner le bon compte. L'utilisateur saisit son adresse e-mail, et Discovery s'en sert pour trouver le bon client dans votre application et dans l'environnement du nom d'hôte. Deux voies existent, selon ce que sert votre nom d'hôte.
| Votre nom d'hôte sert | Voie | Qui construit l'URL Keycloak |
|---|---|---|
| Les clients d'un seul réseau | POST /discover/start-login avec host et email | Discovery |
| Plusieurs réseaux, ou vous voulez afficher le compte avant la connexion | GET /discover/email avec domain | Votre application |
Avant de commencer
- Le nom d'hôte du portail est un hôte IAM actif de l'application dans chaque environnement où vous l'utilisez. Discovery en déduit l'application et l'environnement, et Keycloak accepte l'adresse de retour
https://portail.mon-app.fr/api/auth/callback(voir Déclarer les hôtes IAM et les redirect URIs). - Chaque build envoie son propre nom d'hôte, lu dans
window.locationou dans l'en-têteHost: un build de dev qui envoie le nom d'hôte de production connecte ses utilisateurs sur les fiches de production. - Pour la voie
GET /discover/email, votre service porte une variableKEYCLOAK_URLpar environnement :https://auth.wakastart.appen production,https://auth-staging.wakastart.appen staging,https://auth-dev.wakastart.appen développement (voir Variables et secrets). Cette voie ne reçoit pas l'instance de Discovery.
À ne pas faire
- Ne passez jamais d'
appId: c'est le nom d'hôte, danshostoudomain, qui borne la recherche à votre application. - N'appelez jamais
POST /discover/start-loginsanshost: l'e-mail seul n'est plus accepté et la réponse est400. - N'omettez jamais
domainsurGET /discover/email: sans lui, seules les fiches de production sont cherchées, puis, à une date qui sera annoncée, plus aucune.
Départager les clients d'un réseau
-
Sur votre page de connexion, demandez l'adresse e-mail de l'utilisateur.
-
Depuis votre serveur, appelez
POST /discover/start-loginavec le nom d'hôte complet, l'adresse saisie et vos paramètres PKCE :Bashcurl -s https://discovery.wakastart.app/discover/start-login \ -H 'Content-Type: application/json' \ -d '{ "host": "portail.mon-app.fr", "email": "claire.martin@exemple.fr", "redirectUri": "https://portail.mon-app.fr/api/auth/callback", "state": "q8XGm2Vt0oKc4bQ1", "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "codeChallengeMethod": "S256" }' -
Si la réponse contient
keycloakUrl, redirigez le navigateur vers cette adresse. -
Si elle contient
"ambiguous": true, l'adresse a une fiche chez plusieurs clients du réseau. Affichez lescustomer_namedecandidates, puis rappelezstart-loginavec les mêmes champs et lecustomer_widchoisi danscustomerWid:JSON{ "ambiguous": true, "candidates": [ { "customer_wid": "EXCLI1", "customer_name": "Clinique Exemple", "customer_subdomain": null }, { "customer_wid": "EXCLI2", "customer_name": "Centre Exemple", "customer_subdomain": null } ] }
Résultat attendu : le second appel renvoie { "keycloakUrl": "…" }. Le retour sur /api/auth/callback et l'échange du code sont ceux de la connexion par nom d'hôte (voir Recevoir le code et l'échanger).
Rechercher les comptes de l'utilisateur
- Sur votre page de connexion, demandez l'adresse e-mail de l'utilisateur.
- Depuis votre serveur, appelez Discovery avec cette adresse et le nom d'hôte de votre front dans
domain. Discovery en déduit l'environnement et ne cherche que dans ses fiches :
curl -s "https://discovery.wakastart.app/discover/email?email=claire.martin%40exemple.fr&domain=portail.mon-app.fr"const params = new URLSearchParams({
email: "claire.martin@exemple.fr",
domain: new URL(process.env.PUBLIC_URL!).hostname, // portail.mon-app.fr
});
const response = await fetch(`https://discovery.wakastart.app/discover/email?${params}`);
const { users } = (await response.json()) as { users: DiscoveredAccount[] };Réponse attendue (extrait, un compte) :
{
"users": [
{
"user_email": "claire.martin@exemple.fr",
"customer_wid": "EXCLI1",
"customer_name": "Clinique Exemple",
"network_wid": "EXNET1",
"network_name": "Réseau Exemple",
"network_realm_id": "realm-EXNET1",
"idp_id": null,
"idp_name": null,
"idp_type": null,
"keycloak_org_alias": "EXCLI1",
"app_wid": "EXAPP1",
"app_name": "Mon App",
"app_client_id": "EXAPP1",
"app_url_front": "https://portail.mon-app.fr",
"theme_name": "default",
"default_lang": "fr"
}
]
}La réponse a toujours la même forme. { "users": [] } signifie qu'aucun compte actif ne correspond pour ce nom d'hôte, ou que domain ne correspond à aucun hôte IAM de l'application : affichez un message neutre, par exemple « Vérifiez votre adresse et réessayez », jamais « Cette adresse n'existe pas ».
Choisir le compte
- Si
userscontient un seul compte, passez à l'étape suivante. - Si
usersen contient plusieurs, affichez à l'utilisateur la liste descustomer_nameet laissez-le choisir. Vous pouvez habiller chaque choix avectheme_nameet les champsbranding_*. - Optionnel : si
idp_nameest renseigné, indiquez à l'utilisateur qu'il se connectera avec le fournisseur d'identité de son entreprise.
Construire l'URL d'autorisation
Construisez l'URL avec KEYCLOAK_URL, le network_realm_id et l'app_client_id du compte choisi, les mêmes scopes que Discovery et vos paramètres PKCE :
import { createHash, randomBytes } from "node:crypto";
export function buildAuthorizationUrl(account: { network_realm_id: string; app_client_id: string; user_email: string }) {
const verifier = randomBytes(32).toString("base64url");
const state = randomBytes(16).toString("base64url");
const issuer = `${process.env.KEYCLOAK_URL}/realms/${account.network_realm_id}`;
const url = new URL(`${issuer}/protocol/openid-connect/auth`);
url.search = new URLSearchParams({
client_id: account.app_client_id,
response_type: "code",
scope: "openid profile email organization",
redirect_uri: `${process.env.PUBLIC_URL}/api/auth/callback`,
state,
code_challenge: createHash("sha256").update(verifier).digest("base64url"),
code_challenge_method: "S256",
login_hint: account.user_email, // préremplit l'identifiant sur la page Keycloak
}).toString();
// À conserver dans la session serveur jusqu'au retour sur /api/auth/callback.
return { url: url.toString(), verifier, state, issuer, clientId: account.app_client_id };
}Résultat attendu :
https://auth.wakastart.app/realms/realm-EXNET1/protocol/openid-connect/auth?client_id=EXAPP1&response_type=code&scope=openid+profile+email+organization&redirect_uri=https%3A%2F%2Fportail.mon-app.fr%2Fapi%2Fauth%2Fcallback&state=…&code_challenge=…&code_challenge_method=S256&login_hint=claire.martin%40exemple.frEnregistrez verifier, state, issuer et clientId dans la session, puis redirigez l'utilisateur vers url. Le retour sur /api/auth/callback et l'échange du code sont identiques à ceux de la connexion par nom d'hôte (voir Recevoir le code et l'échanger).
Vérifier le résultat
- Saisissez l'adresse d'un compte de test sur la page de connexion du portail.
- Choisissez le client si plusieurs comptes sont proposés.
Résultat attendu : la page Keycloak s'affiche avec l'adresse préremplie ; après connexion, GET /api/me renvoie le client choisi dans customer.
Voir aussi
- Flux de connexion : comparaison des trois façons de résoudre le realm.
- Référence : réponse de /discover/email.
- Résoudre les problèmes de connexion.