# Instances Keycloak et hôtes IAM

> Les trois instances Keycloak de Wakastart, et les hôtes IAM qui relient le nom d'hôte de votre front à un environnement, un realm et des redirect URIs.

Un hôte IAM est la ligne de configuration qui permet à Discovery de reconnaître votre front : il associe un nom d'hôte à votre application, à un environnement et donc à une instance Keycloak. Sans hôte IAM, Discovery répond `404` et Keycloak refuse l'adresse de retour.

## Définition

**Instance Keycloak.** Wakastart exploite une instance [Keycloak](/v1.0/glossaire#keycloak) par type d'environnement. Chaque environnement de votre application est servi par l'instance de son type :

| Type d'environnement | Instance Keycloak |
|---|---|
| `prod` | `https://auth.wakastart.app` |
| `staging` | `https://auth-staging.wakastart.app` |
| `dev` | `https://auth-dev.wakastart.app` |

Les comptes sont distincts d'une instance à l'autre : chaque environnement a son propre référentiel d'utilisateurs. Une personne qui a accès à votre application en dev et en prod y a deux fiches indépendantes, chacune avec son identifiant et son compte sur l'instance de son environnement.

**Realm.** Dans chaque instance, un [réseau](/v1.0/glossaire#réseau) de clients a son propre [realm](/v1.0/glossaire#realm). Le realm de votre application et son identifiant client figurent dans l'URL que renvoie Discovery ; votre code n'a pas à les connaître à l'avance.

**Hôte IAM.** Un [hôte IAM](/v1.0/glossaire#hôte-iam) associe un nom d'hôte, par exemple `mon-app.exemple.fr`, à une application et à un type d'environnement. Il ne crée ni certificat ni route HTTP : ces éléments relèvent des [URLs publiques](/v1.0/domaines-et-urls) de l'environnement.

## Pourquoi ça existe

Le nom d'hôte est la seule information qu'une page web connaît à coup sûr sur elle-même. En faire la clé de résolution évite à votre application de transporter des identifiants techniques, et garantit qu'un front de production ne peut obtenir que l'instance de production : l'environnement est fixé côté plateforme, pas côté application. La réciproque compte aussi : un build de dev qui envoie le nom d'hôte de production obtient l'instance et les fiches de production. Chaque build doit donc envoyer son propre nom d'hôte.

## Comment ça marche

### Création des hôtes IAM

Un hôte IAM naît de deux façons, visibles dans la section **Hôtes IAM** de l'onglet **URLs & IAM** de l'environnement :

- **automatiquement**, quand vous instanciez une URL publique dans l'environnement : Wakastart crée l'hôte IAM correspondant au nom d'hôte de l'URL ;
- **manuellement**, avec le bouton **Nouveau hôte**, par exemple pour une application mobile ou un hôte local de développement.

Le bouton **Resynchroniser IAM** recalcule les hôtes automatiques et les redirect URIs à partir des URLs de l'environnement, sans toucher aux hôtes créés à la main.

### Règles d'un nom d'hôte

- Discovery compare le nom d'hôte **exact**, tel qu'il est déclaré : sans `https://` ni chemin, en minuscules. Le port n'en fait partie que pour un hôte local (`monapp.localhost:3000`).
- Un nom d'hôte appartient à une seule application et, dans cette application, à un seul environnement.
- Les hôtes locaux (`<nom court de l'app>.localhost:<port>`) ne sont acceptés que dans un environnement `dev`. `localhost` seul et `127.0.0.1` sont refusés.
- Un hôte peut être désactivé sans être supprimé : Discovery ne le résout plus.
- Discovery garde en cache le résultat d'une résolution pendant 5 minutes, y compris un échec : un hôte que vous venez de créer peut mettre jusqu'à 5 minutes à être reconnu.

### Redirect URIs

Pour chaque hôte IAM web actif, Wakastart déclare dans le client Keycloak de votre application, sur l'instance de l'environnement, une seule adresse de retour :

```text
https://<nom d'hôte>/api/auth/callback
```

Un hôte local utilise `http://`. Les mêmes adresses sont déclarées comme adresses autorisées après déconnexion, et leurs origines (`https://<nom d'hôte>`) comme origines web. Keycloak compare l'adresse de retour caractère par caractère : votre application doit donc recevoir le code sur ce chemin précis. Les adresses personnalisées, par exemple un schéma d'application mobile `monapp://callback`, s'ajoutent dans la section **Redirect URIs Keycloak** de l'onglet, réservée au Propriétaire.

### Le client Keycloak de votre application

Le client est public (aucun secret), exige PKCE avec la méthode `S256` et demande les scopes `openid profile email organization`. Le scope `organization` ajoute au jeton l'organisation Keycloak de l'utilisateur, qui correspond à son [client](/v1.0/glossaire#client) Wakastart.

## Exemples

| Hôte IAM | Environnement | Instance renvoyée | Adresse de retour |
|---|---|---|---|
| `mon-app.exemple.fr` | `prod` | `auth.wakastart.app` | `https://mon-app.exemple.fr/api/auth/callback` |
| `recette.mon-app.exemple.fr` | `staging` | `auth-staging.wakastart.app` | `https://recette.mon-app.exemple.fr/api/auth/callback` |
| `monapp.localhost:3000` | `dev` | `auth-dev.wakastart.app` | `http://monapp.localhost:3000/api/auth/callback` |

## Pour aller plus loin

- [Déclarer les hôtes IAM et les redirect URIs](/v1.0/authentification/declarer-les-hotes-et-redirect-uris).
- [Environnements](/v1.0/concepts/environnements) : dev, staging et prod.
- [Domaines et URLs](/v1.0/domaines-et-urls) : exposer votre front sur un nom d'hôte.
