Résoudre les problèmes de connexion
Causes et solutions des erreurs rencontrées en intégrant la connexion d'une wakapp, de Discovery à /api/me, messages cités à l'identique.
This page has not been translated yet and is shown in French.
Cette page part de ce que vous observez : une réponse de Discovery, un écran Keycloak, une erreur de l'API publique. Chaque symptôme indique sa cause probable, la solution et la façon de vérifier.
Symptômes
- Discovery répond 400 invalid_request
- Discovery répond 404 not_found
- Discovery renvoie une liste vide
- Keycloak affiche « Invalid parameter: redirect_uri »
- L'échange du code renvoie invalid_grant
- /api/me répond 401 Authentification requise
- L'API répond 403 Access denied
- /api/me répond 404 ou 409
- L'enrichissement renvoie un objet vide
- Le rafraîchissement renvoie Token is not active
- L'utilisateur est reconnecté sans mot de passe après la déconnexion
- L'utilisateur reste connecté quand la déconnexion échoue
- Un build de dev connecte des comptes de production
- Une réponse 429 Too Many Requests
Discovery répond 400 invalid_request
{ "statusCode": 400, "message": ["invalid_request: host is required (non-empty string, max 253 chars)"], "error": "Bad Request" }Cause : POST /discover/start-login a été appelé sans host, ou avec un host vide. Un appel avec l'e-mail seul n'est plus accepté.
Solution : envoyez toujours le nom d'hôte complet de la page (window.location.host, ou l'en-tête Host côté serveur). Si plusieurs clients partagent ce nom d'hôte, ajoutez l'e-mail en plus du nom d'hôte (voir Connecter par e-mail plusieurs clients sur un même nom d'hôte).
Pour vérifier : la même requête avec host renvoie 200.
Discovery répond 404 not_found
{ "statusCode": 404, "message": "not_found", "error": "Not Found" }Cause : aucun hôte IAM actif ne correspond exactement au host envoyé. Plus rarement : vous envoyez un ancien sous-domaine de réseau dont les hôtes IAM couvrent plusieurs environnements, le realm de l'environnement dev ou staging n'existe pas encore pour le réseau, ou le customerWid envoyé ne fait pas partie des candidats proposés.
Solution :
- Envoyez le nom d'hôte seul :
mon-app.exemple.fr, pashttps://mon-app.exemple.fr/, nimon-app.exemple.fr:443, ni des majuscules. Seul un hôte local garde son port :monapp.localhost:3000. - Envoyez le nom d'hôte complet, pas un sous-domaine extrait comme
reseau-exemple. - Dans la console, ouvrez l'environnement, onglet URLs & IAM, section Hôtes IAM, et vérifiez que l'hôte existe et qu'il est actif. S'il manque, cliquez sur Resynchroniser IAM ou créez-le (voir Déclarer les hôtes IAM et les redirect URIs).
- Si vous venez de créer l'hôte, attendez 5 minutes : Discovery garde aussi les échecs en cache.
Pour vérifier : POST /discover/start-login renvoie 200 et une keycloakUrl.
Discovery renvoie une liste vide
GET /discover/email répond { "users": [] }.
Cause : l'adresse n'a aucun compte actif dans l'application et l'environnement désignés par domain ; ou domain ne correspond à aucun hôte IAM actif de votre application ; ou domain est absent, et seules les fiches de production sont cherchées. Une fiche n'existe que dans un environnement : un compte créé en prod n'est pas trouvé depuis votre front de dev.
Solution :
- Envoyez toujours
domain, avec le nom d'hôte de la page, par exempleportail.mon-app.fr. - Dans la console, ouvrez l'environnement visé, onglet URLs & IAM, et vérifiez que ce nom d'hôte est un hôte IAM actif.
- Vérifiez que le compte existe chez le client dans cet environnement, et qu'il est actif.
Pour vérifier : la même requête renvoie au moins un compte, dont network_realm_id est le realm de l'environnement visé.
Keycloak affiche Invalid parameter: redirect_uri
Cause : la redirectUri envoyée n'est pas déclarée dans le client Keycloak de l'environnement.
Solution :
- Utilisez exactement
https://<nom d'hôte>/api/auth/callback, sans barre oblique finale. - Vérifiez que l'hôte IAM correspondant existe dans le même environnement que celui de l'instance Keycloak affichée.
- Pour une autre adresse (application mobile), ajoutez-la dans Redirect URIs Keycloak.
Pour vérifier : la page de connexion Keycloak s'affiche sans erreur.
L'échange du code renvoie invalid_grant
Keycloak répond 400 avec "error": "invalid_grant", par exemple "error_description": "Code not valid" ou "Incorrect redirect_uri".
Cause : code déjà utilisé ou expiré (5 minutes), redirect_uri différente de celle de la demande, ou code_verifier qui ne correspond pas au code_challenge.
Solution :
- N'échangez chaque code qu'une fois, dès sa réception.
- Envoyez la même
redirect_uriqu'à Discovery. - Envoyez le
code_verifierbrut conservé en session, sans le réencoder. - Vérifiez que l'échange vise l'émetteur lu dans la
keycloakUrl(même instance, même realm) et le mêmeclient_id.
/api/me répond 401 Authentification requise
{
"statusCode": 401,
"message": "Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)",
"error": "Unauthorized",
"timestamp": "2026-10-23T09:12:44.512Z",
"path": "/api/me"
}Cause : l'API n'a pu calculer aucun contexte pour ce jeton. Le jeton a expiré, n'est pas un jeton Keycloak valide, ou l'utilisateur n'a pas accès à l'application dans l'environnement de la session (aucun accès ni profil attribué, compte désactivé).
Solution :
- Rafraîchissez la session et réessayez une fois.
- Vérifiez que l'en-tête est bien
Authorization: Bearer <jeton>et qu'il n'y a pas aussi d'en-têtex-api-key. - Demandez à l'administrateur du client de vérifier que l'utilisateur est actif et a accès à l'application dans cet environnement, avec un profil.
L'API répond 403 Access denied
{ "statusCode": 403, "message": "Access denied: token authorized party does not match the target application" }Cause : le jeton a été émis pour une autre application que celle que vous appelez.
Solution : connectez l'utilisateur par l'hôte IAM de votre application. Un jeton n'est jamais réutilisable d'une application à l'autre.
/api/me répond 404 ou 409
404« Utilisateur non trouvé » : le compte Keycloak n'est rattaché à aucun utilisateur Wakastart. L'utilisateur doit être invité ou créé dans Wakastart avant de se connecter.409« Impossible de résoudre l'utilisateur de façon unique (customerId manquant ou invalide) » : l'adresse a des comptes chez plusieurs clients du même réseau et le jeton ne désigne pas le client. Reconnectez l'utilisateur en lui faisant choisir son organisation.
L'enrichissement renvoie un objet vide
POST /api/auth/enrich répond 200 avec {}.
Cause : les mêmes que pour le 401 de /api/me : utilisateur inconnu, inactif ou sans accès à l'application dans cet environnement, ou jeton expiré.
Solution : appelez GET /api/me avec le même jeton ; son message d'erreur précise la situation. Traitez toujours l'absence de token comme un échec.
Le rafraîchissement renvoie Token is not active
{ "error": "invalid_grant", "error_description": "Token is not active" }Cause : la session est terminée : 6 heures sans activité ou 12 heures au total par défaut, déconnexion, ou refresh token déjà remplacé par un rafraîchissement concurrent.
Solution : renvoyez l'utilisateur vers la connexion. Mutualisez les rafraîchissements et conservez toujours le dernier refresh token (voir Rafraîchir la session).
L'utilisateur est reconnecté sans mot de passe après la déconnexion
Cause : seule la session locale a été supprimée ; la session Keycloak est restée ouverte.
Solution : appelez POST /api/auth/logout avec le refresh token avant de détruire la session (voir Déconnecter un utilisateur).
L'utilisateur reste connecté quand la déconnexion échoue
Le bouton Se déconnecter ne fait rien, ou l'utilisateur reste sur la page après une erreur 4xx, 5xx ou réseau, ou une réponse { "success": false }.
Cause : votre code ne supprime les cookies et le sessionStorage qu'en cas de succès de l'appel à POST /api/auth/logout.
Solution : supprimez les cookies dans un bloc finally de la route serveur, et videz le sessionStorage puis redirigez vers /login dans un bloc finally du bouton, quelle que soit la réponse.
Pour vérifier : coupez le réseau dans les outils du navigateur, cliquez sur Se déconnecter : vous arrivez sur /login, non connecté.
Un build de dev connecte des comptes de production
Un testeur se connecte depuis votre build de dev, mais avec son compte de production, ou ne trouve pas son compte de dev.
Cause : le build envoie à Discovery le nom d'hôte de production, codé en dur ou lu dans une variable commune à tous les environnements. Discovery déduit l'environnement de ce nom d'hôte.
Solution : lisez le nom d'hôte dans window.location, ou dans l'en-tête Host de la requête reçue, et déclarez le nom d'hôte de dev comme hôte IAM de l'environnement dev.
Pour vérifier : la keycloakUrl renvoyée commence par https://auth-dev.wakastart.app/.
Une réponse 429 Too Many Requests
Cause : la limite de débit par adresse IP de Discovery ou de l'API publique est atteinte. Le message est ThrottlerException: Too Many Requests.
Solution : n'appelez Discovery qu'une fois par tentative de connexion, ne relancez pas automatiquement après un 404, et espacez les nouvelles tentatives de façon croissante.
Toujours bloqué ?
Rassemblez ces informations avant de contacter le support :
- le nom d'hôte du front et l'environnement concerné ;
- l'heure exacte de l'essai, avec le fuseau ;
- la requête envoyée (sans jeton ni mot de passe) et la réponse complète, statut et corps ;
- l'adresse e-mail du compte de test, transmise par le canal du support uniquement.