Eseguire la migrazione da Accedi con Google

Questa guida ti aiuta a comprendere le modifiche e i passaggi necessari per eseguire la migrazione delle librerie JavaScript dalla precedente libreria della piattaforma Accedi con Google alla nuova libreria Servizi di identità Google 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 Migrazione ai servizi di identità Google per saperne di più.

Autenticazione e autorizzazione

L'autenticazione stabilisce l'identità di una persona e viene comunemente definita registrazione o accesso 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 al suo Google Drive.

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

Tuttavia, la nuova libreria separa i due processi per ridurre la complessità dell'integrazione degli Account Google con la tua app per gli sviluppatori.

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 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 Servizi di identità Google offre numerosi miglioramenti dell'usabilità. Ecco alcuni dei momenti salienti:

  • Nuovi flussi One Tap e di accesso automatico a basso attrito con meno passaggi individuali.
  • un pulsante di accesso aggiornato con la 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 punto 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 rendere l'integrazione il più rapida possibile. Alcuni di questi miglioramenti includono:

  • 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 OAuth 2.0 non è più necessaria per consentire agli utenti di accedere al tuo sito.
  • entrambe le modalità popup e reindirizzamento continuano a essere supportate, ma l'infrastruttura OAuth 2.0 di Google ora reindirizza all'endpoint di accesso del 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 Promise e l'indirezione tramite le funzioni di tipo getter è stata rimossa per semplicità.

Esempio di migrazione dell'accesso

Se esegui la migrazione dal pulsante Accedi con Google esistente e ti interessa solo consentire agli utenti di accedere al tuo sito, la modifica più semplice è l'aggiornamento al nuovo pulsante personalizzato. A questo scopo, scambia le librerie JavaScript e aggiorna la base di codice per utilizzare un nuovo oggetto di accesso.

Librerie e configurazione

La precedente libreria della piattaforma 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 state sostituite da una nuova libreria JavaScript di Servizi di identità Google: 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 libreria precedente potrebbe essere inclusa nel tuo sito, in genere:

  • il pulsante di accesso predefinito carica apis.google.com/js/platform.js,
  • viene caricata una grafica del pulsante personalizzato apis.google.com/js/api:client.js e
  • utilizzo diretto dei gapi.clientcarichiapis.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 confermare e, se necessario, aggiornare le seguenti impostazioni del client:

  • le tue app di test e di produzione utilizzano progetti separati e hanno ID client propri,
  • 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 interessato ed eseguire il test

Un cookie di debug può aiutarti a individuare il codice interessato e a testare il comportamento post-deprecazione.

Nelle app grandi o complesse, potrebbe essere difficile trovare tutto il codice interessato dal ritiro del modulo gapi.auth2. Per registrare l'utilizzo esistente delle funzionalità che verranno ritirate a breve nella console, imposta il valore del cookie G_AUTH2_MIGRATION su informational. (Facoltativo) Aggiungi i due punti seguiti da un valore chiave per registrare anche nello session storage. Dopo l'accesso e la ricezione delle credenziali, esamina o invia i log raccolti a un backend per un'analisi successiva. Ad esempio, informational:showauth2use salva l'origine e l'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. Ciò consente di testare il comportamento post-ritiro prima della data di applicazione.

Valori possibili del cookie G_AUTH2_MIGRATION:

  • enforced Non caricare il modulo gapi.auth2.
  • informational Registra l'utilizzo delle funzionalità ritirate nella console JS. Registra anche nell'archiviazione della sessione quando viene 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 con autenticazione, vengono mostrati il codice di esempio e i rendering del pulsante Accedi con Google esistente. Seleziona la modalità popup o 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 al server di backend.

Il modo precedente

Visualizza 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

Visualizza il pulsante Accedi con Google, terminando con una chiamata AJAX dal browser dell'utente all'endpoint di accesso dei 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>

Eseguito il rendering

I nuovi attributi visivi semplificano il metodo precedente di creazione di un pulsante personalizzato, eliminano le chiamate a gapi.signin2.render() e la necessità di ospitare e gestire immagini e risorse visive sul tuo sito.

Accedi con Google

Accesso a Google

Testo del pulsante degli aggiornamenti dello stato di accesso utente.

Il nuovo modo

Per utilizzare la nuova libreria in uno scenario di accesso solo con autenticazione, seleziona la modalità popup o reindirizzamento e utilizza l'esempio di codice 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 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 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>

Eseguito il rendering

Utilizza visual-attributes 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 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 nelle visite di ritorno, il pulsante personalizzato include il nome, l'email e l'immagine del profilo dell'utente.

In questo esempio solo di 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 visualizzi il pulsante personalizzato, ti consigliamo vivamente di visualizzare anche il popup One Tap per ridurre al minimo l'attrito degli utenti durante la registrazione e l'accesso.

Sebbene non sia consigliato a causa del maggiore attrito di accesso, il nuovo pulsante personalizzato può essere visualizzato 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 tuo sito web. In alternativa, puoi utilizzare l'API JavaScript, che ha una funzionalità equivalente, oppure combinare le 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, dimensione, 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 gli utenti di registrarsi o accedere al tuo sito. 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, riduce le difficoltà di registrazione e accesso dando agli utenti la flessibilità di registrarsi e accedere da pagine diverse da quella di accesso.

Per attivare l'accesso da qualsiasi pagina, ti abbiamo consigliato di includere g_id_onload in un'intestazione, un piè di pagina o 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 dell'account utente. Offri agli utenti la possibilità di registrarsi o accedere visualizzando il pulsante insieme ad altri pulsanti del provider di identità federata e ai campi di inserimento di nome utente e password.

Risposta del token

L'accesso degli utenti non richiede più la comprensione o l'utilizzo di codici di autorizzazione, token di accesso o 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. Per semplificare ulteriormente la procedura, non è più necessario utilizzare metodi di accesso in stile "getter" per lavorare con i dati del profilo utente.

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

  • al gestore di 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 a getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), metodi getEmail() e
  • utilizzo 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, e solo per la modalità di reindirizzamento, assicurati di impedire la falsificazione di richieste tra siti (CSRF) e di verificare il token ID Google sul 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 il risultato 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 libreria di accesso precedente.

Gli utenti possono revocare le autorizzazioni e disconnettere 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 implementi; il metodo precedente disconnect è stato sostituito dal nuovo metodo revoke.

Quando un utente elimina il proprio account sulla tua piattaforma, la best practice è utilizzare revoke per disconnettere la tua app dal suo Account Google.

In precedenza, auth2.signOut() poteva essere utilizzato per gestire la disconnessione degli utenti 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 per utente.

Stato della sessione e ascoltatori

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, lo stato della sessione e lo stato di accesso dell'app sono concetti distinti e separati.

Lo stato di accesso dell'utente al proprio Account Google e alla tua app sono indipendenti l'uno dall'altro, tranne durante il momento dell'accesso stesso, quando sai che l'utente ha eseguito l'autenticazione e ha eseguito l'accesso al proprio Account Google.

Quando sul tuo sito sono inclusi Accedi con Google, One Tap o l'accesso automatico, 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 in un secondo momento per l'accesso durante le visite di ritorno al tuo sito.

Gli utenti possono rimanere connessi, disconnettersi o passare a un altro Account Google mantenendo una sessione attiva e connessa sul tuo sito web.

Ora sei responsabile della gestione diretta dello stato di accesso per gli utenti della tua app web. In precedenza, Accedi con Google 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 listener venivano utilizzati per condividere le modifiche dello stato di accesso per l'Account Google di un utente. I listener non sono più supportati.

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

Cookie

Accedi con Google utilizza in modo limitato i 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 Google Sign-In non viene più utilizzato.

La nuova libreria Servizi di identità Google può impostare facoltativamente questi cookie cross-domain in base alle 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 a doppio invio utilizzato per prevenire attacchi CSRF e viene impostato quando viene chiamato l'endpoint di accesso. Il valore dell'URI di accesso può essere impostato in modo esplicito o può essere impostato come predefinito sull'URI della pagina corrente. L'endpoint di accesso potrebbe essere chiamato in queste condizioni quando utilizzi:

    • API HTML con data-ux_mode=redirect o quando data-login_uri è impostato 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 degli utenti

Precedente 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 JS e HTML data-callback Sostituisci il vecchio con il nuovo.
GoogleAuth.currentUser.get() CredentialResponse Utilizza invece 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 i momenti di consenso e accesso. Il campo select_by in CredentialResponse può essere utilizzato per determinare l'esito 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 i token di accesso e gli ambiti OAuth 2.0.
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 i momenti di consenso e 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 i momenti di consenso e 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 sono indipendenti. 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 relativi campi secondari anziché i metodi BasicProfile.
GoogleUser.getGrantedScopes() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti 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 i token di accesso e gli ambiti OAuth 2.0.
GoogleUser.grant() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
GoogleUser.hasGrantedScopes() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
GoogleUser.isSignedIn() Rimuovi. Lo stato di accesso attuale di un utente su Google non è disponibile. Gli utenti devono aver eseguito l'accesso a Google per i momenti di consenso e accesso.
GoogleUser.reloadAuthResponse() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
Oggetto gapi.auth2 e metodi associati:
Oggetto gapi.auth2.AuthorizeConfig Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
Oggetto gapi.auth2.AuthorizeResponse Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
Oggetto gapi.auth2.AuthResponse Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
gapi.auth2.authorize() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
gapi.auth2.ClientConfig() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
gapi.auth2.getAuthInstance() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
gapi.auth2.init() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
Oggetto gapi.auth2.OfflineAccessOptions Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti OAuth 2.0.
Oggetto gapi.auth2.SignInOptions Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti 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.