Migrazione da Accedi con Google

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 carica apis.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 modulo gapi.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

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

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

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.

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

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

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 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() e getEmail() 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 quando data-login_uri è impostato oppure

  • L'API JavaScript con ux_mode=redirect e dove google.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