Questa guida ti aiuta a comprendere le modifiche e i passaggi necessari per eseguire correttamente la migrazione delle librerie JavaScript dalla libreria della piattaforma Accedi con Google a quella più recente della libreria di servizi Google Identity per l'autenticazione.
Se il tuo client utilizza la libreria client delle API di Google per JavaScript o altre librerie precedenti per l'autorizzazione, consulta Eseguire la migrazione ai servizi Google Identity per ulteriori informazioni.
Autenticazione e autorizzazione
L'autenticazione stabilisce chi è qualcuno e viene comunemente indicata come registrazione o accesso degli utenti. L'autorizzazione è il processo di concessione o di rifiuto dell'accesso ai dati o alle risorse. Ad esempio, la tua app richiede il consenso dell'utente per accedere al suo Google Drive.
Come la precedente Libreria piattaforma Accedi con Google, la nuova libreria dei servizi Google Identity è stata creata per supportare i processi di autenticazione e autorizzazione.
Tuttavia, la libreria più recente separa i due processi per ridurre la complessità con cui gli sviluppatori possono integrare gli Account Google con la tua app.
Se il tuo caso d'uso riguarda solo l'autenticazione, continua a leggere questa pagina.
Se il tuo caso d'uso include l'autorizzazione, leggi Come funziona l'autorizzazione degli utenti e Esegui la migrazione ai servizi di identità Google per assicurarti che la tua applicazione utilizzi le API nuove e migliorate.
Che cosa è cambiato
Per gli utenti, la nuova libreria dei servizi di Google Identity offre numerosi miglioramenti di usabilità. Le caratteristiche in evidenza includono:
- Nuovi flussi One Tap e Accesso automatico con meno passaggi individuali,
- un pulsante di accesso aggiornato con personalizzazione degli utenti
- un branding coerente e comportamenti di accesso uniformi sul Web migliorino la comprensione e la fiducia,
- accedere rapidamente ai contenuti: gli utenti possono registrarsi in modo semplice e diretto ovunque si trovino sul tuo sito senza dover prima visitare una pagina di accesso o di account.
Per gli sviluppatori, l'obiettivo è stato ridurre la complessità, migliorare la sicurezza e rendere l'integrazione il più facile e veloce possibile. Alcuni di questi miglioramenti includono:
- La possibilità di aggiungere l'accesso utente ai contenuti statici del tuo sito utilizzando solo HTML
- la separazione dell'autenticazione dell'accesso dalle autorizzazioni e la condivisione dei dati utente, la complessità di un'integrazione OAuth2 non è più necessaria per consentire agli utenti di accedere al tuo sito,
- le modalità popup e di reindirizzamento continuano a essere supportate, ma l'infrastruttura OAuth2 di Google ora reindirizza all'endpoint di accesso del server di backend,
- consolidamento della funzionalità di entrambe le librerie JavaScript di Google Identity e API di Google precedenti in un'unica nuova libreria,
- per le risposte di accesso, ora puoi decidere se utilizzare o meno una funzionalità Promise e indirect tramite le funzioni in stile getter sono state rimosse per semplicità.
Un esempio di migrazione dell'accesso
Se stai eseguendo la migrazione dal pulsante Accedi con Google esistente e ti interessa solo accedere agli utenti del tuo sito, la modifica più semplice consiste nell'eseguire l'aggiornamento al nuovo pulsante personalizzato. A questo scopo, è possibile scambiare le librerie JavaScript e aggiornare il codebase in modo da utilizzare un nuovo oggetto di accesso.
Librerie e configurazione
La libreria della piattaforma Accedi con Google precedente apis.google.com/js/platform.js
e la libreria client delle API di Google per JavaScript: gapi.client
non sono più necessarie per l'autenticazione e l'autorizzazione degli utenti.
Sono stati sostituiti da un'unica nuova libreria JavaScript dei servizi Google Identity: accounts.google.com/gsi/client
.
I tre moduli JavaScript precedenti: api
, client
e platform
utilizzati per l'accesso vengono caricati da apis.google.com
. Per aiutarti a identificare le posizioni in cui la vecchia libreria potrebbe essere inclusa nel tuo sito, in genere:
- il pulsante di accesso predefinito carica
apis.google.com/js/platform.js
, - un'immagine pulsante personalizzata carica
apis.google.com/js/api:client.js
e - l'utilizzo diretto di
gapi.client
caricaapis.google.com/js/api.js
.
Nella maggior parte dei casi, puoi semplicemente continuare a utilizzare le credenziali del tuo ID client delle applicazioni web esistenti. Durante la migrazione, ti consigliamo di consultare le norme OAuth 2.0 e di utilizzare la console API di Google per confermare e, se necessario, aggiornare le seguenti impostazioni client:
- Le tue app di test e di produzione utilizzano progetti separati e hanno i propri ID client.
- il tipo di ID client OAuth 2.0 è "Applicazione web" e
- HTTPS viene utilizzato per le origini JavaScript autorizzate e gli URI di reindirizzamento.
Identificare il codice e i test interessati
Un cookie di debug può aiutarti a individuare il codice interessato e a testare il comportamento post-deprecazione.
Nelle app di grandi dimensioni o complesse, potrebbe essere difficile trovare tutto il codice interessato dal ritiro del modulo gapi.auth2
. Per registrare l'utilizzo esistente della funzionalità da presto deprecata nella console, imposta il valore del cookie G_AUTH2_MIGRATION
su informational
. In via facoltativa, aggiungi i due punti seguiti da un valore chiave per registrare anche nello spazio di archiviazione della sessione.
Dopo l'accesso e la ricezione delle credenziali o l'invio dei log raccolti a un backend per un'analisi successiva. Ad esempio, informational:showauth2use
salva
origine e URL in una chiave di archiviazione della sessione denominata showauth2use
Per verificare il comportamento dell'app quando il modulo gapi.auth2
non viene più caricato, imposta il valore del cookie G_AUTH2_MIGRATION
su enforced
. Questo consente di testare il comportamento post-ritiro prima della data di applicazione.
Possibili valori dei cookie G_AUTH2_MIGRATION
:
enforced
Non caricare il modulogapi.auth2
.informational
Registra l'utilizzo della funzionalità deprecata nella console JS. Accedi anche allo spazio di archiviazione della sessione quando è impostato un nome chiave facoltativo:informational:key-name
.
Per ridurre al minimo l'impatto sugli utenti, è consigliabile impostare questo cookie localmente durante lo sviluppo e il test, prima di utilizzarlo in ambienti di produzione.
HTML e JavaScript
In questo scenario di accesso solo di autenticazione vengono mostrati il codice di esempio e il rendering del pulsante Accedi con Google esistente. Seleziona una delle seguenti modalità: Popup o Reindirizzamento per visualizzare le differenze nella modalità di gestione della risposta di autenticazione tramite callback JavaScript o reindirizzamento sicuro all'endpoint di accesso al server di backend.
Nella vecchia maniera
Modalità popup
Esegui il rendering del pulsante Accedi con Google e utilizza un callback per gestire l'accesso direttamente dal browser dell'utente.
<html>
<body>
<script src="https://apis.google.com/js/platform.js" async defer></script>
<meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
<div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
</body>
</html>
Modalità di reindirizzamento
Esegui il rendering del pulsante Accedi con Google, che termina con una chiamata AJAX dal browser dell'utente all'endpoint di accesso dei server back-end.
<html>
<body>
<script src="https://apis.google.com/js/platform.js" async defer></script>
<meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
<div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
<script>
function handleCredentialResponse(googleUser) {
...
var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xhr.onload = function() {
console.log('Signed in as: ' + xhr.responseText);
};
xhr.send('idtoken=' + id_token);
}
</script>
</body>
</html>
Visualizzato
I nuovi attributi visivi semplificano il vecchio metodo di creazione di un pulsante personalizzato, elimina le chiamate a gapi.signin2.render()
e non devi ospitare e gestire immagini e asset visivi sul tuo sito.
Testo del pulsante di aggiornamento dello stato di accesso dell'utente.
Il nuovo modo
Per utilizzare la nuova libreria in uno semplice scenario di accesso solo autenticazione, seleziona la modalità popup o di reindirizzamento e utilizza l'esempio di codice per sostituire l'implementazione esistente nella pagina di accesso.
Modalità popup
Utilizza un callback per gestire l'accesso direttamente dal browser dell'utente.
<html>
<body>
<script src="https://accounts.google.com/gsi/client" async defer></script>
<div id="g_id_onload"
data-client_id="YOUR_CLIENT_ID"
data-callback="handleCredentialResponse">
</div>
<div class="g_id_signin" data-type="standard"></div>
</body>
</html>
Modalità di reindirizzamento
Google richiama il tuo endpoint di accesso come specificato dall'attributo
data-login_url. In precedenza, eri responsabile dell'operazione POST e del nome del parametro. La nuova libreria pubblica il token ID nel tuo endpoint nel parametro credential
. Infine, verifica il token ID sul tuo server di backend.
<html>
<body>
<script src="https://accounts.google.com/gsi/client" async defer></script>
<div id="g_id_onload"
data-client_id="YOUR_CLIENT_ID"
data-ux_mode="redirect"
data-login_uri="https://www.example.com/your_login_endpoint">
</div>
<div class="g_id_signin" data-type="standard"></div>
</body>
</html>
Visualizzato
Utilizza gli attributi visivi per personalizzare le dimensioni, la forma e il colore del pulsante Accedi con Google. Visualizza il popup One Tap insieme al pulsante personalizzato per migliorare la percentuale di accesso.
Lo stato di accesso dell'utente non aggiorna il testo del pulsante da "Accedi" a "Accesso". Dopo aver fornito il consenso o le visite di ritorno, il pulsante personalizzato include il nome, l'indirizzo email e l'immagine del profilo dell'utente.
In questo semplice esempio di sola autenticazione, la nuova libreria accounts.google.com/gsi/client
, la classe g_id_signin
e l'oggetto g_id_onload
sostituiscono la precedente libreria apis.google.com/js/platform.js
e l'oggetto g-signin2
.
Oltre a visualizzare il nuovo pulsante personalizzato, il codice di esempio mostra anche il nuovo popup One Tap. Ogni volta che mostri il pulsante personalizzato, ti consigliamo vivamente di mostrare anche il popup di One Tap per ridurre al minimo l'attrito dell'utente durante la registrazione e l'accesso.
Sebbene non sia consigliabile a causa dei maggiori problemi di accesso, il nuovo pulsante personalizzato può essere mostrato da solo, senza mostrare contemporaneamente la finestra di dialogo One Tap. Per farlo, imposta l'attributo data-auto_prompt
su false
.
API HTML e JavaScript
L'esempio precedente mostra come utilizzare la nuova API HTML per aggiungere l'accesso al sito web. In alternativa, puoi utilizzare l'API JavaScript equivalente dal punto di vista funzionale oppure combinare e abbinare le API HTML e JavaScript in tutto il sito.
Per visualizzare in modo interattivo le opzioni di personalizzazione dei pulsanti, come il tipo di callback e gli attributi, quali colore, dimensione, forma, testo e tema, dai un'occhiata al nostro generatore di codice. Può essere utilizzata per confrontare rapidamente diverse opzioni e generare snippet HTML da utilizzare sul tuo sito.
Accedi da qualsiasi pagina con One Tap
One Tap è un nuovo modo a basso impatto che consente agli utenti di registrarsi o accedere al tuo sito. Consente di attivare l'accesso utente da qualsiasi pagina del sito e di eliminare la necessità di visitare una pagina di accesso dedicata. In altre parole, questo riduce la registrazione e l'accesso, offrendo agli utenti la flessibilità di registrarsi e accedere da pagine diverse dalla pagina di accesso.
Per abilitare l'accesso da una pagina, ti consigliamo di includere g_id_onload
in un'intestazione, nel piè di pagina o in un altro oggetto condiviso incluso in tutto il sito.
Ti consigliamo inoltre di aggiungere g_id_signin
, che mostra il pulsante di accesso personalizzato, solo nelle pagine di accesso o di gestione degli account utente. Offri agli utenti la possibilità di scegliere se registrarsi o eseguire l'accesso mostrando il pulsante accanto ad altri pulsanti federati del provider di identità e i campi di inserimento di nome utente e password.
Risposta token
L'accesso utente non richiede più di comprendere o utilizzare i codici di autorizzazione OAuth2, i token di accesso o i token di aggiornamento. Per condividere lo stato di accesso e il profilo utente viene invece usato un token JWT (JSON Web Token). Come ulteriore semplificazione, non devi più utilizzare i metodi di accesso di tipo "getter" per utilizzare i dati del profilo utente.
Le credenziali di un token JWT sicuro firmato da Google vengono restituite:
- al gestore di callback JavaScript basato su browser dell'utente in modalità popup.
- al tuo server di backend tramite un reindirizzamento Google all'endpoint di accesso quando il pulsante Accedi con Google
ux_mode
è impostato suredirect
.
In entrambi i casi, aggiorna i gestori di callback esistenti rimuovendo:
- chiamate a
googleUser.getBasicProfile()
, - riferimenti a
BasicProfile
e chiamate associate ai metodigetId()
,getName()
,getGivenName()
,getFamilyName()
,getImageUrl()
egetEmail()
e - dell'oggetto
AuthResponse
.
Utilizza invece i riferimenti diretti ai sottocampi credential
nel nuovo oggetto JWT
CredentialResponse
per lavorare con i dati del profilo utente.
Inoltre, e soltanto per la modalità di reindirizzamento, assicurati di impedire la richiesta di contraffazione (CSRF) e la verifica del token ID Google sul tuo server di backend.
Per capire meglio in che modo gli utenti interagiscono con il tuo sito, puoi utilizzare il campo select_by
nella CredentialResponse per determinare il risultato del consenso dell'utente e il flusso di accesso specifico.
Consenso dell'utente e revoca dell'autorizzazione
Quando un utente accede per la prima volta al tuo sito web, Google chiede all'utente il consenso a condividere il profilo del suo account con la tua app. Solo dopo aver fornito il consenso, il profilo dell'utente viene condiviso con la tua app in un token di payload del token ID. La revoca dell'accesso a questo profilo equivale a revocare un token di accesso nella vecchia libreria di accesso.
Gli utenti possono revocare le autorizzazioni e scollegare l'app dal proprio Account Google visitando la pagina https://myaccount.google.com/permissions.
In alternativa, potrebbero disconnettersi direttamente dalla tua app attivando una chiamata API che implementi; il metodo disconnect
precedente è stato sostituito dal metodo revoke
più recente.
Quando un utente elimina il proprio account sulla piattaforma, è buona norma utilizzare revoke
per scollegare l'app dal proprio Account Google.
In precedenza, potevi utilizzare auth2.signOut()
per gestire la disconnessione dell'utente dall'app.
Qualsiasi utilizzo di auth2.signOut()
dovrebbe essere rimosso e l'app doveva gestire direttamente lo stato della sessione e l'accesso di ogni utente.
Stato sessione e listener
La nuova libreria non mantiene lo stato di accesso o lo stato della sessione per la tua app web.
Lo stato di accesso di un Account Google e lo stato di sessione e di accesso dell'app sono due concetti distinti e separati.
Lo stato di accesso dell'utente al suo Account Google e alla tua app sono indipendenti l'uno dall'altro, tranne durante il momento in cui avviene l'accesso stesso quando sai che l'utente ha eseguito l'autenticazione ed ha eseguito l'accesso al suo Account Google.
Se includi l'opzione Accedi con Google, One Tap o Accesso automatico sul tuo sito, gli utenti devono prima accedere al proprio Account Google per:
- Acconsenti alla condivisione del proprio profilo utente quando si registra per la prima volta o accede al tuo sito.
- e in un secondo momento per l'accesso per le visite di ritorno sul tuo sito.
Gli utenti possono rimanere collegati, uscire o passare a un altro Account Google, mantenendo una sessione attiva su cui è stato eseguito l'accesso sul tuo sito web.
Ora sei responsabile della gestione diretta dello stato dell'accesso per gli utenti della tua app web. In precedenza, Accedi con Google ti aiutava a Monitorare lo stato della sessione dell'utente.
Rimuovi tutti i riferimenti a auth2.attachClickHandler()
e ai relativi gestori di callback registrati.
In precedenza, i Ascoltatori venivano usati per condividere le modifiche dello stato dell'accesso a un Account Google di un utente. Gli ascoltatori non sono più supportati.
Rimuovi i riferimenti a listen()
, auth2.currentUser
e auth2.isSignedIn
.
Cookie
La funzionalità Accedi con Google fa un uso limitato dei cookie. Di seguito è riportata una descrizione di questi cookie. Per ulteriori informazioni sugli altri tipi di cookie utilizzati da Google, consulta la pagina In che modo Google utilizza i cookie.
Il cookie G_ENABLED_IDPS
impostato dalla precedente libreria della piattaforma Accedi con Google non viene più utilizzato.
Facoltativamente, la nuova libreria Servizi di identità Google può impostare questi cookie interdominio in base alle tue opzioni di configurazione:
g_state
archivia lo stato di disconnessione dell'utente e viene impostato usando il popup One Tap o l'Accesso automatico,g_csrf_token
è un cookie a doppio invio utilizzato per impedire gli attacchi CSRF e viene impostato quando viene richiamato l'endpoint di accesso. Il valore dell'URI di accesso può essere esplicitamente impostato o potrebbe essere l'URI della pagina corrente predefinito. Il tuo endpoint di accesso può essere chiamato a queste condizioni quando utilizzi:API HTML con
data-ux_mode=redirect
o quandodata-login_uri
è impostato oppureL'API JavaScript con
ux_mode=redirect
e dovegoogle.accounts.id.prompt()
non viene utilizzato per visualizzare One Tap o Accesso automatico.
Se hai un servizio che gestisce i cookie, assicurati di aggiungere i due nuovi cookie e di rimuovere il cookie precedente al termine della migrazione.
Se gestisci più domini o sottodomini, consulta l'articolo Visualizzare One Tap in tutti i sottodomini per ulteriori istruzioni sull'utilizzo del cookie g_state
.
Riferimento per la migrazione degli oggetti per l'accesso degli utenti
Precedenti | Nuovo | Note |
---|---|---|
Librerie JavaScript | ||
apis.google.com/js/platform.js | accounts.google.com/gsi/client | Sostituisci il vecchio con il nuovo. |
apis.google.com/js/api.js | accounts.google.com/gsi/client | Sostituisci il vecchio con il nuovo. |
GoogleAuth e i metodi associati: | ||
GoogleAuth.attachClickHandler() | IdConfiguration.callback per data-callback JS e HTML | Sostituisci il vecchio con il nuovo. |
GoogleAuth.currentUser.get() | Risposta credenziali | Utilizza CredentialResponse, non più necessario. |
GoogleAuth.currentUser.listen() | Rimuovi. Lo stato di accesso attuale di un utente su Google non è disponibile. Gli utenti devono aver eseguito l'accesso a Google per il consenso e i momenti di accesso. Il campo select_by in CredentialResponse può essere utilizzato per determinare il risultato del consenso dell'utente insieme al metodo di accesso utilizzato. | |
GoogleAuth.disconnect() | google.accounts.id.revoke | Sostituisci il vecchio con il nuovo. La revoca potrebbe avvenire anche da https://myaccount.google.com/permissions |
GoogleAuth.grantOfflineAccess() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
GoogleAuth.isSignedIn.get() | Rimuovi. Lo stato di accesso attuale di un utente su Google non è disponibile. Gli utenti devono aver eseguito l'accesso a Google per il consenso e i momenti di accesso. | |
GoogleAuth.isSignedIn.listen() | Rimuovi. Lo stato di accesso attuale di un utente su Google non è disponibile. Gli utenti devono aver eseguito l'accesso a Google per il consenso e i momenti di accesso. | |
GoogleAuth.signin() | Rimuovi. Il caricamento HTML DOM dell'elemento g_id_signin o della chiamata JS a google.accounts.id.renderButton attiva l'accesso dell'utente a un Account Google. | |
GoogleAuth.signOut() | Rimuovi. Lo stato di accesso dell'utente per la tua app e per un Account Google è indipendente. Google non gestisce lo stato della sessione per la tua app. | |
GoogleAuth.then() | Rimuovi. L'app GoogleAuth è deprecata. | |
Oggetto GoogleUser e metodi associati: | ||
Google.disconnect() | google.accounts.id.revoke | Sostituisci il vecchio con il nuovo. La revoca potrebbe avvenire anche da https://myaccount.google.com/permissions |
UtenteGoogle.getAuthResponse() | ||
UtenteGoogle.GetBaseprofile() | Risposta credenziali | Utilizza direttamente credential e i sottocampi invece dei metodi BasicProfile . |
UtenteGoogle.getGrantedScopes() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
GoogleUser.getHostedDomain() | Risposta credenziali | Utilizza invece credential.hd direttamente. |
UtenteGoogle.getId() | Risposta credenziali | Utilizza invece credential.sub direttamente. |
GoogleUser.grantOfflineAccess() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
GoogleUser.grant() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
GoogleUser.hasGrantedScopes() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
UtenteGoogle.isSignedIn() | Rimuovi. Lo stato di accesso attuale di un utente su Google non è disponibile. Gli utenti devono aver eseguito l'accesso a Google per il consenso e i momenti di accesso. | |
GoogleUser.reloadAuthResponse() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
gapi.auth2 e i metodi associati: | ||
Oggetto gapi.auth2.AuthorizeConfig | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
Oggetto gapi.auth2.AuthorizeResponse | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
Oggetto gapi.auth2.AuthResponse | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
gapi.auth2.auth() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
gapi.auth2.ClientConfig() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
gapi.auth2.getAuthInstance() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
gapi.auth2.init() | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
Oggetto gapi.auth2.OfflineAccessOptions | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
Oggetto gapi.auth2.SignInOptions | Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth2. | |
gapi.signin2 e metodi associati: | ||
gapi.signin2.render() | Rimuovi. Il caricamento HTML DOM dell'elemento g_id_signin o della chiamata JS a google.accounts.id.renderButton attiva l'accesso dell'utente a un Account Google. |