Skip to content

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.

ConceptDeveloper

This page has not been translated yet and is shown in French.

Une wakapp ne connaît jamais son realm Keycloak : elle envoie son propre nom d'hôte à 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 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.
  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 :

OrigineCréationMise à jour
AutomatiqueDé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
ManuelleNouveau hôte dans l'onglet URLs & IAMSeulement 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