Guida al concetto di collegamento "semplificato" di Accedi con Google basato su OAuth

Il tipo di collegamento "Semplificato" Accedi con Google basato su OAuth aggiunge Accedi con Google oltre al collegamento dell'account basato su OAuth. Se utilizzi questo tipo di collegamento nell'Azione, il flusso inizia con Accedi con Google, che ti consente di verificare se le informazioni del profilo Google dell'utente sono presenti nel tuo sistema. In caso contrario, viene avviato un flusso OAuth standard. Se fornisci una combinazione di questi due tipi di collegamento, gli utenti possono collegare la propria identità nell'Azione a un Account Google o non Google. Se vogliono, possono anche creare un nuovo account con le informazioni del loro profilo Google.

Il collegamento semplificato è la soluzione consigliata per il collegamento degli account se si applica una delle seguenti condizioni:

  • L'Azione riguarda più piattaforme (ad esempio, se l'Azione funziona con un'app per Android).
  • Disponi di un sistema di autenticazione esistente e vuoi consentire agli utenti di collegare le loro identità ad account non Google. Ad esempio, se offri un programma fedeltà e vuoi assicurarti che l'utente non perda i punti accumulati sul suo account esistente.

Per verificare che il collegamento semplificato 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 semplificato, familiarizza con i seguenti termini:

  • Token ID Google: un'asserzione firmata dell'identità di un utente contenente le informazioni di base del profilo Google (nome, indirizzo email e immagine del profilo dell'utente). Un token ID Google è un token web JSON (JWT). Di seguito è riportato un esempio di token decodificato:
{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}

  • 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: un flusso OAuth 2.0 che puoi implementare con il collegamento semplificato. Questo flusso richiede due endpoint:

    • Endpoint di autorizzazione: l'endpoint che presenta la UI di accesso agli utenti che non hanno ancora effettuato l'accesso. Registra il consenso all'accesso richiesto sotto forma di codice di autorizzazione di breve durata.
    • Endpoint di scambio di token: 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: un flusso OAuth 2.0 che puoi implementare con il collegamento semplificato. Questo flusso richiede solo un endpoint di autorizzazione. Durante questo flusso, Google apre l'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 è ora incluso in ogni richiesta inviata dall'Assistente all'Azione.

  • 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.

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

Prerequisiti

Per utilizzare il tipo di collegamento semplificato, devi disporre di:

  • Un server OAuth 2.0

  • Un endpoint di scambio di token

    L'endpoint di scambio di token deve essere esteso in modo da aggiungere il supporto dei protocolli di Google per il collegamento automatico e la creazione di account da un token ID (ovvero aggiungendo i parametri intent=get e intent=create alle richieste a questo endpoint).

Come funziona

Questa sezione descrive il flusso generale per il collegamento semplificato. La sezione seguente, Flussi di collegamento semplificati, descrive i vari flussi che possono verificarsi in base a a) l'attivazione o la disattivazione della creazione di account tramite voce e b) l'utilizzo del flusso implicito o del codice di autorizzazione.

Il flusso di base è il seguente:

  1. L'Azione chiede all'utente il consenso per accedere al proprio profilo Google.
  2. Dopo che l'utente ha dato il consenso, l'Azione riceve un token ID Google contenente informazioni del profilo Google dell'utente.
  3. Per leggere i contenuti del profilo, devi convalidare e decodificare il token.
  4. L'Azione utilizza questo token per verificare se nel sistema sono presenti informazioni del profilo Google dell'utente.
    1. In questo caso, l'utente ha già eseguito l'accesso al tuo sistema con il proprio Account Google e l'assistente collega la sua identità al suo Account Google. L'utente può continuare la conversazione con l'assistente con il proprio account collegato.
    2. In caso contrario, vedi il passaggio 5.
  5. L'utente può a) creare un nuovo account con le informazioni del suo profilo Google o b) accedere al sistema con un altro account. Le opzioni a disposizione dell'utente variano a seconda che tu abbia attivato o disattivato la creazione di account tramite comandi vocali. Se l'utente sceglie di accedere al tuo sistema con un altro account, viene avviato il flusso OAuth standard.
  6. Dopo che l'utente ha creato un nuovo account o ha eseguito l'accesso con un altro provider, il servizio restituisce un token di accesso a Google. Se utilizzi il flusso del codice di autorizzazione, il servizio restituisce anche un token di aggiornamento.
  7. Ora l'utente può continuare la conversazione con l'assistente con il proprio account collegato.

Flussi di collegamento semplificati

Questa sezione esamina i vari flussi che possono essere eseguiti con il collegamento semplificato. Questi diagrammi illustrano i flussi che si verificano con il flusso del codice di autorizzazione anziché con il flusso di codice implicito e presuppongono che tu stia utilizzando Actions Builder.

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. La scena chiede all'utente l'autorizzazione ad accedere alle informazioni del suo profilo Google. Dopo che l'utente ha dato il consenso, l'assistente invia una richiesta contenente le informazioni del profilo per user@gmail.com.

Dopo questo punto, i flussi variano a seconda che tu configuri o meno il collegamento degli account con la voce e che le informazioni dell'utente esistano già nel tuo sistema. Ciascuno di questi flussi è descritto nelle sezioni seguenti.

Flussi con creazione di account vocale abilitata

Questa sezione descrive in dettaglio i flussi di collegamento degli account che possono verificarsi se attivi la creazione di account tramite comandi vocali.

Flusso 1: le informazioni dell'utente sono presenti nel tuo sistema

In questo caso, l'utente rappresentato da user@gmail.com esiste nel backend, quindi l'endpoint di scambio di token restituisce un token per l'utente. L'identità dell'utente nell'Azione è ora collegata al suo Account Google. La richiesta originale dell'utente ("Ordina il mio solito") corrisponde all'intent dell'utente order_drink. Il webhook gestisce l'evasione dell'intent con corrispondenza ed esegue query sul database per l'ordine abituale di user@gmail.com. L'utente può quindi continuare la conversazione con l'assistente.

Flusso 2: le informazioni dell'utente non esistono e l'utente crea l'account

Poiché hai abilitato la creazione di account tramite comandi vocali e user@gmail.com non esiste nel tuo backend, l'assistente chiede all'utente se vuole eseguire una delle seguenti operazioni:

a) Creare un nuovo account sul tuo sistema utilizzando le informazioni del profilo Google dell'utente, tramite comandi vocali.

b) Accedi al sistema con un altro account.

In questo caso, l'utente sceglie di creare un nuovo account tramite comandi vocali. Google chiama l'endpoint di scambio di token del tuo servizio con una richiesta di creazione di un account. Questa richiesta contiene il token ID Google, che include i componenti necessari per creare un nuovo account. Puoi quindi utilizzare le informazioni di questo token (nome e indirizzo email dell'utente) per creare un account per l'utente.

Dopo la creazione dell'account, il servizio restituisce un token di accesso e un token di aggiornamento per l'account appena creato. L'identità dell'utente nell'Azione è ora collegata al suo Account Google. La richiesta originale dell'utente ("Ordina il mio solito") corrisponde all'intent dell'utente. order_drink. Il webhook gestisce l'evasione dell'intent con corrispondenze ed esegue query sul database per l'ordine abituale di user@gmail.com, che non esiste ancora perché l'utente è nuovo. L'Azione può quindi chiedere all'utente cosa vuole ordinare.

Flusso 3: le informazioni dell'utente non esistono e l'utente accede con un account diverso

Hai attivato la creazione di account tramite comandi vocali, quindi l'assistente chiede all'utente se vuole eseguire una delle seguenti operazioni:

a) Creare un nuovo account sul tuo sistema utilizzando le informazioni del profilo Google dell'utente, tramite comandi vocali.

b) Accedi al sistema con un altro account.

In questo caso, l'utente sceglie di accedere con un altro account, avviando così il flusso OAuth standard. Se il flusso è iniziato su un dispositivo solo vocale, Google trasferisce l'esecuzione su un telefono. Google apre quindi l'endpoint di autorizzazione nel browser dell'utente e, a seconda della configurazione, l'utente può scegliere se a) accedere al servizio con un account esistente che non utilizza Accedi con Google o b) creare un nuovo account utilizzando un altro provider. Per ulteriori informazioni sul flusso OAuth, consulta la guida al concetto di collegamento OAuth.

Dopo aver verificato le credenziali dell'utente, il servizio restituisce a Google un token di accesso e un token di aggiornamento. L'identità dell'utente nell'Azione è ora collegata a un account non Google. La richiesta originale dell'utente ("Ordina il mio solito") corrisponde all'intent dell'utente order_drink.. Quindi, il webhook gestisce il completamento dell'intent corrispondente ed esegue query sul database per l'ordine abituale di user@gmail.com, che non esiste ancora perché l'utente è nuovo. L'Azione può quindi chiedere all'utente cosa vuole ordinare o di configurare l'ordine abituale.

Flusso con creazione dell'account vocale disattivata

Questa sezione descrive in dettaglio il flusso di collegamento degli account che può verificarsi se disattivi la creazione degli account tramite comandi vocali.

Flusso 4: le informazioni dell'utente non esistono

Non hai abilitato la creazione di account tramite comandi vocali e l'utente non esiste nel backend, pertanto inizia il flusso OAuth standard. L'assistente apre il tuo endpoint di autorizzazione nel browser dell'utente (se il flusso è iniziato su un dispositivo solo vocale, Google trasferisce l'esecuzione su un dispositivo dotato di uno schermo). L'utente può scegliere di a) accedere con un altro fornitore, se si è registrato al servizio con un altro account o b) creare un nuovo account con un altro fornitore. Per ulteriori informazioni sul flusso OAuth, consulta la guida al concetto di collegamento OAuth.

Dopo aver verificato le credenziali dell'utente, il servizio restituisce a Google un token di accesso e un token di aggiornamento. L'identità dell'utente nell'Azione è ora collegata a un Account non Google. La richiesta originale dell'utente ("Ordina il mio solito") corrisponde all'intent dell'utente order_drink.. Quindi, il webhook gestisce il completamento dell'intent corrispondente ed esegue query sul database per l'ordine abituale di user@gmail.com, che non esiste ancora perché l'utente è nuovo. L'Azione può quindi chiedere all'utente di configurare l'ordine abituale.