Collegamento dell'account con OAuth

Il tipo di collegamento OAuth supporta due flussi OAuth 2.0 standard di settore: i flussi di codice implicito e di autorizzazione.

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Implementare il collegamento degli account OAuth

Configura il progetto

Per configurare il progetto per l'utilizzo del collegamento OAuth, segui questi passaggi:

1. Apri la console di Actions e seleziona il progetto che vuoi utilizzare.
2. Fai clic sulla scheda Sviluppo e scegli Collegamento dell'account.
3. Attiva l'opzione Collegamento dell'account.
4. Nella sezione Creazione account, seleziona No, voglio consentire la creazione di account solo sul mio sito web.

5. In Tipo di collegamento, seleziona OAuth e Implicito.

   

6. In Informazioni sul cliente:

   • Assegna un valore al Client-ID emesso dalle tue Azioni a Google per identificare le richieste provenienti da Google.
   • Inserisci gli URL per gli endpoint di autorizzazione e di scambio dei token.

6. Fai clic su Salva.

Implementare il server OAuth

Per supportare il flusso implicito OAuth 2.0, il servizio effettua un'autorizzazione endpoint disponibile tramite HTTPS. Questo endpoint è responsabile dell'autenticazione e ottenere il consenso degli utenti per l'accesso ai dati. Endpoint di autorizzazione presenta una UI di accesso agli utenti che non hanno ancora effettuato l'accesso e registra acconsentire all'accesso richiesto.

Se l'Azione deve chiamare una delle API autorizzate del tuo servizio, Google utilizza per ottenere l'autorizzazione degli utenti per chiamare queste API sui loro per conto tuo.

Una tipica sessione di flusso implicito OAuth 2.0 avviata da Google ha flusso seguente:

1. Google apre il tuo endpoint di autorizzazione nel browser dell'utente. La l'utente accede se non l'ha già fatto e concede a Google l'autorizzazione ad accedere i propri dati con l'API, se non hanno già concesso l'autorizzazione.
2. Il servizio crea un token di accesso e lo restituisce a Google reindirizzando il browser dell'utente a Google tramite il token di accesso in allegato alla richiesta.
3. Google chiama le API del tuo servizio e collega il token di accesso con per ogni richiesta. Il tuo servizio verifica che il token di accesso conceda a Google l'autorizzazione ad accedere all'API e quindi completa la chiamata API.

Gestire le richieste di autorizzazione

Se l'azione deve eseguire il collegamento dell'account tramite un flusso implicito OAuth 2.0, Google invia l'utente al tuo endpoint di autorizzazione con una richiesta che include i seguenti parametri:

Ad esempio, se l'endpoint di autorizzazione è disponibile all'indirizzo https://myservice.example.com/auth, una richiesta potrebbe avere il seguente aspetto:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

Affinché l'endpoint di autorizzazione possa gestire le richieste di accesso, segui questi passaggi:

1. Verifica i valori client_id e redirect_uri per evitare di concedere l'accesso ad app client indesiderate o configurate in modo errato:

   • Verifica che il client_id corrisponda all'ID cliente che hai indicato assegnati a Google.
   • Verifica che l'URL specificato dal redirect_uri ha il seguente formato:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID è l'ID trovato nella pagina Impostazioni progetto della console di Actions.

2. Verifica se l'utente ha eseguito l'accesso al tuo servizio. Se l'utente non ha firmato completa la procedura di accesso o registrazione al servizio.

3. Genera un token di accesso che Google utilizzerà per accedere alla tua API. La il token di accesso può essere qualsiasi valore di stringa, ma deve rappresentare in modo univoco l'utente e il client a cui è destinato il token e non deve essere prevedibile.

4. Invia una risposta HTTP che reindirizza il browser dell'utente all'URL specificato dal parametro redirect_uri. Includi tutti i seguenti parametri nel frammento URL:

   • access_token: il token di accesso che hai appena generato
   • token_type: la stringa bearer
   • state: il valore dello stato non modificato dell'originale richiesta Di seguito è riportato un esempio dell'URL risultante:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Il gestore del reindirizzamento OAuth 2.0 di Google riceverà il token di accesso e confermerà che il valore state sia rimasto invariato. Dopo che Google ha ottenuto di accesso al tuo servizio, Google lo collegherà alle chiamate successive all'Azione nell'ambito di AppRequest.

Progetta l'interfaccia utente vocale per il flusso di autenticazione

Controlla se l'utente è verificato e avvia la procedura di collegamento dell'account

1. Apri il progetto Actions Builder nella console di Actions.
2. Crea una nuova scena per avviare il collegamento dell'account nell'Azione:
   1. Fai clic su Scene.
   2. Fai clic sull'icona Aggiungi (+) per aggiungere una nuova scena.
3. Nella scena appena creata, fai clic sull'icona Aggiungi add in Condizioni.
4. Aggiungi una condizione che verifichi se l'utente associato alla conversazione è un utente verificato. Se il controllo ha esito negativo, l'Azione non può eseguire il collegamento dell'account durante la conversazione e dovrebbe fornire l'accesso a funzionalità che non richiedono il collegamento dell'account.
   1. Nel campo Enter new expression in Condizione, inserisci la seguente logica: user.verificationStatus != "VERIFIED"
   2. In Transizione, seleziona una scena che non richieda il collegamento dell'account o che sia il punto di accesso alle funzionalità solo per gli ospiti.

1. Fai clic sull'icona Aggiungi add in Condizioni.
2. Aggiungi una condizione per attivare un flusso di collegamento dell'account se all'utente non è associata un'identità.
   1. Nel campo Enter new expression in Condizione, inserisci la seguente logica: user.verificationStatus == "VERIFIED"
   2. In Transizione, seleziona la scena di sistema Collegamento dell'account.
   3. Fai clic su Salva.

Dopo il salvataggio, al progetto viene aggiunta una nuova scena di sistema di collegamento dell'account denominata <SceneName>_AccountLinking.

Personalizzare la scena di collegamento dell'account

1. In Scene, seleziona la scena di sistema per il collegamento dell'account.
2. Fai clic su Invia richiesta e aggiungi una breve frase per descrivere all'utente il motivo per cui l'Azione deve accedere alla sua identità (ad esempio "Per salvare le tue preferenze").
3. Fai clic su Salva.

1. In Condizioni, fai clic su Se l'utente completa correttamente il collegamento dell'account.
2. Configura la procedura da seguire nel caso in cui l'utente accetti di collegare il suo account. Ad esempio, chiama il webhook per elaborare qualsiasi logica di business personalizzata richiesta e tornare alla scena di origine.
3. Fai clic su Salva.

1. In Condizioni, fai clic su Se l'utente annulla o ignora il collegamento dell'account.
2. Configura la procedura da seguire nel flusso se l'utente non accetta di collegare il proprio account. Ad esempio, invia un messaggio di conferma e reindirizza a scene che offrono funzionalità che non richiedono il collegamento dell'account.
3. Fai clic su Salva.

1. In Condizioni, fai clic su Se si verifica un errore di sistema o di rete.
2. Configura la procedura da seguire se non è possibile completare il flusso di collegamento dell'account a causa di errori di sistema o di rete. Ad esempio, invia un messaggio di conferma e reindirizza a scene che offrono funzionalità che non richiedono il collegamento dell'account.
3. Fai clic su Salva.

Gestire le richieste di accesso ai dati

Se la richiesta dell'assistente contiene un token di accesso, verifica innanzitutto che il token di accesso sia valido (e non scaduto), quindi recupera l'account utente associato dal database.