# Discovery

> Comment votre application trouve sa page de connexion sans connaître ni son realm, ni son instance Keycloak, ni son environnement : tout part du nom d'hôte.

[Discovery](/v1.0/glossaire#discovery) est le service public qui répond à la première question de toute connexion : vers quelle page envoyer cet utilisateur ? Votre application lui envoie le nom d'hôte de sa propre page ; Discovery en déduit l'application, l'environnement et le realm, et renvoie l'adresse de connexion complète. Votre application ne lui transmet jamais l'environnement : c'est le nom d'hôte qui le désigne.

## Définition

Discovery est joignable à `https://discovery.wakastart.app`, sans jeton : l'utilisateur n'est pas encore connecté. Il propose trois façons de résoudre le realm, toutes fondées sur le nom d'hôte du front.

```mermaid
flowchart TD
  Q{"Que désigne le nom d'hôte<br/>de votre front ?"}
  Q -->|"une seule organisation"| P1["POST /discover/start-login<br/>{ host }"]
  Q -->|"un réseau, plusieurs clients"| P2["POST /discover/start-login<br/>{ host, email }"]
  Q -->|"un portail commun à plusieurs réseaux"| P3["GET /discover/email<br/>?email=…&domain=…"]
  P1 --> R1["{ keycloakUrl }"]
  P2 --> R1
  P2 -->|"plusieurs clients pour cet e-mail"| A["{ ambiguous, candidates }<br/>puis nouvel appel avec customerWid"]
  A --> R1
  P3 --> R3["{ users: [ … ] }<br/>URL construite avec KEYCLOAK_URL"]
  R1 --> K["Page de connexion Keycloak<br/>de l'environnement de l'hôte"]
  R3 --> K
```

## Pourquoi ça existe

Chaque réseau a un realm par environnement, et chaque environnement son instance Keycloak. Si votre application codait ces valeurs, il faudrait une version par réseau et par environnement. Avec Discovery, le même code fonctionne partout : c'est le nom d'hôte du front, différent pour chaque environnement et chaque organisation, qui porte l'information.

C'est aussi ce nom d'hôte qui désigne les fiches utilisateurs consultées : chaque environnement a son propre référentiel d'utilisateurs, et Discovery ne cherche que dans celui de l'environnement de l'hôte.

## Comment ça marche

### Par nom d'hôte : une application mono-organisation par adresse

Votre application envoie le **nom d'hôte complet** de la page, par exemple `app.clinique-du-parc.fr`, à `POST /discover/start-login`, avec son adresse de retour et ses paramètres PKCE :

| Champ | Contenu |
|---|---|
| `host` | **obligatoire** : le nom d'hôte complet du front (`window.location.host` côté navigateur, en-tête `Host` côté serveur), sans `https://` ni chemin, avec le port pour un hôte local (`monapp.localhost:3000`) |
| `redirectUri` | l'adresse de retour : `https://<nom d'hôte>/api/auth/callback` |
| `state`, `nonce` | facultatifs, recopiés dans l'URL |
| `codeChallenge`, `codeChallengeMethod` | le défi PKCE ; seule la méthode `S256` est acceptée |

Discovery cherche ce nom d'hôte dans les **hôtes IAM**. Chaque [hôte IAM](/v1.0/glossaire#hôte-iam) relie un nom d'hôte à une application, un réseau, un client et un environnement (dev, staging ou prod). Il en déduit l'instance Keycloak, le realm de cet environnement et l'identifiant client, et renvoie :

```json
{
  "keycloakUrl": "https://auth.wakastart.app/realms/realm-EXNET1/protocol/openid-connect/auth?client_id=EXAPP1&response_type=code&scope=openid+profile+email+organization&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256"
}
```

Une adresse correspond à un seul realm. Sans `host`, la réponse est `400` (`invalid_request`) ; si aucun hôte IAM ne correspond, `404` avec le message `not_found`. Les hôtes IAM se lisent dans l'onglet **URLs & IAM** de chaque environnement.

Un ancien sous-domaine de réseau ou de client (`reseau-exemple`) reste accepté dans `host`, mais il ne désigne aucun environnement. Discovery ne le résout que si tous les hôtes IAM actifs de ce réseau, ou de ce client, appartiennent au même environnement ; sinon la réponse est `404`. Envoyez toujours le nom d'hôte complet.

### Par nom d'hôte et e-mail : plusieurs clients d'un même réseau

Quand un nom d'hôte sert un réseau dont plusieurs clients ont leurs utilisateurs, la même adresse e-mail peut avoir une fiche chez plusieurs d'entre eux. Envoyez alors `email` **en plus** de `host` à `POST /discover/start-login`. Le nom d'hôte désigne toujours le réseau, l'application et l'environnement ; l'e-mail sert seulement à départager les clients :

- un seul client correspond : la réponse est la `keycloakUrl` habituelle ;
- plusieurs clients correspondent : la réponse est `{ "ambiguous": true, "candidates": [ … ] }`, avec pour chaque client `customer_wid`, `customer_name` et `customer_subdomain`. Faites choisir l'utilisateur, puis rappelez `start-login` avec le `customerWid` retenu.

### Par e-mail : plusieurs organisations sur un même portail

Quand toutes les organisations partagent une adresse, la page demande d'abord l'e-mail. Votre application appelle :

```text
GET https://discovery.wakastart.app/discover/email?email=<adresse>&domain=<nom d'hôte du front>
```

`domain` est le nom d'hôte du front de votre application (`window.location.hostname`). Discovery ne renvoie que les comptes de l'application qui a un **hôte IAM actif** pour ce nom d'hôte, en déduit l'environnement et ne cherche que les fiches de cet environnement. `network_realm_id` est le realm de cet environnement. La réponse a toujours la forme `{ "users": [ … ] }`, vide si rien ne correspond. Chaque compte donne notamment `network_realm_id`, `app_client_id`, `customer_name` et `keycloak_org_alias`.

Envoyez `domain` dès maintenant, sur chaque appel. Sans lui, Discovery ne cherche que dans les fiches de production ; une fois le refus activé, à une date qui sera annoncée, une recherche sans `domain` ne renverra plus aucun compte.

Votre application construit alors l'URL elle-même, avec l'instance lue dans sa variable `KEYCLOAK_URL` et les mêmes scopes que Discovery :

```text
${KEYCLOAK_URL}/realms/${network_realm_id}/protocol/openid-connect/auth?client_id=${app_client_id}&response_type=code&scope=openid+profile+email+organization&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256
```

Si l'adresse e-mail correspond à plusieurs organisations, présentez la liste (`customer_name`) et laissez l'utilisateur choisir.

### Ce qu'il ne faut pas faire

:::warning
- **N'envoyez pas d'`appId`** pour borner la résolution : c'est le nom d'hôte, ou `domain`, qui désigne l'application. Votre application n'a pas à connaître son propre identifiant client.
- **N'appelez jamais `POST /discover/start-login` sans `host`** : un appel avec l'e-mail seul n'est plus accepté et répond `400`.
- **N'utilisez pas 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. Chaque build lit son nom d'hôte dans `window.location`, sans le coder en dur.
:::

### Bonnes pratiques

- Appelez Discovery depuis le serveur de votre application.
- Affichez un message neutre en cas de `404` ou de liste vide, sans dire si l'adresse existe.
- Ne journalisez pas les adresses e-mail transmises : ce sont des données personnelles.
- En cas de `429`, attendez avant de réessayer.

## Exemples

**Une application par organisation.** Chaque clinique a son adresse : `rdv.clinique-du-parc.fr`, `rdv.saint-louis.fr`. Le serveur de l'application envoie à Discovery le nom d'hôte de la requête reçue ; chaque clinique arrive sur sa propre page de connexion, aux couleurs de son réseau.

**Un réseau, plusieurs clients.** Un groupement de cliniques partage `rdv.groupe-sante.fr`. Le serveur envoie le nom d'hôte et l'e-mail saisi ; un praticien qui exerce dans deux cliniques du groupement choisit la sienne dans la liste des candidats.

**Un portail commun.** Un logiciel RH est servi à `app.rh-exemple.fr` pour tous ses clients. L'écran d'accueil demande l'e-mail, appelle `GET /discover/email` avec `domain=app.rh-exemple.fr`, puis envoie l'utilisateur sur le realm de son organisation.

## Par nom d'hôte ou par e-mail ?

| Critère | Par nom d'hôte | Par nom d'hôte et e-mail | Par e-mail (`/discover/email`) |
|---|---|---|---|
| Une adresse par organisation | ✔ recommandé | inutile | inutile |
| Une adresse pour les clients d'un réseau | ne départage pas les clients | ✔ | possible |
| Une adresse pour plusieurs réseaux | ne convient pas | ne convient pas | ✔ |
| Qui construit l'URL Keycloak | Discovery | Discovery | votre application, avec `KEYCLOAK_URL` |
| Environnement déduit de | l'hôte IAM de `host` | l'hôte IAM de `host` | l'hôte IAM de `domain` |
| Prérequis | un hôte IAM actif pour le nom d'hôte | un hôte IAM actif pour le nom d'hôte | un hôte IAM actif pour le nom d'hôte envoyé dans `domain` |

## Pour aller plus loin

- [Connecter vos utilisateurs](/v1.0/demarrer/connecter-vos-utilisateurs) : la connexion par nom d'hôte, de bout en bout.
- [Référence API : Discovery](/v1.0/reference-api/discovery) : tous les champs et toutes les réponses.
- [Environnements](/v1.0/concepts/environnements) : les trois instances Keycloak et `KEYCLOAK_URL`.
- [Authentification](/v1.0/authentification) : le reste du parcours de connexion.
