# 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.

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`](#départager-les-clients-dun-réseau) | Discovery |
| Plusieurs réseaux, ou vous voulez afficher le compte avant la connexion | [`GET /discover/email` avec `domain`](#rechercher-les-comptes-de-lutilisateur) | 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](/v1.0/authentification/declarer-les-hotes-et-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](/v1.0/variables-et-secrets)). Cette voie ne reçoit pas l'instance de Discovery.

:::warning[À 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](/v1.0/authentification/integrer-la-connexion-application-serveur#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"
```

```ts
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 :

```ts
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 :

```text
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](/v1.0/authentification/integrer-la-connexion-application-serveur#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

- [Flux de connexion](/v1.0/authentification/flux-de-connexion) : comparaison des trois façons de résoudre le realm.
- [Référence : réponse de /discover/email](/v1.0/authentification/reference#compte-renvoyé-par-discovery).
- [Résoudre les problèmes de connexion](/v1.0/authentification/depannage#discovery-renvoie-une-liste-vide).
