Panoramica

Scegliere il percorso di integrazione

Seleziona il percorso più adatto alle tue esigenze:

Percorso	Ideale per	Scopri di più
Universal Commerce Protocol (UCP)	Commercianti e rivenditori.	Documenti UCP
Collegamento degli account standard	Smart Home, TV e YouTube.	Documenti

Il collegamento degli account consente ai titolari di Account Google di connettersi ai tuoi servizi in modo rapido, semplice e sicuro. Puoi scegliere di implementare il collegamento dell'Account Google per condividere i dati di un utente dalla tua piattaforma con app e servizi Google.

Il protocollo OAuth 2.0 sicuro ti consente di collegare in modo sicuro l'Account Google di un utente al suo account sulla tua piattaforma, concedendo così alle applicazioni e ai dispositivi Google l'accesso ai tuoi servizi.

Gli utenti possono collegare o scollegare i propri account e, facoltativamente, creare un nuovo account sulla tua piattaforma con il collegamento dell'Account Google.

Casi d'uso

Alcuni motivi per implementare il collegamento dell'Account Google sono:

• Condividere i dati di un utente dalla tua piattaforma con app e servizi Google.

• Esegui l'integrazione con Google Shopping e le piattaforme AI (Ricerca, Gemini) utilizzando l'Universal Commerce Protocol (UCP).

• Riproduci i tuoi video e film utilizzando Google TV.

• Gestire e controllare i dispositivi connessi Google Smart Home utilizzando l'app Google Home e l'Assistente Google, "Hey Google, accendi le luci".

• Crea esperienze e funzionalità personalizzate dell'Assistente Google con Azioni conversazionali, "Hey Google, ordina il mio solito da Starbucks".

• Consenti agli utenti di guadagnare premi guardando live streaming idonei su YouTube dopo aver collegato il proprio Account Google a un account partner per i premi.

• Precompilare i nuovi account durante la registrazione con dati condivisi consensualmente da un profilo dell'Account Google.

Funzionalità supportate

Queste funzionalità sono supportate dal collegamento degli Account Google:

• Condividi rapidamente i tuoi dati utilizzando il flusso OAuth Linking implicito.

• Fornisci una sicurezza migliorata con il flusso del codice di autorizzazione per il collegamento OAuth.

• Accedi agli utenti esistenti o registra nuovi utenti verificati da Google sulla tua piattaforma, ottieni il loro consenso e condividi in modo sicuro i dati con il collegamento semplificato.

• Riduci le difficoltà con App Flip. Da un'app Google attendibile, un tocco apre in modo sicuro l'app Android o iOS verificata e un tocco concede il consenso dell'utente e collega gli account.

• Migliora la privacy degli utenti definendo ambiti personalizzati per condividere solo i dati necessari, aumenta la fiducia degli utenti definendo chiaramente come vengono utilizzati i loro dati.

• L'accesso ai dati e ai servizi ospitati sulla tua piattaforma può essere revocato scollegando gli account. L'implementazione di un endpoint di revoca dei token facoltativo ti consente di rimanere sincronizzato con gli eventi avviati da Google, mentre la protezione cross-account (RISC) ti consente di comunicare a Google eventuali eventi di scollegamento che si verificano sulla tua piattaforma.

Flussi di collegamento degli account

Esistono tre flussi di collegamento dell'Account Google, tutti basati su OAuth e che richiedono la gestione o il controllo di endpoint di autorizzazione e scambio di token conformi a OAuth 2.0.

Durante la procedura di collegamento, emetti token di accesso per singoli Account Google dopo aver ottenuto il consenso dei titolari degli account per collegare i loro account e condividere i dati.

Collegamento OAuth ("OAuth web")

Si tratta del flusso OAuth di base che indirizza gli utenti al tuo sito web per il collegamento. L'utente viene reindirizzato al tuo sito web per accedere al proprio account. Una volta effettuato l'accesso, l'utente acconsente alla condivisione dei propri dati sul tuo servizio con Google. A questo punto, l'Account Google dell'utente e il tuo servizio sono collegati.

Il collegamento OAuth supporta i flussi OAuth impliciti e del codice di autorizzazione. Il tuo servizio deve ospitare un endpoint di autorizzazione conforme a OAuth 2.0 per il flusso implicito e deve esporre sia un endpoint di autorizzazione sia uno di scambio di token quando utilizzi il flusso del codice di autorizzazione.

Figura 1. Collegamento dell'account sullo smartphone di un utente con OAuth web

Collegamento basato su OAuth ('App Flip')

Un flusso OAuth che indirizza gli utenti alla tua app per il collegamento.

Il collegamento tramite App Flip basato su OAuth guida gli utenti mentre si spostano tra le tue app mobile Android o iOS verificate e la piattaforma di Google per esaminare le modifiche proposte all'accesso ai dati e dare il consenso per collegare il proprio account sulla tua piattaforma al proprio Account Google. Per attivare App Flip, il tuo servizio deve supportare il collegamento OAuth o il collegamento di Accedi con Google basato su OAuth utilizzando il flusso del codice di autorizzazione.

Il trasferimento delle app è supportato sia su Android che su iOS.

Come funziona:

L'app Google controlla se la tua app è installata sul dispositivo dell'utente:

• Se l'app viene trovata, l'utente viene reindirizzato alla tua app. La tua app raccoglie il consenso dell'utente per collegare l'account a Google, quindi torna alla piattaforma Google.
• Se l'app non viene trovata o si verifica un errore durante il processo di app flip, l'utente viene reindirizzato al flusso OAuth semplificato o web.

Figura 2. Collegamento dell'account sullo smartphone di un utente con App Flip

Collegamento semplificato basato su OAuth ("Semplificato")

Il collegamento semplificato basato su OAuth di Accedi con Google aggiunge Accedi con Google in aggiunta al collegamento OAuth, consentendo agli utenti di completare la procedura di collegamento senza uscire dalla piattaforma Google, riducendo così gli attriti e gli abbandoni. Il collegamento semplificato basato su OAuth offre la migliore esperienza utente con accesso, creazione e collegamento dell'account senza interruzioni combinando Accedi con Google con il collegamento OAuth. Il tuo servizio deve supportare endpoint di autorizzazione e scambio di token conformi a OAuth 2.0. Inoltre, l'endpoint di scambio di token deve supportare le asserzioni JSON Web Token (JWT) e implementare gli intent check, create e get.

Come funziona:

Google afferma che l'account utente e ti trasmette queste informazioni:

• Se nel tuo database esiste un account per l'utente, quest'ultimo collega correttamente il suo Account Google al suo account sul tuo servizio.
• Se nel tuo database non esiste un account per l'utente, quest'ultimo può creare un nuovo account di terze parti con le informazioni fornite da Google : email, nome e immagine del profilo oppure scegliere di accedere e collegarsi con un altro indirizzo email (in questo caso, dovrà accedere al tuo servizio utilizzando OAuth web).

Figura 3. Collegamento dell'account sullo smartphone di un utente con il collegamento semplificato

Quale flusso dovresti utilizzare?

Ti consigliamo di implementare tutti i flussi per garantire agli utenti la migliore esperienza di collegamento. I flussi semplificati e di app flip riducono l'attrito del collegamento, in quanto gli utenti possono completare la procedura di collegamento in pochi passaggi. Il collegamento OAuth web richiede il minimo sforzo ed è un buon punto di partenza, dopodiché puoi aggiungere gli altri flussi di collegamento.

Utilizzare i token

Il collegamento dell'Account Google si basa sullo standard di settore OAuth 2.0.

Emetti token di accesso a Google per i singoli Account Google dopo aver ottenuto il consenso dei titolari degli account per collegare i loro account e condividere i dati.

Token types

OAuth 2.0 uses strings called tokens to communicate between the user agent, the client application, and the OAuth 2.0 server.

Three types of OAuth 2.0 tokens can be used during account linking:

• Authorization code. A short-lived token that can be exchanged for an access and a refresh token. For security purposes, Google calls your authorization endpoint to obtain a single use or very short-lived code.

• Access token. A token that grants the bearer access to a resource. To limit exposure that could result from the loss of this token, it has a limited lifetime, usually expiring after an hour or so.

• Refresh token. A long-lived token that can be exchanged for a new access token when an access token expires. When your service integrates with Google, this token is exclusively stored and used by Google. Google calls your token exchange endpoint to exchange refresh tokens for access tokens, which are in turn used to access user data.

Token handling

Race conditions in clustered environments and client-server exchanges can result in complex timing and error handling scenarios when working with tokens. For example:

• You receive a request for a new access token, and you issue a new access token. Concurrently, you receive a request for access to your service's resource using the previous, unexpired access token.
• Your refresh token reply is yet to be received (or is never received) by Google. Meanwhile, the previously valid refresh token is used in a request from Google.

Requests and replies can arrive in any order, or not at all due to asynchronous services running in a cluster, network behavior, or other means.

Immediate and fully consistent shared state both within, and between, your and Google's token handling systems cannot be guaranteed. Multiple valid, unexpired tokens can coexist within or across systems short period of time. To minimize negative user impact we recommend you do the following:

• Accept unexpired access tokens, even after a newer token is issued.
• Use alternatives to Refresh Token Rotation.
• Support multiple, concurrently valid access and refresh tokens. For security, you should limit the number of tokens and token lifetime.

Maintenance and outage handling

During maintenance or unplanned outages Google might be unable to call your authorization or token exchange endpoints to obtain access and refresh tokens.

Your endpoints should respond with a 503 error code and empty body. In this case, Google retries failed token exchange requests for a limited time. Provided that Google is later able to obtain refresh and access tokens, failed requests are not visible to users.

Failing requests for an access token result in a visible error, if initiated by a user. Users will be required to retry linking failures if the implicit OAuth 2.0 flow is used.

Recommendations

There are many solutions to minimize maintenance impact. Some options to consider:

• Maintain your existing service and route a limited number of requests to your newly updated service. Migrate all requests only after confirming expected functionality.

• Reduce the number of token requests during the maintenance period:

  • Limit maintenance periods to less than the access token lifetime.

  • Temporarily increase the access token lifetime:

    1. Increase token lifetime to greater than maintenance period.
    2. Wait twice the duration of your access token lifetime, enabling users to exchange short lived tokens for longer duration tokens.
    3. Enter maintenance.
    4. Respond to token requests with a 503 error code and empty body.
    5. Exit maintenance.
    6. Decrease token lifetime back to normal.

Registrati con Google

Avremo bisogno dei dettagli della configurazione di OAuth 2.0 e di condividere le credenziali per attivare il collegamento dell'account. Per i dettagli, consulta la sezione Registrazione.