Aller au contenu

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.

GuideDéveloppeur
Durée
25 min
Voir en Markdown

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 sertVoieQui construit l'URL Keycloak
Les clients d'un seul réseauPOST /discover/start-login avec host et emailDiscovery
Plusieurs réseaux, ou vous voulez afficher le compte avant la connexionGET /discover/email avec domainVotre 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.location ou dans l'en-tête Host : 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 variable KEYCLOAK_URL par environnement : https://auth.wakastart.app en production, https://auth-staging.wakastart.app en staging, https://auth-dev.wakastart.app en 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, dans host ou domain, qui borne la recherche à votre application.
  • N'appelez jamais POST /discover/start-login sans host : l'e-mail seul n'est plus accepté et la réponse est 400.
  • N'omettez jamais domain sur GET /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

  1. Sur votre page de connexion, demandez l'adresse e-mail de l'utilisateur.

  2. Depuis votre serveur, appelez POST /discover/start-login avec le nom d'hôte complet, l'adresse saisie et vos paramètres PKCE :

    Bash
    curl -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"
      }'
  3. Si la réponse contient keycloakUrl, redirigez le navigateur vers cette adresse.

  4. Si elle contient "ambiguous": true, l'adresse a une fiche chez plusieurs clients du réseau. Affichez les customer_name de candidates, puis rappelez start-login avec les mêmes champs et le customer_wid choisi dans customerWid :

    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

  1. Sur votre page de connexion, demandez l'adresse e-mail de l'utilisateur.
  2. 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 :
Bash
curl -s "https://discovery.wakastart.app/discover/email?email=claire.martin%40exemple.fr&domain=portail.mon-app.fr"
TypeScript
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) :

JSON
{
  "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

  1. Si users contient un seul compte, passez à l'étape suivante.
  2. Si users en contient plusieurs, affichez à l'utilisateur la liste des customer_name et laissez-le choisir. Vous pouvez habiller chaque choix avec theme_name et les champs branding_*.
  3. Optionnel : si idp_name est 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 :

TypeScript
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 :

Texte
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.fr

Enregistrez 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

  1. Saisissez l'adresse d'un compte de test sur la page de connexion du portail.
  2. 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