Scegli 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 dell'account standard | Smart Home, TV e YouTube. | Documenti |
Il collegamento dell'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
Ecco alcuni motivi per implementare il collegamento dell'Account Google:
Condividere i dati di un utente dalla tua piattaforma con app e servizi Google.
Eseguire l'integrazione con Google Shopping e le superfici AI (Ricerca, Gemini) utilizzando il Universal Commerce Protocol (UCP).
Riprodurre i contenuti video e cinematografici utilizzando Google TV.
Gestire e controllare i dispositivi per la smart home connessi a Google utilizzando l'app Google Home e l'Assistente Google, ad esempio "Ok Google, accendi le luci".
Creare esperienze e funzionalità dell'Assistente Google personalizzate per gli utenti con le azioni conversazionali, "Hey Google, ordina il mio solito da Starbucks".
Consentire agli utenti di vincere 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 i dati condivisi con il consenso dell'utente da un profilo di Account Google.
Funzionalità e requisiti
La seguente matrice definisce il supporto e i consigli per ogni flusso di collegamento.
| Flusso di collegamento | Funzionalità standard | Funzionalità UCP |
|---|---|---|
| App Flip | Consigliato | Consigliato |
| Collegamento semplificato | Consigliato | Consigliato |
| Collegamento OAuth | Obbligatorio (fallback) | Obbligatorio (fallback) |
| OAuth 2.1 | Consigliato | Consigliato |
Migliorare la privacy degli utenti definendo ambiti personalizzati per condividere solo i dati necessari e aumentare 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 notificare a Google eventuali eventi di scollegamento che si verificano sulla tua piattaforma.
Flussi di collegamento dell'account
Esistono tre flussi di collegamento dell'Account Google, tutti basati su OAuth e che richiedono di gestire o controllare gli endpoint di autorizzazione e scambio di token conformi a OAuth 2.0.
Durante la procedura di collegamento, rilasci token di accesso a Google per i singoli Account Google dopo aver ottenuto il consenso dei titolari degli account per collegare i propri account e condividere i dati.
Collegamento OAuth
Questo è il flusso di collegamento OAuth che invia gli utenti al tuo sito web per il collegamento. L'utente viene reindirizzato al tuo sito web per accedere al proprio account. Una volta eseguito l'accesso, l'utente acconsente a condividere i 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 del codice di autorizzazione e implicito. 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 si utilizza il flusso del codice di autorizzazione.
Figura 1. Collegamento dell'account sullo smartphone di un utente con il collegamento OAuth
Collegamento App Flip basato su OAuth ("App Flip")
Un flusso OAuth che invia gli utenti alla tua app per il collegamento.
Il collegamento 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 concedere il consenso a 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 Accedi con Google basato su OAuth utilizzando il flusso del codice di autorizzazione.
App Flip è supportato sia per Android che per iOS.
Come funziona:
L'app Google verifica se la tua app è installata sul dispositivo dell'utente:
- Se l'app viene trovata, l'utente viene "trasferito" alla tua app. La tua app raccoglie il consenso dell'utente per collegare l'account a Google e poi "ritorna" alla superficie Google.
- Se l'app non viene trovata o si verifica un errore durante la procedura di collegamento App Flip, l'utente viene reindirizzato al flusso di collegamento semplificato o OAuth.
Figura 2. Collegamento dell'account sullo smartphone di un utente con App Flip
Collegamento semplificato basato su OAuth ("Semplificato")
Il collegamento semplificato Accedi con Google basato su OAuth aggiunge Accedi con Google al collegamento OAuth, consentendo agli utenti di completare la procedura di collegamento senza uscire dalla superficie Google, riducendo così gli attriti e gli abbandoni.
Il collegamento semplificato basato su OAuth offre
la migliore esperienza utente con l'accesso, la creazione dell'account e il collegamento dell'account
senza interruzioni combinando Accedi con Google e il collegamento OAuth. Il tuo servizio deve supportare gli 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 intenti
check,
create,
e get.
Come funziona:
Google asserisce l'account utente e ti trasmette queste informazioni:
- Se esiste un account per l'utente nel tuo database, l'utente collega correttamente il proprio Account Google al proprio account sul tuo servizio.
- Se non esiste un account per l'utente nel tuo database, l'utente può creare un nuovo account di terze parti con le informazioni asserite fornite da Google: indirizzo email, nome e immagine del profilo oppure scegliere di accedere e collegare con un altro indirizzo email (in questo caso dovrà accedere al tuo servizio utilizzando il collegamento OAuth ).
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 App Flip riducono gli attriti di collegamento, in quanto gli utenti possono completare la procedura di collegamento in pochi passaggi. Il flusso di collegamento OAuth 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.
Rilasci token di accesso a Google per i singoli Account Google dopo aver ottenuto il consenso dei titolari degli account per collegare i propri account e condividere i dati.
Tipi di token
OAuth 2.0 utilizza stringhe chiamate token per comunicare tra lo user agent, l'applicazione client e il server OAuth 2.0.
Durante il collegamento dell'account è possibile utilizzare tre tipi di token OAuth 2.0:
Codice di autorizzazione. Un token a breve durata che può essere scambiato con un token di accesso e un token di aggiornamento. Per motivi di sicurezza, Google chiama l'endpoint di autorizzazione per ottenere un codice monouso o a brevissima durata.
Token di accesso. Un token che concede al portatore l'accesso a una risorsa. Per limitare l'esposizione che potrebbe derivare dalla perdita di questo token, ha una durata limitata, in genere scade dopo circa un'ora.
Token di aggiornamento. Un token a lunga durata che può essere scambiato con un nuovo token di accesso quando un token di accesso scade. Quando il tuo servizio si integra con Google, questo token viene archiviato e utilizzato esclusivamente da Google. Google chiama l'endpoint di scambio dei token per scambiare i token di aggiornamento con i token di accesso, che a loro volta vengono utilizzati per accedere ai dati utente.
Gestione dei token
Le condizioni di race negli ambienti in cluster e gli scambi client-server possono comportare scenari complessi di gestione di tempistiche e gestione degli errori quando si lavora con i token. Ad esempio:
- Ricevi una richiesta per un nuovo token di accesso ed emetti un nuovo token di accesso. Contemporaneamente, ricevi una richiesta di accesso alla risorsa del tuo servizio utilizzando il token di accesso precedente, non scaduto.
- Google non ha ancora ricevuto (o non riceverà mai) la risposta del token di aggiornamento. Nel frattempo, il token di aggiornamento valido in precedenza viene utilizzato in una richiesta di Google.
Le richieste e le risposte possono arrivare in qualsiasi ordine o non arrivare affatto a causa di servizi asincroni in esecuzione in un cluster, del comportamento della rete o di altri mezzi.
Non è possibile garantire uno stato condiviso immediato e completamente coerente sia all'interno che tra i sistemi di gestione dei token di Google e del tuo servizio. Per un breve periodo di tempo, possono coesistere più token validi e non scaduti all'interno o tra i sistemi. Per ridurre al minimo l'impatto negativo sugli utenti, ti consigliamo di:
- Accettare i token di accesso non scaduti, anche dopo l'emissione di un token più recente.
- Utilizzare alternative alla rotazione dei token di aggiornamento.
- Supportare più token di accesso e di aggiornamento validi contemporaneamente. Per motivi di sicurezza, devi limitare il numero di token e la durata dei token.
Gestione della manutenzione e delle interruzioni
Durante la manutenzione o le interruzioni non pianificate, Google potrebbe non essere in grado di chiamare gli endpoint di autorizzazione o di scambio dei token per ottenere i token di accesso e di aggiornamento.
Gli endpoint devono rispondere con un codice di errore 503 e un corpo vuoto. In questo caso, Google riprova a inviare le richieste di scambio dei token non riuscite per un periodo di tempo limitato. A condizione che Google sia in grado di ottenere in un secondo momento i token di aggiornamento e di accesso, le richieste non riuscite non sono visibili agli utenti.
Se avviate da un utente, le richieste non riuscite per un token di accesso generano un errore visibile. Se viene utilizzato il flusso implicito OAuth 2.0, gli utenti dovranno riprovare a collegare gli account in caso di errori.
Consigli
Esistono molte soluzioni per ridurre al minimo l'impatto della manutenzione. Ecco alcune opzioni da prendere in considerazione:
Mantieni il servizio esistente e indirizza un numero limitato di richieste al servizio appena aggiornato. Esegui la migrazione di tutte le richieste solo dopo aver confermato la funzionalità prevista.
Riduci il numero di richieste di token durante il periodo di manutenzione:
Limita i periodi di manutenzione a una durata inferiore alla durata del token di accesso.
Aumenta temporaneamente la durata del token di accesso:
- Aumenta la durata del token a un valore superiore al periodo di manutenzione.
- Attendi il doppio della durata del token di accesso, consentendo agli utenti di scambiare i token a breve durata con token di durata maggiore.
- Avvia la manutenzione.
- Rispondi alle richieste di token con un codice di errore
503e un corpo vuoto. - Termina la manutenzione.
- Riporta la durata del token al valore normale.
Collegamento persistente
Il collegamento persistente è un requisito fondamentale per le integrazioni stabili. Garantisce che gli account utente rimangano collegati anche durante guasti di rete temporanei o aggiornamenti periodici delle credenziali.
Per implementare il collegamento persistente, utilizza un approccio a "finestra scorrevole": estendi la scadenza del token di aggiornamento esistente anziché ruotarlo (fai riferimento alla sezione 6 della RFC 6749). In questo modo si evitano condizioni di competizione e scollegamenti involontari che possono verificarsi se viene emesso un nuovo token di aggiornamento, ma non viene ricevuto o memorizzato correttamente da Google.
Registrarsi 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 relativa alla registrazione.