Guida al concetto di collegamento OAuth

Il tipo di collegamento OAuth supporta due flussi OAuth 2.0 standard di settore: i flussi implicito e codice di autorizzazione. Nel flusso di codice implicito, Google apre l'endpoint di autorizzazione nel browser dell'utente. Una volta eseguito l'accesso, restituisci a Google un token di accesso di lunga durata. Questo token di accesso viene quindi incluso in ogni richiesta inviata dall'Assistente all'Azione.

Il collegamento OAuth è la soluzione consigliata per il collegamento degli account se si applica quanto segue:

  • Disponi di un'implementazione esistente di un server OAuth 2.0 e non puoi estendere l'endpoint di scambio di token per aggiungere il supporto dei protocolli di Google per il collegamento automatico e la creazione di account da un token ID (ad esempio, aggiungi i parametri intent=get e intent=create nelle richieste a questo endpoint).

Per verificare che il collegamento OAuth sia la soluzione giusta per te, consulta la pagina Scegliere il tipo di collegamento dell'account.

Termini chiave

Prima di leggere il funzionamento del collegamento OAuth, leggi attentamente i seguenti termini:

  • user.verificationStatus: una proprietà impostata dal sistema per indicare se la sessione corrente ha un utente verificato.

  • user.accountLinkingStatus: una proprietà impostata dal sistema per indicare se l'utente della sessione corrente ha un'identità collegata.

  • Scena del sistema di collegamento degli account: una scena predefinita che implementa il flusso di conferma per il collegamento dell'account e può essere personalizzata per casi d'uso specifici.

  • Flusso del codice di autorizzazione:durante questo flusso OAuth 2.0, Google apre il tuo endpoint di autorizzazione nel browser dell'utente. Se l'accesso va a buon fine, il servizio crea un codice di autorizzazione e lo restituisce a Google. Google invia questo codice di autorizzazione all'endpoint di scambio di token, che verifica l'autenticità del codice e restituisce un token di accesso e un token di aggiornamento.

    Questo flusso richiede due endpoint:

    • Endpoint di autorizzazione: endpoint responsabile di trovare o ottenere il consenso degli utenti per l'accesso ai dati. Questo endpoint svolge le seguenti operazioni:
      1. Presenta la UI di accesso agli utenti che non hanno ancora eseguito l'accesso.
      2. Registra il consenso all'accesso richiesto sotto forma di codice di autorizzazione di breve durata.
    • Endpoint di scambio di token: questo endpoint viene utilizzato per ottenere stringhe criptate chiamate token che autorizzano l'utente dell'azione ad accedere al servizio. Questo endpoint è responsabile di due tipi di scambi:
      1. Scambia un codice di autorizzazione con un token di aggiornamento di lunga durata e un token di accesso di breve durata. Questo scambio avviene quando l'utente segue il flusso di collegamento dell'account.
      2. Scambia un token di aggiornamento di lunga durata con un token di accesso di breve durata. Questo scambio si verifica quando Google ha bisogno di un nuovo token di accesso perché quello è scaduto.

  • Flusso di codice implicito: durante questo flusso OAuth 2.0, Google apre il tuo endpoint di autorizzazione nel browser dell'utente. Se l'accesso va a buon fine, restituisci a Google un token di accesso di lunga durata. Questo token di accesso viene quindi incluso in ogni richiesta inviata dall'Assistente all'Azione. Questo flusso richiede solo un endpoint di autorizzazione.

  • Token di accesso: un token che autorizza il tuo servizio ad accedere a parti dei dati di un utente. I token di accesso sono associati a ogni singolo utente e non devono essere decifrabili.

  • Token di aggiornamento: token che viene scambiato con un nuovo token di accesso dopo la scadenza di un token di accesso di breve durata.

Come funziona

Questa sezione descrive il flusso generale per il codice di autorizzazione OAuth e i flussi impliciti. La sezione seguente, Flussi di collegamento OAuth, descrive i vari flussi che possono essere eseguiti con OAuth.

Il flusso del codice di autorizzazione può essere riassunto come segue:

  1. L'Azione chiede all'utente se vuole collegare il suo account al tuo servizio.
  2. Dopo che l'utente accetta di collegare gli account, Google apre il tuo endpoint di autorizzazione nel browser dell'utente. Se il flusso per un'Azione fosse avviato su un dispositivo solo vocale, Google trasferirà l'esecuzione su un telefono.
  3. L'utente esegue l'accesso (se non ha già eseguito l'accesso) e concede a Google l'autorizzazione per accedere ai propri dati con la tua API (se non ha già concesso l'autorizzazione).
  4. Il servizio crea un codice di autorizzazione e lo restituisce a Google reindirizzando il browser dell'utente a Google con il codice di autorizzazione allegato alla richiesta.
  5. Google invia il codice di autorizzazione all'endpoint di scambio di token che verifica l'autenticità del codice e restituisce un token di accesso e un token di aggiornamento. Il token di accesso è un token di breve durata che il tuo servizio accetta come credenziali per accedere alle API. Il token di aggiornamento è un token di lunga durata che Google può archiviare e utilizzare per acquisire nuovi token di accesso alla scadenza.
  6. Dopo che l'utente ha completato il flusso di collegamento dell'account, ogni richiesta successiva inviata dall'assistente al webhook di fulfillment contiene un token di accesso.

Il flusso di codice implicito può essere riepilogato come segue:

  1. L'Azione chiede all'utente se vuole collegare il suo account al tuo servizio.
  2. Dopo che l'utente accetta di collegare gli account, Google apre il tuo endpoint di autorizzazione nel browser dell'utente.
  3. L'utente esegue l'accesso (se non ha già eseguito l'accesso) e concede a Google l'autorizzazione per accedere ai propri dati con la tua API (se non ha già concesso l'autorizzazione).
  4. Il servizio crea un token di accesso e lo restituisce a Google reindirizzando il browser dell'utente a Google con il token di accesso associato alla richiesta.
  5. Dopo che l'utente ha completato il flusso di collegamento dell'account, Google chiama le API del tuo servizio e allega il token di accesso a ogni richiesta. Il servizio verifica che il token di accesso conceda a Google l'autorizzazione ad accedere all'API, quindi completa la chiamata API.

Il flusso di base del codice di autorizzazione è il seguente:

  1. L'Azione chiede all'utente se vuole collegare il suo account al tuo servizio.
  2. Dopo che l'utente accetta di collegare gli account, Google apre il tuo endpoint di autorizzazione nel browser dell'utente. Se il flusso per un'Azione fosse avviato su un dispositivo solo vocale, Google trasferirà l'esecuzione su un telefono.
  3. L'utente esegue l'accesso (se non ha già eseguito l'accesso) e concede a Google l'autorizzazione per accedere ai propri dati con la tua API (se non ha già concesso l'autorizzazione).
  4. Il servizio crea un codice di autorizzazione e lo restituisce a Google reindirizzando il browser dell'utente a Google con il codice di autorizzazione di breve durata allegato alla richiesta.
  5. Google invia il codice di autorizzazione all'endpoint di scambio di token che verifica l'autenticità del codice e restituisce un token di accesso e un token di aggiornamento. Il token di accesso è un token di breve durata che il tuo servizio accetta come credenziali per accedere alle API. Il token di aggiornamento è un token di lunga durata che Google può archiviare e utilizzare per acquisire nuovi token di accesso alla scadenza.
  6. Dopo che l'utente ha completato il flusso di collegamento dell'account, ogni richiesta successiva inviata dall'assistente al webhook di fulfillment contiene un token di accesso.

Flussi di collegamento OAuth

Questa sezione esamina i vari flussi che possono verificarsi con il collegamento OAuth.

Ogni flusso contiene i seguenti passaggi comuni dopo che l'utente richiama l'Azione:

Nel flusso precedente, passerai alla scena del sistema di collegamento dell'account e fornisci una motivazione personalizzata. L'assistente chiede all'utente se vuole collegare il suo account al tuo servizio e mostra una schermata con le autorizzazioni richieste. Quando l'utente acconsente, Google lo reindirizza all'endpoint di autorizzazione del tuo servizio nel browser. L'utente accede (o, a seconda della configurazione, crea un nuovo account) e concede all'azione l'autorizzazione ad accedere ai propri dati.

I flussi dopo questo punto differiscono a seconda che tu abbia implementato o meno il flusso implicito o il flusso del codice di autorizzazione. Questi flussi sono descritti nelle sezioni seguenti.

Flusso 1: l'utente accede con un flusso implicito

Dopo che l'utente accede e le sue credenziali sono state verificate, il servizio crea un token di accesso di lunga durata e lo restituisce a Google. A questo punto, l'identità dell'utente nell'Azione è collegata all'account con cui ha eseguito l'accesso e il token di accesso è associato a ogni chiamata API effettuata da Google alle API del tuo servizio.

Flusso 2: L'utente accede con il flusso del codice di autorizzazione

Dopo che l'utente esegue l'accesso e le sue credenziali sono state verificate, il servizio crea un codice di autorizzazione e lo restituisce a Google.

Questo codice di autorizzazione viene inviato all'endpoint di scambio di token, che restituisce sia un token di accesso sia un token di aggiornamento. A questo punto, l'identità dell'utente nell'Azione è collegata all'account con cui ha eseguito l'accesso e ogni richiesta successiva inviata dall'assistente al tuo fulfillment contiene un token di accesso.