logo
Développement
AperçuEspaceDéveloppementEspaceDeTravailRéférenceAPIMeilleurePratiqueJournalDesModifications
Rechercher
Français
RéférenceAPI / ConnexionAppsExtension / Dépannage
07 · Questions fréquentes et dépannage
Dernière mise à jour：2 days ago

07 · Questions fréquentes et dépannage

Tableau récapitulatif des codes d'erreur

WsaVerificationError.code levés par verifyWsa

code Cause fréquente Comment diagnostiquer
InvalidSignature Clé erronée, jeton altéré, mauvaise clé Tier1/Tier2 Vérifiez que la clé utilisée par le backend correspond à celle enregistrée/distribuée ; passez la clé per-app telle quelle en chaîne, sans décodage hex
WrongAudience L'audience ne correspond pas au aud du jeton L'audience doit être exactement égale au host de l'URL enregistrée (ex. app.example.com), sans port ni protocole
WrongIssuer La configuration de l'issuer a été modifiée Conservez la valeur par défaut gptbots-workspace
Expired Jeton de plus de 5 minutes, décalage d'horloge du serveur Synchronisez l'horloge du serveur par NTP ; le wsa est un jeton d'amorçage à usage unique, ne le réutilisez pas après l'avoir mis en cache
NotYetValid iat/nbf dans le futur Généralement une désynchronisation d'horloge sévère entre l'émetteur et le vérificateur
MissingClaim Manque exp/sub/role/workspace_id Un jeton normal de la plateforme n'en manque jamais ; son apparition indique une origine de jeton suspecte
UnsupportedAlgorithm alg absent de la liste blanche Par défaut uniquement HS256 ; RS256 nécessite explicitement algorithms:['RS256'] + publicKey
InvalidToken Jeton vide/structure invalide/tronqué Vérifiez que le frontend récupère bien le wsa complet, et que l'URL n'a pas été réécrite par un intermédiaire

Phase d'échange /token (pull)

code Signification Condition de déclenchement
403209 Invalid grant code manquant, expiré ou déjà utilisé (rejeu). Le code ne peut être utilisé qu'une fois
403210 Invalid verifier Le codeVerifier PKCE ne correspond pas au code_challenge initial

sign-token push (appelé par le frontend de l'espace de travail, à titre informatif)

code Signification Condition de déclenchement
40000 Parameter error URL non enregistrée, auth_mode différent de workspace_account
40100 Permission deny Non connecté ou session invalide
40105 Require member of project Le cliqueur n'est pas membre de cet espace de travail
40320 Member not found Compte désactivé/supprimé

FAQ

Q : Dois-je choisir le push ou le pull ?
R : Point d'entrée dans la page « Extensions » de l'espace de travail, souhait de faire une « application embarquée » → push (le plus simple). Si votre application est un site indépendant et que vous voulez afficher un bouton « Se connecter avec GPTBots » → pull (M-Auth, plus sûr, le wsa n'entre pas dans le navigateur). Voir 02.

Q : Peut-on décoder directement le JWT dans le frontend pour récupérer les informations utilisateur ?
R : On peut le décoder pour le lire, mais pas le traiter comme une identité de confiance — sans la clé, impossible de vérifier la signature, et le payload peut être falsifié. Toute décision d'autorisation doit reposer sur le résultat de verifyWsa côté backend. Voir 05 §5.

Q : Que faire si le wsa a expiré ?
R : Le wsa n'est qu'un jeton d'amorçage à usage unique (5 minutes). Vérifiez-le une fois à l'atterrissage, échangez-le contre votre propre session, puis utilisez toujours votre session ensuite, sans plus dépendre du wsa. L'utilisateur obtiendra un nouveau wsa à sa prochaine ouverture depuis la page des extensions.

Q : consumeHandoff lève « no handoff token present » sur la page d'atterrissage ?
R : Cela signifie que l'URL courante ne contient pas de ?wsa= — soit l'utilisateur y a accédé directement, soit le wsa a déjà été effacé par un échange réussi précédent. Distinguez « premier atterrissage avec jeton » et « accès normal », ce dernier passant par votre propre branche de connexion/anonyme.

Q : La connexion pull renvoie StateMismatch / MissingRequest au callback ?
R : MissingRequest = vous n'avez pas d'abord appelé startWorkspaceLogin dans la même session de navigateur (le verifier PKCE est stocké dans sessionStorage, il est perdu si vous changez d'onglet ou effacez le stockage). StateMismatch = le state du callback ne correspond pas à celui stocké (protection CSRF) ; vérifiez qu'il n'y a pas de changement d'appareil/de session.

Q : La connexion pull renvoie CryptoUnavailable ?
R : PKCE nécessite Web Crypto, disponible uniquement dans un contexte sécurisé (HTTPS ou localhost). Utilisez HTTPS ou déboguez en local sur localhost.

Q : Le redirect_uri renvoie invalid_request / revient à la page de sélection d'organisation ?
R : Le scheme + host du redirect_uri doivent être exactement identiques à ceux de client_id (URL enregistrée). Une application https ne peut pas configurer un callback http ; le host doit être identique. La plateforme ne redirige jamais vers une adresse non vérifiée, elle revient donc à la page de sélection d'organisation avec ?error=invalid_request.

Q : Comment utiliser la clé per-app comme clé HMAC ? Faut-il un décodage base64/hex ?
R : Passez-la telle quelle en chaîne (le SDK et la plateforme utilisent tous deux directement les octets UTF-8 comme clé HMAC). La clé Tier 2 a la forme wext_+64 hex ; la chaîne entière est la clé, ne la décodez pas.

Q : Un projet CommonJS peut-il utiliser le SDK ?
R : Le SDK est en ESM. Un projet CJS utilise un import() dynamique, ou convertit les modules concernés en ESM.

Q : Comment modifier l'icône/le nom ?
R : Tier 2 se modifie dans la gestion de l'espace ; pour Tier 1, contactez l'exploitation de la plateforme pour modifier l'entrée du dictionnaire.

Q : Que se passe-t-il si un administrateur désactive mon application ?
R : Un administrateur d'organisation peut désactiver une application dans la gestion de l'espace (y compris la visibilité des applications publiques de la plateforme dans cette organisation). Une fois désactivée, les membres de cette organisation ne voient plus le point d'entrée sur la page des extensions, et la plateforme ne signe plus de wsa pour cette organisation (refus en push comme en pull).

Liste de vérification de débogage

  • audience == host de l'URL enregistrée (la source la plus fréquente de WrongAudience)
  • La clé backend correspond à celle enregistrée/distribuée, et est uniquement dans le backend
  • Horloge du serveur synchronisée par NTP (Expired / NotYetValid sont souvent dus à l'horloge)
  • Après l'atterrissage, history.replaceState efface le wsa / code
  • Échange contre une session propre, les requêtes suivantes ne transmettent plus le wsa
  • Pull : contexte sécurisé HTTPS/localhost ; redirect_uri du même domaine que client_id
  • Isolation multi-tenant par workspace_id

Références