# Hôtes IAM

> Comment chaque nom d'hôte de votre application est relié au bon realm Keycloak, et pourquoi Discovery en a besoin pour connecter vos utilisateurs.

Une wakapp ne connaît jamais son realm Keycloak : elle envoie son propre nom d'hôte à [Discovery](/v1.0/glossaire#discovery), qui répond avec l'adresse de connexion. Ce qui permet à Discovery de répondre, c'est l'**hôte IAM** : la correspondance entre un nom d'hôte et le realm de l'application pour un type d'environnement.

## Définition

Un hôte IAM associe :

- un **motif d'hôte** (**Pattern d'hôte**), par exemple `app.exemple.fr` ou, avec l'option **Wildcard ( *. )**, tous les sous-domaines d'un nom ;
- une **application** et un **type d'environnement** (dev, staging ou prod) ;
- le [realm](/v1.0/glossaire#realm) Keycloak du réseau de l'application.

Il sert à deux choses :

1. **Résoudre le realm et l'environnement** : quand votre front appelle `POST /discover/start-login` avec `host` égal à `window.location.host`, ou `GET /discover/email` avec `domain`, Discovery cherche l'hôte IAM actif qui correspond. Il en déduit l'environnement, donc les fiches utilisateurs à consulter, et renvoie l'URL d'autorisation ou les comptes de cet environnement. Sans hôte IAM, Discovery ne se rabat jamais sur la production. Voir [Authentification](/v1.0/authentification).
2. **Autoriser les redirections OAuth2** : les noms d'hôte des hôtes IAM sont déclarés comme adresses de retour autorisées dans Keycloak.

Un hôte IAM n'est pas une URL publique : il ne crée ni DNS ni certificat. Une URL publique sans hôte IAM est joignable, mais la connexion par nom d'hôte y échoue.

## Pourquoi ça existe

Le nom d'hôte est la seule information fiable dont dispose un front au moment de la connexion : il porte à la fois l'application et l'environnement. `app.staging.exemple.fr` doit envoyer vers le Keycloak de staging, `app.exemple.fr` vers celui de prod. L'hôte IAM rend cette règle explicite, et l'unicité d'un hôte garantit qu'un nom ne mène jamais au realm d'une autre application.

## Comment ça marche

Les hôtes IAM ont deux origines :

| Origine | Création | Mise à jour |
|---|---|---|
| **Automatique** | Dérivée des routes en ligne : chaque nom d'hôte instancié produit un hôte IAM | À chaque instanciation de route, à chaque changement de préfixe, et sur **Resynchroniser IAM** |
| **Manuelle** | **Nouveau hôte** dans l'onglet **URLs & IAM** | Seulement par vous ; la resynchronisation ne les modifie ni ne les supprime jamais |

La resynchronisation aligne les hôtes automatiques sur les noms d'hôte réels de tous les environnements du même type, puis met à jour les adresses de retour autorisées dans Keycloak. Elle n'écrase jamais un nom déjà porté par un hôte manuel ou par une autre application.

Règles d'unicité :

- un nom d'hôte n'appartient qu'à **une seule application** ;
- un même nom d'hôte ne peut pas servir deux types d'environnement d'une même application ;
- en dev uniquement, un hôte local de la forme `<identifiant de l'app>.localhost:<port>` est accepté ; `localhost` seul et `127.0.0.1` sont refusés.

Les hôtes manuels servent aux noms que la plateforme ne connaît pas : une application mobile (option **App mobile (deep link)**, qui déclare un schéma de retour comme `monapp://callback`), un poste de développement local, ou un nom servi en dehors de Wakastart.

## Exemples

- **App mono-tenant en trois environnements** : vous instanciez les routes ; les hôtes `app.dev.exemple.fr`, `app.staging.exemple.fr` et `app.exemple.fr` apparaissent seuls, chacun rattaché au bon Keycloak.
- **Application mobile** : vous créez en prod un hôte manuel avec **App mobile (deep link)**, schéma `monapp`, chemin `callback`.
- **Développement local** : en dev, un hôte manuel `monapp.localhost:5173` permet de tester la connexion depuis votre poste.

## Pour aller plus loin

- [Gérer les hôtes IAM](/v1.0/domaines-et-urls/gerer-les-hotes-iam)
- [Authentification](/v1.0/authentification)
- [URLs, routes et noms d'hôte](/v1.0/domaines-et-urls/urls-et-routes)
