Dépannage : identité

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la fonctionnalité côté produit : guide produit ; l'appeler : guide développeur.

Symptôme	Cause	Action
401 sur des jetons valides juste après un démarrage	Les clés de l'émetteur ne sont pas encore chargées	Le journal dit issuer not reachable yet ; vérifier que la passerelle joint l'URL de découverte
401 invalid_token sur un jeton qui marche ailleurs	Audience, émetteur ou algorithme : le motif est au journal (token refused), jamais dans la réponse	Comparer aud et iss du jeton à auth.issuers
403 insufficient_scope	Le jeton ne porte pas la portée ou le rôle que le contrat exige	Lire scope= dans WWW-Authenticate ; pour un rôle, vérifier roles_claim
401 WWW-Authenticate: ApiKey sur une clé qu'on croit bonne	Clé inconnue (retirée, mal copiée), expirée, ou sans le préfixe fwk_	Le journal (API key refused) donne la cause et, pour une clé expirée, son id ; recréer la clé
401 « does not accept API keys »	L'opération n'a pas d'alternative apiKey dans le contrat	Ajouter { key: [] } à son security, si c'est voulu
403 not bound to this operation (clé ou certificat)	L'entrée ne nomme pas cette opération	Ajouter l'operationId à operations de l'entrée ; rechargement
Refus au chargement « no contract declares » sur une clé ou un certificat	L'entrée nomme une opération qui n'existe pas (renommée ?)	Corriger l'operationId
401 « requires a client certificate » malgré un certificat	Certificat non déclaré, ou x-forwarded-client-cert venu d'un pair hors server.trusted_proxies	Vérifier l'URI SAN ou le sujet face à auth.mtls.clients ; déclarer la plage de l'edge
Poignée de main TLS refusée sur :8443	Certificat client d'une autre autorité que client_ca_file	Ajouter l'autorité au fichier : il est relu sans redémarrage
403 « This origin is not allowed »	L'origine du navigateur n'est dans aucune politique cors	L'ajouter à allow_origins