Explorer les subventions OIDC : comprendre et dépanner l'erreur "invalid_grant"

Contexte#

Dans notre communauté, nous entendons souvent une question récurrente de nos utilisateurs : Quel est le problème avec l'erreur "invalid_grant" dans Logto ? Comme #503

C'est un défi commun et un obstacle pour certains de nos utilisateurs lors de l'intégration de Logto dans leurs propres applications. Cependant, les raisons derrière cette erreur varient d'un cas à l'autre, et parfois il est difficile d'expliquer avec le contexte limité fourni. Par conséquent, comprendre le concept OIDC exact et apprendre la façon de dépanner l'issue est essentiel pour tout le monde.

Maintenant, plongeons dans les bases des subventions OIDC.

Explication des subventions OIDC#

Comme nous l'avons introduit dans un article de blog précédemment, OpenID Connect (OIDC) est un protocole construit sur OAuth 2.0.

Dans le contexte d'OIDC ou OAuth2, une subvention est un ensemble de permissions accordées par le propriétaire de la ressource (généralement l'utilisateur) à une application client. Les subventions sont essentielles pour que l'application client puisse accéder aux informations d'identité de l'utilisateur et à d'autres ressources protégées. OIDC définit plusieurs types de subventions, chacun adapté à un scénario différent et à la façon dont une application obtient un jeton d'accès.

Voici une analogie pour vous aider à mieux comprendre les subventions OIDC.

Imaginez que vous voyagez dans différents pays, et chaque pays demande un tampon de visa pour entrer. Dans ce scénario, votre passeport sert de compte utilisateur, contenant vos informations personnelles. Les subventions OIDC sont comme les moyens que vous utilisez pour demander un visa pour entrer dans un pays. Lorsqu'un visa vous est délivré, vous obtenez essentiellement le "token" pour entrer dans ce pays.

De même, lorsque vous utilisez une application, la demande de subvention est l'action que vous demandez au serveur d'autorisation de vous accorder l'accès. Le serveur d'autorisation valide votre identité, et vous délivre le "visa" (jeton d'accès) pour vous connecter à l'application.

Types de subventions OIDC couramment utilisés :#

1. Subvention de code d'autorisation : Il s'agit du type de subvention le plus couramment utilisé en OIDC. Il implique de rediriger l'utilisateur vers un serveur d'autorisation, d'obtenir un code d'autorisation, de rediriger à nouveau vers l'application et d'échanger le code contre un jeton d'accès. Pensez-y comme le processus standard pour demander un visa à l'ambassade avant d'entrer dans un pays étranger.
2. Subvention de jeton d'actualisation : En OIDC, ce type de subvention permet à une application client d'obtenir un nouveau jeton d'accès en utilisant un jeton de rafraîchissement qui a été précédemment émis. Il est couramment utilisé pour prolonger une session d'utilisateur sans nécessiter la réentrée de ses identifiants. Imaginez que votre visa vient avec une carte magique qui vous permet de prolonger votre séjour dans le pays étranger sans passer par les douanes à nouveau.
3. Subvention implicite : Ce type de subvention est utilisé pour les applications basées sur un navigateur obsolète et est moins sécurisé que la Subvention de Code d'Autorisation. Il retourne le jeton d'accès directement à l'application client. Il fonctionne comme un "visa à l'arrivée", car aucune demande de visa préalable n'est requise.
4. Subvention de credentials client : Adaptée pour la communication serveur à serveur, ce type de subvention permet à une application client de s'authentifier directement auprès du serveur d'autorisation en utilisant ses credentials (ID client et secret client). C'est comme un agent spécial montrant un badge de travail spécial pour entrer dans le pays sans passer par le processus de demande de visa.

Modèle d'objet de subvention :#

Dans Logto, la subvention est persistée dans la base de données en tant qu'entité d'objet, contenant des informations telles que l'ID du compte utilisateur, l'ID de l'application, les ressources OIDC associées et les scopes, le temps d'expiration, et plus encore. Chaque jeton de rafraîchissement et jeton d'accès est associé à un objet de subvention spécifique.

Demandes de subvention :#

Les demandes HTTP faites au serveur d'autorisation par le biais d'APIs. Une application client peut envoyer des demandes de subvention à l'endpoint de jeton OIDC à diverses fins, y compris la demande d'une nouvelle subvention (par exemple, la connexion et l'obtention des jetons de rafraîchissement et d'accès), la mise à jour des détails de la subvention (par exemple, l'échange d'un jeton de rafraîchissement contre un nouveau jeton d'accès), ou la révocation d'une subvention (par exemple, la révocation de tous les jetons délivrés aux utilisateurs connectés et la fin de leur accès).

Une demande typique de subvention de code d'autorisation ressemble à ceci :

Comprendre l'erreur "invalid_grant"#

Rencontrer une erreur invalid_grant en OIDC indique généralement que le type de subvention ou les données associées à la demande de subvention sont invalides ou non supportées. Voici quelques raisons courantes derrière cette erreur :

1. Type de subvention incorrect : L'utilisation du mauvais type de subvention pour votre application peut entraîner une erreur invalid_grant. Assurez-vous que vous utilisez le type de subvention approprié en exploitant les SDKs Logto.
2. URIs de redirection non correspondants : Lors de l'échange d'un code d'autorisation contre des jetons, l'URI de redirection utilisé dans la requête doit correspondre à celui utilisé lors de la demande d'autorisation initiale. Une non-correspondance peut entraîner une erreur invalid_grant.
3. Code d'autorisation expiré ou consommé : Dans le flux de connexion de code d'autorisation, le code d'autorisation a une durée de vie limitée, et sera marqué comme "consommé" une fois utilisé pour acquérir des jetons. Essayer d'échanger un code expiré ou consommé contre un jeton d'accès entraînera une erreur invalid_grant.
4. Jeton de rafraîchissement expiré ou tourné : Lors de l'échange d'un jeton de rafraîchissement contre un jeton d'accès, l'erreur invalid_grant se produit si le jeton de rafraîchissement est déjà expiré. De plus, pour une sécurité accrue, Logto active la rotation du jeton de rafraîchissement par défaut. Demander l'endpoint du jeton avec le même jeton de rafraîchissement une deuxième fois est considéré comme l'utilisation d'un jeton de rafraîchissement "tourné" et sera rejeté.
5. Données obligatoires ou en-têtes de requête manquants : Lors de la composition d'une demande de subvention, les paramètres obligatoires et les en-têtes de requête doivent être fournis pour le type de subvention donné. Par exemple, l'ID client doit être fourni dans toutes les demandes de subvention, et l'ID client et le secret client doivent être fournis pour la Subvention de Credentials Client. Ce risque peut également être atténué en exploitant les SDKs Logto.
6. Autres raisons : Cette erreur peut aussi survenir pour des raisons telles que la incompatibilité des credentials client, la subvention expirée ou non trouvée, le jeton de rafraîchissement non trouvé, etc.

Dépannage#

Quelques astuces pour dépanner efficacement l'erreur "invalid_grant" :

1. Utilisez toujours un SDK client Logto pour intégrer Logto dans votre application, afin de vous assurer que la demande de subvention est faite à l'endpoint respectif et avec les données correctes.
2. Vérifiez que vos credentials d'application et vos URIs de redirection correspondent aux configurations dans la console d'administration.
3. Évitez de faire des demandes redondantes, en particulier pour les SPAs comme React et Vue, où les composants de page peuvent être rerendered en raison de changements de dépendance. Assurez-vous que les fonctions utilisées pour échanger des codes ou des jetons de rafraîchissement contre des jetons d'accès ne sont pas déclenchées plusieurs fois avec les mêmes paramètres de requête. Ceci est une erreur courante commise par certains de nos utilisateurs. Typiquement, si vous voyez plusieurs requêtes "token" dans votre console de débogage, la première est réussie mais les suivantes échouent, vérifiez leurs paramètres de demande pour voir s'ils utilisent le même "code" ou "refresh token". Rappelez-vous, vous ne pouvez utiliser un code et un token de rafraîchissement qu'UNE FOIS dans les demandes de subvention.
4. Vérifiez les temps d'expiration. Par exemple, si votre jeton de rafraîchissement est expiré (par défaut 14 jours) et que vous recevez l'erreur invalid_grant, vous devriez la gérer correctement en initialisant à nouveau un flux d'inscription d'utilisateur. Si vous utilisez le SDK Logto, vous pouvez appeler la fonction signIn() à nouveau pour rediriger vos utilisateurs vers la page d'inscription.
5. Surveillez les journaux d'audit. Allez dans la console d'administration → Journaux d'audit, trouvez le journal d'erreur associé à l'incident et vérifiez la trace de la pile d'erreur détaillée. Généralement, il y a une raison plus spécifique dans la trace de la pile derrière l'erreur invalid_grant, comme "Grant not found" ou "Refresh token expired".

Remarques de clôture#

L'erreur invalid_grant peut être un défi et une source de confusion pour les débutants, mais avec une compréhension claire des subventions OIDC et une attention aux détails, vous pouvez identifier et résoudre le problème vous-même. Rejoignez nos discussions sur Discord ou GitHub, et faites-nous savoir si ce blog a aidé à clarifier la confusion et à identifier les problèmes que vous rencontrez. L'équipe de développement de Logto est toujours heureuse de vous aider.

Ensemble, construisons une expérience d'authentification fluide et sécurisée pour vos applications bien-aimées.