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.
- 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
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
- Dans la console Wakastart, ouvrez le menu de votre application, puis Environnements.
- Cliquez sur l'environnement, puis ouvrez l'onglet URLs & IAM.
- 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.
- Dans la section Hôtes IAM, cliquez sur Nouveau hôte.
- 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, oumonapp.localhost:3000dans 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éfautcallback). La fenêtre affiche l'adresse obtenue, par exemplemonapp://callback.
- pour un front web ou local, Pattern d'hôte : le nom d'hôte exact, par exemple
- Laissez Actif coché.
- 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.
- Dans l'onglet URLs & IAM, descendez jusqu'à la section Redirect URIs Keycloak.
- Dans la liste Valid redirect URIs, cliquez sur Ajouter.
- Saisissez l'adresse, par exemple
https://app.example.com/api/auth/callbackoumonapp://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é :
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 :
{
"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.