Aller au contenu

Déclarer les hôtes IAM et les redirect URIs

Faire reconnaître le nom d'hôte de votre front par Discovery et Keycloak, et ajouter une adresse de retour personnalisée pour une application mobile.

GuideDéveloppeur
Accès requis
Administrateur réseau ou plus, avec le droit « Gérer les URLs/routage » (et « Accès infrastructure en production » en prod). Redirect URIs personnalisées : Propriétaire.
Durée
10 min
Voir en Markdown

Discovery ne reconnaît un nom d'hôte que s'il est déclaré comme hôte IAM d'un environnement de votre application. Ce guide montre comment vérifier qu'un hôte existe, en créer un à la main, et ajouter une adresse de retour personnalisée. Toutes ces opérations se font dans la console Wakastart.

Avant de commencer

  • Votre application et l'environnement existent. Votre application est créée par Wakastart ; contactez-nous pour en ouvrir une.
  • Pour un front web, l'URL publique est créée dans l'architecture de l'application (voir Domaines et URLs). Instancier cette URL dans l'environnement crée l'hôte IAM automatiquement : dans la plupart des cas, vous n'avez rien d'autre à faire.

Vérifier les hôtes IAM d'un environnement

  1. Dans la console Wakastart, ouvrez le menu de votre application, puis Environnements.
  2. Cliquez sur l'environnement, puis ouvrez l'onglet URLs & IAM.
  3. Descendez jusqu'à la section Hôtes IAM.

Résultat : la liste affiche chaque nom d'hôte de l'environnement. Un hôte inactif ne sera pas résolu par Discovery ; activez-le avec l'action Activer ce mapping hôte.

Si un hôte attendu manque alors que l'URL publique est instanciée, cliquez sur Resynchroniser IAM. Le bandeau « Synchronisation IAM en cours… » s'affiche, puis la liste se met à jour.

Créer un hôte IAM à la main

Créez un hôte à la main pour un hôte local de développement ou une application mobile.

  1. Dans la section Hôtes IAM, cliquez sur Nouveau hôte.
  2. Dans la fenêtre Nouvel hôte IAM, renseignez :
    • pour un front web ou local, Pattern d'hôte : le nom d'hôte exact, par exemple app.mondomaine.fr, ou monapp.localhost:3000 dans un environnement dev (le sous-domaine doit être le nom court ou l'identifiant de votre application) ;
    • pour une application mobile, cochez App mobile (deep link), puis renseignez Schéma (par exemple monapp) et Chemin callback (par défaut callback). La fenêtre affiche l'adresse obtenue, par exemple monapp://callback.
  3. Laissez Actif coché.
  4. Cliquez sur Créer.

Résultat : le message « Hôte IAM créé » s'affiche. Wakastart déclare l'adresse de retour https://<nom d'hôte>/api/auth/callback (ou schéma://chemin pour une application mobile) dans le client Keycloak de l'environnement.

Note

Discovery garde en cache ses résolutions, y compris les échecs, pendant 5 minutes. Un hôte que vous venez de créer peut donc renvoyer 404 pendant ce délai.

Ajouter une redirect URI personnalisée

Les adresses de retour auto sont dérivées des hôtes IAM. Ajoutez une adresse custom quand votre application doit recevoir le code ailleurs, par exemple sur un lien profond mobile.

  1. Dans l'onglet URLs & IAM, descendez jusqu'à la section Redirect URIs Keycloak.
  2. Dans la liste Valid redirect URIs, cliquez sur Ajouter.
  3. Saisissez l'adresse, par exemple https://app.example.com/api/auth/callback ou monapp://callback, puis cliquez sur OK.

Résultat : le message « Redirect URIs mises à jour » s'affiche et l'adresse apparaît avec l'étiquette custom. Les listes Valid post logout redirect URIs et Web origins (dérivés automatiquement) sont recalculées.

Règles appliquées :

  • le joker * seul est interdit ;
  • en production, une adresse web doit être en HTTPS, sauf une adresse locale ;
  • 50 adresses personnalisées au plus par application et par environnement.

Vérifier le résultat

Interrogez Discovery avec le nom d'hôte déclaré :

Bash
curl -s https://discovery.wakastart.app/discover/start-login \
  -H 'Content-Type: application/json' \
  -d '{ "host": "app.mondomaine.fr", "redirectUri": "https://app.mondomaine.fr/api/auth/callback" }'

Réponse attendue :

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=https%3A%2F%2Fapp.mondomaine.fr%2Fapi%2Fauth%2Fcallback"
}

L'instance dans l'URL doit correspondre au type de l'environnement : auth.wakastart.app pour prod, auth-staging.wakastart.app pour staging, auth-dev.wakastart.app pour dev.

Dépannage

  • « Host "…" is already in use for environment "…" of this app — a host can only belong to one environment per app » : le nom d'hôte est déjà déclaré dans un autre environnement de l'application.
  • « Le host "…" est déjà déclaré par une autre wakapp » : un nom d'hôte n'appartient qu'à une seule application.
  • « Les patterns localhost/*.localhost ne sont autorisés qu'en environnement dev » : un hôte local n'est accepté que dans un environnement dev.

Les autres cas sont dans Résoudre les problèmes de connexion.

Voir aussi