Esplorazione dei grant OIDC: comprensione e risoluzione dei problemi dell'errore "invalid_grant"

Background#

Nella nostra community, sentiamo spesso una domanda ricorrente dai nostri utenti: Qual è il problema con l'errore "invalid_grant" in Logto? Come #503.

È una sfida comune e un ostacolo per alcuni dei nostri utenti quando integrano Logto nelle loro applicazioni. Tuttavia, le ragioni dietro a questo errore variano da caso a caso e a volte è difficile da spiegare con un contesto limitato fornito. Pertanto, capire l'esatto concetto di OIDC e imparare il modo di risolvere il problema è essenziale per tutti.

Ora approfondiamo i fondamentali dei grant OIDC.

Spiegazione dei grant OIDC#

Come abbiamo introdotto in un post sul blog in precedenza, OpenID Connect (OIDC) è un protocollo costruito su OAuth 2.0.

Nel contesto di OIDC o OAuth2, un grant è un insieme di permessi concessi dal proprietario della risorsa (di solito l'utente) a un'applicazione client. I grant sono essenziali per l'applicazione client per accedere alle informazioni sull'identità dell'utente e ad altre risorse protette. OIDC definisce diversi tipi di grant, ognuno adatto a uno scenario diverso e al modo in cui un'applicazione ottiene un token di accesso.

Ecco un'analogia per aiutarti a capire meglio i grant OIDC.

Immagina di viaggiare in diversi paesi, e ogni paese richiede un timbro del visto per l'ingresso. In questo scenario, il tuo passaporto funge da tuo account utente, contenente le tue informazioni personali. I grant OIDC sono come i modi in cui fai domanda per un visto per entrare in un paese. Quando un visto ti viene emesso, tu ottieni essenzialmente il "token" per entrare in quel paese.

Allo stesso modo, quando usi un'applicazione, la richiesta di grant è l'azione con cui chiedi al server di autorizzazione di concederti l'accesso. Il server di autorizzazione convalida la tua identità e ti rilascia il "visto" (token di accesso) per accedere all'applicazione.

Tipi di grant OIDC più comunemente usati:#

1. Grant del codice di autorizzazione: È il tipo di grant più comunemente utilizzato in OIDC. Comprende il reindirizzamento dell'utente a un server di autorizzazione, l'ottenimento di un codice di autorizzazione, il reindirizzamento di nuovo all'applicazione e lo scambio del codice per un token di accesso. Pensaci come al processo standard di richiesta di un visto presso l'ambasciata prima di entrare in un paese straniero.
2. Grant del token di aggiornamento: In OIDC, questo tipo di grant consente a un'applicazione client di ottenere un nuovo token di accesso utilizzando un token di aggiornamento che è stato precedentemente emesso. È comunemente usato per estendere la sessione di un utente senza richiedere loro di reinserire le loro credenziali. Immagina che il tuo visto venga con una carta magica che ti permette di prolungare il tuo soggiorno nel paese straniero senza dover passare di nuovo per i controlli doganali.
3. Grant implicito: Questo tipo di grant è usato per le applicazioni basate su browser di vecchia data ed è meno sicuro del Grant del codice di autorizzazione. Restituisce il token di accesso direttamente all'applicazione client. Funziona come un "visto all'arrivo", in quanto non è richiesta alcuna domanda di visto precedente.
4. Grant delle credenziali del client: Adatto per la comunicazione server-to-server, questo tipo di grant consente a un'applicazione client di autenticarsi direttamente con il server di autorizzazione utilizzando le sue credenziali (ID del client e segreto del client). È simile a un agente speciale che mostra un distintivo di lavoro speciale per entrare nel paese senza passare attraverso il processo di domanda di visto.

Modello di oggetto Grant:#

In Logto, il grant è persistente nel database come entità oggetto, contenendo informazioni come l'ID dell'account utente, l'ID dell'applicazione, le risorse e gli ambiti OIDC associati, il tempo di scadenza, e altro ancora. Ogni token di aggiornamento e token di accesso è associato a un oggetto di grant specifico.

Richieste di Grant:#

Richieste HTTP fatte al server di autorizzazione tramite API. Un'applicazione client può inviare richieste di grant all'endpoint del token OIDC per vari scopi, tra cui la domanda di un nuovo grant (ad es., accedendo e ottenendo token di aggiornamento e di accesso), l'aggiornamento dei dettagli del grant (ad es., scambiando un token di aggiornamento per un nuovo token di accesso), o la revoca di un grant (ad es., revocando tutti i token emessi agli utenti collegati e terminando il loro accesso).

Una tipica richiesta di grant del codice di autorizzazione si presenta come segue:

Comprensione dell'errore "invalid_grant"#

Incontrare un errore invalid_grant in OIDC indica tipicamente che il tipo di grant o i dati associati alla richiesta di grant sono non validi o non supportati. Ecco alcune ragioni comuni dietro a questo errore:

1. Tipo di grant errato: L'uso del tipo di grant sbagliato per la tua applicazione può risultare in un errore invalid_grant. Assicurati di utilizzare il tipo di grant appropriato sfruttando le SDK di Logto.
2. URI di reindirizzamento non corrispondenti: Quando si scambia un codice di autorizzazione per i token, l'URI di reindirizzamento utilizzato nella richiesta deve corrispondere a quello utilizzato durante la richiesta di autorizzazione iniziale. Un non corrispondenza può risultare in un errore invalid_grant.
3. Codice di autorizzazione scaduto o consumato: Nel flusso di accesso con codice di autorizzazione, il codice di autorizzazione ha un periodo di vita limitato, e sarà contrassegnato come "consumato" una volta utilizzato per acquisire i token. Tentare di scambiare un codice scaduto o consumato per un token di accesso risulterà in un errore invalid_grant.
4. Token di aggiornamento scaduto o rotato: Quando si scambia un token di aggiornamento per un token di accesso, l'errore invalid_grant si verifica se il token di aggiornamento è già scaduto. Inoltre, per una maggiore sicurezza, Logto abilita la rotazione del token di aggiornamento per impostazione predefinita. Richiedere l'endpoint del token con lo stesso token di aggiornamento una seconda volta viene considerato l'utilizzo di un token di aggiornamento "rotato" e verrà rifiutato.
5. Manca dati obbligatori o intestazioni di richiesta: Quando si compone una richiesta di grant, i parametri obbligatori e le intestazioni di richiesta devono essere forniti per il dato tipo di grant. Ad esempio, l'ID del client deve essere fornito in tutte le richieste di grant, e l'ID del client e il segreto del client devono essere forniti per il Grant delle credenziali del client. Questo rischio può essere mitigato anche sfruttando le SDK di Logto.
6. Altre ragioni: Quest'errore può verificarsi anche a causa di motivi come l'errata corrispondenza delle credenziali del client, il grant scaduto o non trovato, il token di aggiornamento non trovato, ecc.

Risoluzione dei problemi#

Alcuni consigli per risolvere efficacemente l'errore "invalid_grant":

1. Utilizza sempre un SDK client Logto per integrare Logto nella tua applicazione, in modo da assicurarti che la richiesta di grant venga fatta all'endpoint rispettivo e con dati corretti.
2. Verifica che le tue credenziali dell'app e gli URI di reindirizzamento corrispondano alle configurazioni nella Console di amministrazione.
3. Evita di fare richieste ridondanti, soprattutto per SPA come React e Vue, dove i componenti delle pagine possono essere ri-renderizzati a causa di cambiamenti delle dipendenze. Assicurati che le funzioni utilizzate per scambiare codici o token di aggiornamento per i token di accesso non vengano attivate più volte con gli stessi parametri di richiesta. Questo è un errore comune fatto da alcuni dei nostri utenti. Tipicamente se vedi più richieste di "token" nella tua console di debug, la prima è andata a buon fine ma tutte le successive sono fallite, controlla i loro parametri di richiesta per vedere se stanno utilizzando lo stesso "codice" o "token di aggiornamento". Ricorda, puoi usare una sola volta un codice e un token di aggiornamento nelle richieste di grant.
4. Controlla i tempi di scadenza. Ad esempio, se il tuo token di aggiornamento è scaduto (di solito 14 giorni) e ricevi l'errore invalid_grant, dovresti gestirlo correttamente reinizializzando il flusso di accesso dell'utente. Se stai utilizzando l'SDK Logto, puoi chiamare la funzione signIn() ancora una volta per reindirizzare i tuoi utenti alla pagina di accesso.
5. Monitora i log di audit. Vai alla Console di amministrazione → Log di audit, trova il log di errore associato all'incidente e controlla la traccia dello stack di errore dettagliata. Di solito, c'è una ragione più specifica nella traccia dello stack dietro all'errore invalid_grant, come "Grant non trovato" o "Token di aggiornamento scaduto".

Considerazioni finali#

L'errore invalid_grant può essere impegnativo e confuso per i principianti, ma con una chiara comprensione dei grant OIDC e un'attenzione ai dettagli, puoi identificare e affrontare da solo il problema. Partecipa alle nostre discussioni su Discord o GitHub, e facci sapere se questo blog ha aiutato a chiarire la confusione e a identificare i problemi che stai affrontando. Il team di sviluppo di Logto è sempre felice di assisterti.

Insieme, costruiamo un'esperienza di autenticazione senza problemi e sicura per le tue applicazioni preferite.