Het verkennen van OIDC-grants: begrijpen en oplossen van de "invalid_grant"-fout

Achtergrond#

In onze gemeenschap horen we vaak een terugkerende vraag van onze gebruikers: Wat is het probleem met de "invalid_grant"-fout in Logto? Zoals #503

Het is een veelvoorkomende uitdaging en een blokkade voor sommige van onze gebruikers bij het integreren van Logto in hun eigen applicaties. De redenen achter deze fout variëren echter van geval tot geval, en soms is het moeilijk uit te leggen met beperkte context. Daarom is het essentieel dat iedereen het exacte OIDC-concept begrijpt en de manier leert om het probleem op te lossen.

Laten we nu de basisprincipes van OIDC-grants verkennen.

OIDC-grants uitgelegd#

Zoals we eerder in een blogpost hebben geïntroduceerd, is OpenID Connect (OIDC) een protocol dat bovenop OAuth 2.0 is gebouwd.

In de context van OIDC of OAuth2 is een grant een reeks machtigingen die door de resource-eigenaar (meestal de gebruiker) aan een clienttoepassing worden verleend. Grants zijn essentieel voor de clienttoepassing om toegang te krijgen tot de identiteitsinformatie van de gebruiker en andere beschermde bronnen. OIDC definieert verschillende granttypes, die elk geschikt zijn voor een ander scenario en de manier waarop een applicatie een toegangstoken krijgt.

Hier is een analogie om je te helpen OIDC-grants beter te begrijpen.

Stel je voor dat je naar verschillende landen reist en elk land een visumstempel voor binnenkomst eist. In dit scenario dient je paspoort als je gebruikersaccount, met je persoonlijke informatie. OIDC-grants zijn als de manieren waarop je een visum aanvraagt om een land binnen te komen. Wanneer een visum aan je wordt verstrekt, verkrijg je in feite het "token" om dat land binnen te gaan.

Evenzo, bij het gebruik van een applicatie, is de grantaanvraag de handeling die je de autorisatieserver vraagt om je toegang te verlenen. De autorisatieserver valideert je identiteit en verstrekt je het "visum" (toegangstoken) om je aan te melden bij de applicatie.

Veelgebruikte OIDC-granttypes:#

1. Authorization Code Grant: Dit is het meest gebruikte granttype in OIDC. Het omvat het omleiden van de gebruiker naar een autorisatieserver, het verkrijgen van een autorisatiecode, terugsturen naar de applicatie en het inwisselen van de code voor een toegangstoken. Zie het als het standaardproces van het aanvragen van een visum bij de ambassade voordat je een vreemd land binnengaat.
2. Refresh Token Grant: In OIDC stelt dit granttype een clienttoepassing in staat om een nieuw toegangstoken te verkrijgen met behulp van een eerder uitgegeven refresh-token. Het wordt vaak gebruikt om de sessie van een gebruiker te verlengen zonder dat deze zijn/haar inloggegevens opnieuw moet invoeren. Stel je voor dat je visum wordt geleverd met een magische kaart die je verblijf in het vreemde land verlengt zonder opnieuw door de douane te hoeven gaan.
3. Implicit Grant: Dit granttype wordt gebruikt voor oudere browsergebaseerde applicaties en is minder veilig dan de Authorization Code Grant. Het geeft het toegangstoken rechtstreeks terug aan de clienttoepassing. Het werkt als een "visum bij aankomst", omdat er geen eerdere visumaanvraag nodig is.
4. Client Credentials Grant: Geschikt voor communicatie van server tot server, stelt dit granttype een clienttoepassing in staat om rechtstreeks te authenticeren bij de autorisatieserver met behulp van zijn referenties (client-ID en clientgeheim). Het is als een speciale agent die een speciale werkbadge laat zien om het land binnen te komen zonder door het visumaanvraagproces te gaan.

Grant-objectmodel:#

In Logto wordt een grant als objectentiteit in de database opgeslagen, met informatie zoals gebruikersaccount-ID, applicatie-ID, geassocieerde OIDC-bronnen en -scopes, vervaltijd, en meer. Elk refresh-token en toegangstoken is geassocieerd met een specifiek grantobject.

Grantverzoeken:#

HTTP-verzoeken gedaan aan de autorisatieserver via API's. Een clienttoepassing kan grantverzoeken naar het OIDC-token-eindpunt sturen voor verschillende doeleinden, waaronder het aanvragen van een nieuwe grant (bijv. inloggen en verkrijgen van refresh- en toegangstokens), het bijwerken van grantdetails (bijv. inwisselen van een refresh-token voor een nieuw toegangstoken) of het intrekken van een grant (bijv. intrekken van alle tokens die aan ingelogde gebruikers zijn uitgegeven en het beëindigen van hun toegang).

Een typisch authorization code grantverzoek ziet er als volgt uit:

Begrijpen van de "invalid_grant"-fout#

Het tegenkomen van een invalid_grant-fout in OIDC geeft meestal aan dat het granttype of de gegevens die bij het grantverzoek horen ongeldig of niet ondersteund zijn. Hier zijn enkele veelvoorkomende redenen achter deze fout:

1. Onjuist granttype: Het gebruik van het verkeerde granttype voor je applicatie kan resulteren in een invalid_grant-fout. Zorg ervoor dat je het juiste granttype gebruikt door gebruik te maken van Logto SDK's.
2. Niet-overeenkomende redirect-URI's: Bij het inwisselen van een autorisatiecode voor tokens moet de redirect-URI die in het verzoek wordt gebruikt, overeenkomen met die welke tijdens het initiële autorisatieverzoek is gebruikt. Een afwijking kan resulteren in een invalid_grant-fout.
3. Verlopen of verbruikte autorisatiecode: In de Authorization Code-sign-in flow heeft de autorisatiecode een beperkte levensduur en wordt deze gemarkeerd als "verbruikt" zodra deze wordt gebruikt om tokens te verkrijgen. Pogingen om een verlopen of verbruikte code om te wisselen voor een toegangstoken resulteren in een invalid_grant-fout.
4. Verlopen of geroteerd refresh-token: Bij het inwisselen van een refresh-token voor een toegangstoken, treedt de invalid_grant-fout op als het refresh-token al is verlopen. Bovendien activeert Logto standaard refresh-tokenrotatie voor verbeterde beveiliging. Het aanvragen van het token-eindpunt met hetzelfde refresh-token een tweede keer wordt beschouwd als het gebruik van een "geroteerd" refresh-token en wordt afgewezen.
5. Ontbrekende verplichte gegevens of aanvraagheaders: Bij het samenstellen van een grantverzoek moeten de verplichte parameters en aanvraagheaders voor het gegeven granttype worden verstrekt. Bijvoorbeeld, de client-ID moet in alle grantverzoeken worden verstrekt, en client-ID en clientgeheim moeten worden verstrekt voor Client Credentials Grant. Dit risico kan ook worden verminderd door gebruik te maken van Logto SDK's.
6. Andere redenen: Deze fout kan ook optreden vanwege redenen zoals clientreferentiemismatch, grant verlopen of niet gevonden, refresh-token niet gevonden, etc.

Problemen oplossen#

Enkele tips om de "invalid_grant"-fout effectief op te lossen:

1. Gebruik altijd een Logto-client-SDK om Logto in je applicatie te integreren, om ervoor te zorgen dat de grantverzoeken worden gedaan aan het respectieve eindpunt en met de juiste gegevens.
2. Verifieer dat je appreferenties en redirect-URI's overeenkomen met de configuraties in de beheerdersconsole.
3. Vermijd het maken van overbodige verzoeken, vooral voor SPAs zoals React en Vue, waar pagina-componenten opnieuw kunnen worden gerenderd door veranderingen in afhankelijkheden. Zorg ervoor dat functies die worden gebruikt om codes of refresh-tokens in te wisselen voor toegangstokens niet meerdere keren worden geactiveerd met dezelfde aanvraagparameters. Dit is een veelgemaakte fout door sommige van onze gebruikers. Meestal, als je meerdere "token"-verzoeken in je debugconsole kunt zien, is het eerste succesvol, maar de daaropvolgende mislukken allemaal. Controleer hun aanvraagparameters om te zien of ze dezelfde "code" of "refresh-token" gebruiken. Vergeet niet dat je een code en refresh-token slechts ÉÉN keer kunt gebruiken in grantverzoeken.
4. Controleer de vervaltijden. Bijvoorbeeld, als je refresh-token is verlopen (standaard 14 dagen) en je ontvangt de invalid_grant-fout, dien je dit op de juiste manier af te handelen door opnieuw een gebruikersinlogstroom te starten. Als je de Logto SDK gebruikt, kun je de functie signIn() opnieuw oproepen om je gebruikers terug te leiden naar de inlogpagina.
5. Monitor auditlogs. Ga naar Beheerdersconsole → Auditlogs, vind het foutlogboek dat aan het incident is gekoppeld en controleer de gedetailleerde foutstacktrace. Meestal is er een specifiekere reden in de stacktrace achter de invalid_grant-fout, zoals "Grant niet gevonden" of "Refresh-token verlopen".

Afsluitende opmerkingen#

De invalid_grant-fout kan uitdagend en verwarrend zijn voor beginners, maar met een duidelijk begrip van OIDC-grants en aandacht voor detail, kun je het probleem zelf identificeren en oplossen. Doe mee aan onze discussies op Discord of GitHub en laat ons weten of deze blog heeft geholpen om verwarring te verduidelijken en de problemen te identificeren waarmee je wordt geconfronteerd. Het Logto-ontwikkelingsteam staat altijd klaar om je te helpen.

Laten we samen een naadloze en veilige authenticatie-ervaring bouwen voor je geliefde applicaties.