Aller au contenu

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.

ConceptDéveloppeur
Voir en Markdown

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 par type d'environnement. Chaque environnement de votre application est servi par l'instance de son type :

Type d'environnementInstance Keycloak
prodhttps://auth.wakastart.app
staginghttps://auth-staging.wakastart.app
devhttps://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 de clients a son propre 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 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 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 :

Texte
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 Wakastart.

Exemples

Hôte IAMEnvironnementInstance renvoyéeAdresse de retour
mon-app.exemple.frprodauth.wakastart.apphttps://mon-app.exemple.fr/api/auth/callback
recette.mon-app.exemple.frstagingauth-staging.wakastart.apphttps://recette.mon-app.exemple.fr/api/auth/callback
monapp.localhost:3000devauth-dev.wakastart.apphttp://monapp.localhost:3000/api/auth/callback

Pour aller plus loin