Eseguire la migrazione da Accedi con Google

Questa guida ti aiuta a comprendere le modifiche necessarie e i passaggi per eseguire la migrazione delle librerie JavaScript dalla precedente libreria della piattaforma di Accedi con Google alla nuova libreria di Servizi di identità Google per l'autenticazione.

Se il tuo cliente utilizza la libreria client delle API di Google per JavaScript o altre librerie precedenti per l'autorizzazione, consulta Eseguire la migrazione a Google Identity Services per ulteriori informazioni.

Autenticazione e autorizzazione

L'autenticazione stabilisce chi è una persona ed è comunemente indicata come registrazione o accesso dell'utente. L'autorizzazione è il processo di concessione o rifiuto dell'accesso a dati o risorse. Ad esempio, la tua app richiede il consenso dell'utente per accedere a Google Drive.

Come la precedente libreria della piattaforma di Accedi con Google, la nuova libreria dei Servizi di identità Google è progettata per supportare sia le procedure di autenticazione sia quelle di autorizzazione.

Tuttavia, la libreria più recente separa i due processi per ridurre la complessità per gli sviluppatori nell'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 utente e Eseguire la migrazione a Google Identity Services per assicurarti che la tua applicazione utilizzi le API nuove e migliorate.

Che cosa è cambiato

Per gli utenti, la nuova libreria di Servizi di identità Google offre numerosi miglioramenti dell'usabilità. Ecco alcune delle caratteristiche principali:

  • Nuovi flussi One Tap e di accesso automatico con meno passaggi individuali,
  • un pulsante di accesso aggiornato con personalizzazione dell'utente.
  • un branding coerente e un comportamento di accesso uniforme sul web migliorano la comprensione e la fiducia,
  • accedere rapidamente ai contenuti: gli utenti possono registrarsi e accedere direttamente da qualsiasi pagina del tuo sito senza dover prima visitare una pagina di accesso o dell'account.

Per gli sviluppatori, il nostro obiettivo è stato ridurre la complessità, migliorare la sicurezza e effettuare l'integrazione il più rapidamente possibile. Ecco alcuni di questi miglioramenti:

  • L'opzione per aggiungere l'accesso degli utenti ai contenuti statici del tuo sito utilizzando solo HTML,
  • separazione dell'autenticazione di accesso dall'autorizzazione e dalla condivisione dei dati utente, la complessità di un'integrazione di OAuth 2.0 non è più necessaria per far accedere gli utenti al tuo sito,
  • sia le modalità popup sia quelle di reindirizzamento continuano a essere supportate, ma l'infrastruttura OAuth 2.0 di Google ora reindirizza all'endpoint di accesso del tuo server di backend.
  • il consolidamento delle funzionalità delle precedenti librerie JavaScript di Google Identity e Google API in un'unica nuova libreria,
  • Per le risposte di accesso, ora puoi decidere se utilizzare o meno una promessa e l'indirizzamento tramite funzioni di stile getter è stato rimosso per semplicità.

Un esempio di migrazione dell'accesso

Se stai eseguendo la migrazione dal pulsante Accedi con Google esistente e ti interessa solo far accedere gli utenti al tuo sito, la modifica più semplice è eseguire l'aggiornamento al nuovo pulsante personalizzato. Questo può essere ottenuto scambiando le librerie JavaScript e aggiornando la base di codice in modo da utilizzare un nuovo oggetto di accesso.

Librerie e configurazione

La precedente libreria della piattaforma di Accedi con Google: 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 una singola nuova libreria JavaScript di Google Identity Services:accounts.google.com/gsi/client.

I tre moduli JavaScript precedenti: api, client e platform utilizzati per accedere vengono caricati da apis.google.com. Per aiutarti a identificare le posizioni in cui la raccolta precedente potrebbe essere inclusa nel tuo sito, in genere:

  • viene caricato il pulsante di accesso predefinito apis.google.com/js/platform.js.
  • viene caricata un'immagine del pulsante personalizzato apis.google.com/js/api:client.js e
  • l'utilizzo diretto di gapi.client caricamenti apis.google.com/js/api.js.

Nella maggior parte dei casi puoi continuare a utilizzare le credenziali dell'ID client dell'applicazione web esistente. Nell'ambito della migrazione, ti consigliamo di esaminare le nostre norme OAuth 2.0 e di utilizzare la Console API di Google per verificare e, se necessario, aggiornare le seguenti impostazioni client:

  • le app di test e di produzione utilizzano progetti separati e hanno i propri ID client,
  • il tipo di ID client OAuth 2.0 sia "Applicazione web" e
  • HTTPS viene utilizzato per le origini JavaScript autorizzate e gli URI di reindirizzamento.

Identificare il codice interessato e testarlo

Un cookie di debug può essere utile per individuare il codice interessato e per testare il comportamento post-ritiro.

In app di grandi dimensioni o complesse, potrebbe essere difficile trovare tutto il codice interessato dal ritiro del modulo gapi.auth2. Per registrare nella console l'utilizzo esistente di funzionalità che verranno ritirate a breve, imposta il valore del cookie G_AUTH2_MIGRATION su informational. Se vuoi, aggiungi due punti seguiti da un valore della chiave per registrare anche nello spazio di archiviazione della sessione. Dopo l'accesso e la ricezione delle credenziali, esamina o invia i log raccolti a un backend per l'analisi successiva. Ad esempio, informational:showauth2use salva l'origine e l'URL in una chiave della memoria di 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. In questo modo, puoi testare il comportamento post-ritiro prima della data di applicazione.

Possibili valori del cookie G_AUTH2_MIGRATION:

  • enforced Non caricare il modulo gapi.auth2.
  • informational Registra l'utilizzo delle funzionalità ritirate nella console JS. Esegui anche il logging nell'archiviazione della sessione quando è impostato un nome chiave facoltativo: informational:key-name.

Per ridurre al minimo l'impatto sugli utenti, ti consigliamo di impostare prima questo cookie localmente durante lo sviluppo e il test, prima di utilizzarlo negli ambienti di produzione.

HTML e JavaScript

In questo scenario di accesso solo per l'autenticazione, vengono mostrati codice di esempio e rendering del pulsante Accedi con Google esistente. Seleziona la modalità popup o di reindirizzamento per vedere le differenze nel modo in cui la risposta di autenticazione viene gestita da un callback JavaScript o da un reindirizzamento sicuro all'endpoint di accesso del server di backend.

Il metodo precedente

Mostra il 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

Mostra il pulsante Accedi con Google, terminando con una chiamata AJAX dal browser dell'utente all'endpoint di accesso dei tuoi server di backend.

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

Renderizzato

I nuovi attributi visual-attributes semplificano il metodo precedente per creare un pulsante personalizzato, eliminano le chiamate a gapi.signin2.render() e la necessità di ospitare e gestire immagini e asset visivi sul tuo sito.

Accedi con Google

Accesso con Google

Testo del pulsante di aggiornamento dello stato di accesso dell'utente.

Il nuovo modo

Per utilizzare la nuova libreria in uno scenario di accesso solo per l'autenticazione, scegli la modalità popup o di reindirizzamento e utilizza il codice di esempio per sostituire l'implementazione esistente nella pagina di accesso.

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 l'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 parametro credential del tuo endpoint. 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>

Renderizzato

Utilizza visual-attributes per personalizzare il pulsante Accedi con Google in termini di dimensione, forma e colore. Visualizza il popup One Tap insieme al pulsante personalizzato per migliorare il tasso di accesso.

Pulsante Accedi con Google popup One Tap

Lo stato di accesso dell'utente non aggiorna il testo del pulsante da "Accedi" a "Accesso eseguito". Dopo aver fornito il consenso o durante le visite successive, il pulsante personalizzato include il nome, l'indirizzo email e l'immagine del profilo dell'utente.

In questo esempio solo per l'autenticazione, la nuova libreria accounts.google.com/gsi/client, la classe g_id_signin e l'oggetto g_id_onload sostituiscono la libreria apis.google.com/js/platform.js e l'oggetto g-signin2 precedenti.

Oltre a eseguire il rendering del nuovo pulsante personalizzato, il codice di esempio mostra anche il nuovo popup One Tap. Ovunque mostri il pulsante personalizzato, ti consigliamo vivamente di mostrare anche il popup One Tap per ridurre al minimo le difficoltà degli utenti durante la registrazione e l'accesso.

Sebbene non sia consigliato a causa dell'aumento delle difficoltà di accesso, il nuovo pulsante personalizzato può essere mostrato da solo, senza visualizzare 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 tuo sito web. In alternativa, puoi utilizzare l'API JavaScript, funzionalmente equivalente, o combinare API HTML e JavaScript nel tuo sito.

Per visualizzare in modo interattivo le opzioni di personalizzazione dei pulsanti, ad esempio il tipo di callback e gli attributi come colore, dimensioni, forma, testo e tema, consulta il nostro Generatore di codice. Può essere utilizzato per confrontare rapidamente diverse opzioni e generare snippet HTML da utilizzare sul tuo sito.

Accedere da qualsiasi pagina con One Tap

One Tap è un nuovo modo semplice per consentire agli utenti di registrarsi o accedere al tuo sito. Ti consente di attivare l'accesso degli utenti direttamente da qualsiasi pagina del tuo sito ed elimina la necessità per gli utenti di visitare una pagina di accesso dedicata. In altre parole, questo riduce le difficoltà di registrazione e accesso offrendo agli utenti la flessibilità di registrarsi e accedere da pagine diverse dalla tua pagina di accesso.

Per abilitare l'accesso da qualsiasi pagina, ti consigliamo di includere g_id_onload in un header, un piè di pagina o un altro oggetto condiviso incluso nell'intero sito.

Ti consigliamo inoltre di aggiungere g_id_signin, che mostra il pulsante di accesso personalizzato, solo nelle pagine di accesso o di gestione dell'account utente. Offri agli utenti la possibilità di scegliere tra registrazione o accesso mostrando il pulsante insieme ad altri pulsanti di provider di identità federati e ai campi di immissione di nome utente e password.

Risposta del token

Per l'accesso degli utenti non è più necessario comprendere o utilizzare i codici di autorizzazione, i token di accesso o i token di aggiornamento OAuth 2.0. Viene invece utilizzato un token ID JWT (JSON Web Token) per condividere lo stato di accesso e il profilo utente. Come ulteriore semplificazione, non è più necessario utilizzare metodi di accesso nello stile "getter" per lavorare con i dati del profilo utente.

Viene restituita una credenziale JWT token ID sicura firmata da Google se:

  • al gestore dei callback JavaScript basato sul browser dell'utente in modalità popup oppure
  • al tuo server di backend tramite un reindirizzamento di Google al tuo endpoint di accesso quando il pulsante Accedi con Google ux_mode è impostato su redirect.

In entrambi i casi, aggiorna i gestori di callback esistenti rimuovendo:

  • Chiamate a googleUser.getBasicProfile(),
  • riferimenti a BasicProfile e chiamate associate ai metodi getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), getEmail() e
  • dell'oggetto AuthResponse.

Utilizza invece riferimenti diretti ai campi secondari credential nel nuovo oggetto JWT CredentialResponse per lavorare con i dati del profilo utente.

Inoltre, solo per la modalità di reindirizzamento, assicurati di impedire le attività di falsificazione delle richieste cross-site (CSRF) e di verificare il token ID Google sul tuo server di backend.

Per comprendere meglio in che modo gli utenti interagiscono con il tuo sito, il campo select_by in CredentialResponse può essere utilizzato per determinare l'esito del consenso dell'utente e il flusso di accesso specifico utilizzato.

Quando un utente accede per la prima volta al tuo sito web, Google gli chiede il consenso per 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 payload delle credenziali del token ID. La revoca dell'accesso a questo profilo equivale alla revoca di un token di accesso nella biblioteca di accesso precedente.

Gli utenti possono revocare le autorizzazioni e scollegare la tua app dal proprio Account Google visitando la pagina https://myaccount.google.com/permissions. In alternativa, possono disconnettersi direttamente dalla tua app attivando una chiamata API che hai implementato. Il metodo precedente disconnect è stato sostituito dal metodo più recente revoke.

Quando un utente elimina il proprio account sulla tua piattaforma, è buona prassi utilizzare revoke per scollegare la tua app dal suo Account Google.

In precedenza, auth2.signOut() poteva essere utilizzato per gestire il logout dell'utente dalla tua app. Qualsiasi utilizzo di auth2.signOut() deve essere rimosso e la tua app deve gestire direttamente lo stato della sessione e lo stato di accesso dell'utente.

Stato della sessione e ascoltatori

La nuova libreria non mantiene lo stato di accesso o della sessione per la tua app web.

Lo stato di accesso di un Account Google e lo stato della sessione e di accesso della tua app sono concetti distinti e separati.

Lo stato di accesso dell'utente al proprio Account Google e alla tua app sono indipendenti tra loro, tranne durante il momento dell'accesso stesso, quando sai che l'utente si è autenticato correttamente ed ha eseguito l'accesso al proprio Account Google.

Quando Accedi con Google, One Tap o Accesso automatico sono inclusi sul tuo sito, gli utenti devono prima accedere al proprio Account Google per:

  • fornire il consenso alla condivisione del proprio profilo utente al momento della registrazione o dell'accesso al tuo sito,
  • e versioni successive per accedere alle visite di ritorno al tuo sito.

Gli utenti possono rimanere connessi, uscire o passare a un altro Account Google mantenendo attiva una sessione di accesso sul tuo sito web.

Ora sei responsabile della gestione diretta dello stato di accesso degli utenti della tua app web. In precedenza, Accedi con Google consentiva di monitorare lo stato della sessione dell'utente.

Rimuovi eventuali riferimenti a auth2.attachClickHandler() e ai relativi gestori di callback registrati.

In precedenza, gli ascoltatori venivano utilizzati per condividere le modifiche dello stato di accesso per l'Account Google di un utente. Gli ascoltatori non sono più supportati.

Rimuovi tutti i riferimenti a listen(), auth2.currentUser e auth2.isSignedIn.

Cookie

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 sezione In che modo Google utilizza i cookie.

Il cookie G_ENABLED_IDPS impostato dalla precedente libreria della piattaforma di accesso Google non viene più utilizzato.

La nuova libreria Servizi di identità Google può impostare facoltativamente questi cookie cross-domain in base alle tue opzioni di configurazione:

  • g_state memorizza lo stato di disconnessione dell'utente e viene impostato quando si utilizza il popup One Tap o l'accesso automatico,

  • g_csrf_token è un cookie di invio doppio utilizzato per prevenire gli attacchi CSRF e viene impostato quando viene chiamato l'endpoint di accesso. Il valore dell'URI di accesso può essere impostato esplicitamente o può essere predefinito l'URI della pagina corrente. L'endpoint di accesso può essere chiamato nelle seguenti condizioni quando si utilizzano:

    • API HTML con data-ux_mode=redirect o quando è impostato data-login_uri oppure

    • API JavaScript con ux_mode=redirect e dove google.accounts.id.prompt() non viene utilizzato per visualizzare One Tap o l'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 Visualizzare One Tap su più sottodomini per ulteriori istruzioni sull'utilizzo del cookie g_state.

Riferimento alla migrazione degli oggetti per l'accesso utente

Vecchio 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.
Oggetto GoogleAuth e metodi associati:
GoogleAuth.attachClickHandler() IdConfiguration.callback per data-callback in JS e HTML Sostituisci il vecchio con il nuovo.
GoogleAuth.currentUser.get() CredentialResponse Utilizza CredentialResponse, non più necessario.
GoogleAuth.currentUser.listen() Rimuovi. Lo stato di accesso corrente 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 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 può avvenire anche dalla pagina https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
GoogleAuth.isSignedIn.get() Rimuovi. Lo stato di accesso corrente 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 corrente 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 del DOM HTML dell'elemento g_id_signin o la 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 un Account Google è indipendente. Google non gestisce lo stato della sessione per la tua app.
GoogleAuth.then() Rimuovi. GoogleAuth è deprecato.
Oggetto GoogleUser e metodi associati:
GoogleUser.disconnect() google.accounts.id.revoke Sostituisci il vecchio con il nuovo. La revoca può avvenire anche dalla pagina https://myaccount.google.com/permissions
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() CredentialResponse Utilizza direttamente credential e i campi secondari anziché i metodi BasicProfile.
GoogleUser.getGrantedScopes() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
GoogleUser.getHostedDomain() CredentialResponse Utilizza invece direttamente credential.hd.
GoogleUser.getId() CredentialResponse Utilizza invece direttamente credential.sub.
GoogleUser.grantOfflineAccess() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
GoogleUser.grant() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
GoogleUser.hasGrantedScopes() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
GoogleUser.isSignedIn() Rimuovi. Lo stato di accesso corrente 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 OAuth 2.0.
Oggetto gapi.auth2 e metodi associati:
Oggetto gapi.auth2.AuthorizeConfig Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
Oggetto gapi.auth2.AuthorizeResponse Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
Oggetto gapi.auth2.AuthResponse Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
gapi.auth2.authorize() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
gapi.auth2.ClientConfig() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
gapi.auth2.getAuthInstance() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
gapi.auth2.init() Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
Oggetto gapi.auth2.OfflineAccessOptions Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
Oggetto gapi.auth2.SignInOptions Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
Oggetto gapi.signin2 e metodi associati:
gapi.signin2.render() Rimuovi. Il caricamento del DOM HTML dell'elemento g_id_signin o la chiamata JS a google.accounts.id.renderButton attiva l'accesso dell'utente a un Account Google.