Eseguire la 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 precedente alla più recente libreria dei 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 ulteriori informazioni.

autentica e autorizza

L'autenticazione stabilisce chi è un utente, e comunemente definito accesso o registrazione dell'utente. L'autorizzazione è il processo di concessione o rifiuto dell'accesso a dati o risorse. Ad esempio, l'app richiede il consenso dell'utente per accedere al suo Google Drive.

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

Tuttavia, la libreria più recente separa i due processi per ridurre la complessità per gli sviluppatori di integrare gli Account Google nella 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 Eseguire 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 identità Google offre numerosi miglioramenti in termini di usabilità. Le caratteristiche principali includono:

  • Nuovi flussi di accesso automatico e One Tap più semplici con meno passaggi singoli,
  • 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 sito senza dover prima visitare la pagina di accesso o l'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 sito utilizzando solo HTML,
  • separazione tra l'autenticazione dell'accesso e l'autorizzazione e la condivisione dei dati utente, la complessità di un'integrazione OAuth 2.0 non è più necessaria per far accedere gli utenti al tuo sito,
  • 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,
  • un consolidamento delle 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 promessa e l'indiretto tramite le funzioni di stile getter è stato rimosso per semplicità.

Esempio di migrazione dell'accesso

Se stai eseguendo la migrazione dal pulsante Accedi con Google esistente e ti interessa soltanto far accedere gli utenti al tuo sito, la modifica più semplice è l'aggiornamento al nuovo pulsante personalizzato. A tale scopo, puoi scambiare le librerie JavaScript e aggiornare il codebase in modo da 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 stati sostituiti da un'unica nuova libreria JavaScript dei 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:

  • viene caricato il pulsante di accesso predefinito apis.google.com/js/platform.js,
  • l'immagine di un pulsante personalizzato carica apis.google.com/js/api:client.js e
  • Utilizzo diretto di gapi.client viene caricato apis.google.com/js/api.js.

Nella maggior parte dei casi, puoi continuare a utilizzare le credenziali ID client esistenti per le applicazioni web. Nell'ambito della migrazione, ti consigliamo di esaminare i nostri criteri OAuth 2.0 e utilizzare la console API di Google per verificare e, se necessario, aggiornare le seguenti impostazioni client:

  • le app di test e 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.

Identifica il codice interessato ed esegui il test

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

Nelle 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 stanno per essere ritirate, imposta il valore del cookie G_AUTH2_MIGRATION su informational. Facoltativamente, aggiungi i due punti seguiti da una coppia chiave-valore per registrare anche lo spazio di archiviazione della sessione. Dopo l'accesso e la ricezione delle credenziali, esamina o invia i log raccolti a un backend per analisi successive. 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. In questo modo è possibile testare il comportamento successivo al ritiro prima della data di applicazione.

G_AUTH2_MIGRATION valori possibili dei cookie:

  • enforced Non caricare il modulo gapi.auth2.
  • informational Registra l'utilizzo delle funzionalità deprecate 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, ti consigliamo di impostare questo cookie localmente durante lo sviluppo e il test, prima di utilizzarlo negli ambienti di produzione.

HTML e JavaScript

In questo scenario di accesso di sola autenticazione vengono mostrati codice di esempio e rendering del pulsante Accedi con Google esistente. Seleziona la modalità Popup o Reindirizzamento per vedere le differenze nella modalità di gestione della risposta di autenticazione tramite un callback JavaScript o dal reindirizzamento sicuro all'endpoint di accesso del server di backend.

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

Rendering eseguito

I nuovi attributi visivi semplificano il metodo precedente di creazione di un pulsante personalizzato, eliminano le chiamate a gapi.signin2.render() e non richiedono l'hosting e la gestione di immagini e asset visivi sul sito.

Accedi con Google

Accesso eseguito con Google

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

Il nuovo modo

Per utilizzare la nuova libreria in uno scenario di accesso di sola autenticazione, scegli tra la modalità Popup o Reindirizzamento e utilizza l'esempio di codice per sostituire la tua 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 nell'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>

Rendering eseguito

Utilizza gli attributi-visivi per personalizzare dimensioni, forma e colore del pulsante Accedi con Google. Mostra il popup One Tap insieme al pulsante Personalizzato per migliorare la percentuale di accesso.

Pulsante Accedi con Google Popup One Tap

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

In questo 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 libreria apis.google.com/js/platform.js e l'oggetto g-signin2 precedenti.

Oltre a visualizzare il 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 l'attrito per l'utente durante la registrazione e l'accesso.

Sebbene sia sconsigliato a causa del maggiore problema 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 equivalente a livello funzionale o combinare le API HTML e JavaScript sul tuo sito.

Per visualizzare in modo interattivo le opzioni di personalizzazione dei pulsanti, ad esempio il tipo di callback e attributi quali colore, dimensioni, forma, testo e tema, controlla il nostro Generatore di codice. Puoi utilizzarlo 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 semplice e intuitivo con cui gli utenti possono registrarsi o accedere al tuo sito. Consente di consentire l'accesso degli utenti direttamente da qualsiasi pagina del sito ed elimina la necessità che gli utenti visitino una pagina di accesso dedicata. In altre parole, questo riduce i problemi di registrazione e accesso offrendo agli utenti la flessibilità necessaria per registrarsi e accedere da pagine diverse da quella di accesso.

Per consentire l'accesso da qualsiasi pagina, ti consigliamo 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 effettuare la registrazione o l'accesso visualizzando il pulsante insieme ad altri pulsanti dei provider di identità federata e ai campi di immissione di nome utente e password.

Risposta token

Per accedere agli utenti non è più necessario conoscere o utilizzare i codici di autorizzazione, i token di accesso o i token di aggiornamento OAuth 2.0. Per condividere lo stato di accesso e il profilo utente, viene invece utilizzato un token ID JWT (JSON Web Token). Per semplificare l'operazione, non è più necessario utilizzare metodi di accesso in stile "getter" per lavorare con i dati del profilo utente.

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

  • al gestore di callback JavaScript basato su browser dell'utente in modalità popup, oppure
  • al server di backend tramite un reindirizzamento di 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(),
  • i riferimenti a BasicProfile e le chiamate associate ai metodi getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), getEmail() e
  • dell'oggetto AuthResponse.

Utilizza invece riferimenti diretti ai sottocampi 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 delle richieste tra siti (RSF) e di verificare il token ID Google sul server di backend.

Per capire meglio in che modo gli utenti interagiscono con il tuo sito, puoi utilizzare il campo select_by in CredentialResponse per determinare il risultato del consenso degli utenti 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 nella 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 scollegare la tua 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 precedente metodo disconnect è stato sostituito dal metodo revoke più recente.

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

In precedenza, auth2.signOut() poteva essere utilizzato per facilitare la gestione dell'uscita dell'utente dall'app. L'eventuale utilizzo di auth2.signOut() dovrebbe essere rimosso e l'app deve gestire direttamente lo stato della sessione utente e lo stato di accesso.

Stato della sessione e listener

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

Lo stato di accesso di un Account Google, così come lo stato della sessione e dell'accesso dell'app sono concetti distinti e separati.

Lo stato di accesso dell'utente al proprio Account Google e la tua app sono indipendenti l'uno dall'altro, tranne nel momento dell'accesso, quando sai che l'utente si è autenticato correttamente e ha eseguito l'accesso al proprio Account Google.

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

  • dà il consenso a condividere il suo profilo utente la prima volta che si registra o il primo accesso al tuo sito,
  • e successivamente per l'accesso per le visite di ritorno al tuo sito.

Gli utenti possono rimanere collegati, uscire dall'account o passare a un altro Account Google mentre mantengono una sessione attiva e in cui è stato eseguito l'accesso sul tuo sito web.

Ora sei responsabile della gestione diretta dello stato di accesso degli utenti della tua app web. In precedenza, la funzionalità Accedi con Google aiuta 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 utilizzati per condividere le modifiche allo stato di accesso all'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 fa un uso limitato dei cookie; di seguito viene fornita una descrizione di questi cookie. Consulta la sezione In che modo Google utilizza i cookie per ulteriori informazioni sugli altri tipi di cookie utilizzati da Google.

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

La nuova libreria dei Servizi di identità Google può facoltativamente impostare questi cookie interdominio in base alle opzioni di configurazione:

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

  • g_csrf_token è un cookie inviato due volte, 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 potrebbe corrispondere all'URI della pagina corrente come valore predefinito. L'endpoint di accesso può essere chiamato in queste condizioni quando utilizzi:

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

    • L'API JavaScript con ux_mode=redirect e in cui google.accounts.id.prompt() non viene utilizzata per visualizzare l'accesso One Tap o Accesso automatico.

Se disponi di un servizio che gestisce i cookie, assicurati di aggiungere i due nuovi cookie e di rimuovere quello precedente al termine della migrazione.

Se gestisci più domini o sottodomini, consulta l'articolo Visualizzare un tocco nei sottodomini per ulteriori istruzioni sull'uso del cookie g_state.

Riferimento alla migrazione degli oggetti per l'accesso degli utenti

Precedenti Novità Note
Librerie JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Sostituisci vecchio con nuovo.
apis.google.com/js/api.js accounts.google.com/gsi/client Sostituisci vecchio con nuovo.
Oggetto GoogleAuth e metodi associati:
GoogleAuth.attachClickHandler() IdConfiguration.callback per data-callback JS e HTML Sostituisci vecchio con nuovo.
GoogleAuth.currentUser.get() CredentialResponse Utilizza invece CredentialResponse, che 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 ottenere il consenso e l'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 vecchio con nuovo. La revoca potrebbe avvenire anche all'indirizzo https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di 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 ottenere il consenso e l'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 ottenere il consenso e l'accesso.
GoogleAuth.signIn() Rimuovi. Il caricamento HTML DOM 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 quello di 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 vecchio con nuovo. La revoca potrebbe avvenire anche all'indirizzo 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 i token di accesso e gli ambiti di 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 di OAuth 2.0.
GoogleUser.grant() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
GoogleUser.hasGrantedScopes() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di 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 ottenere il consenso e l'accesso.
GoogleUser.reloadAuthResponse() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
gapi.auth2 e i metodi associati:
Oggetto gapi.auth2.AutorizzaConfig Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
Oggetto gapi.auth2.AutorizzaResponse Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
Oggetto gapi.auth2.AuthResponse Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
gapi.auth2.authorized() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
gapi.auth2.ClientConfig() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
gapi.auth2.getAuthInstance() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
gapi.auth2.init() Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
Oggetto gapi.auth2.OfflineAccessOptions Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
Oggetto gapi.auth2.SignInOptions Rimuovi. Un token ID ha sostituito i token di accesso e gli ambiti di OAuth 2.0.
gapi.signin2 e metodi associati:
gapi.signin2.render() Rimuovi. Il caricamento HTML DOM dell'elemento g_id_signin o la chiamata JS a google.accounts.id.renderButton attiva l'accesso dell'utente a un Account Google.