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 dei 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 libreria della piattaforma Accedi con Google precedente, la nuova libreria Google Identity Services è progettata per supportare sia i processi di autenticazione che 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 Servizi di identità Google offre numerosi miglioramenti dell'usabilità. I punti salienti includono:

• 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,
• rapidamente ai contenuti; gli utenti possono registrarsi e accedere direttamente da qualsiasi punto del sito senza dover prima visitare la 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,
• la separazione tra l'autenticazione dell'accesso e l'autorizzazione e la condivisione dei dati utente, la complessità dell'integrazione OAuth 2.0 non è più necessaria per consentire agli utenti di accedere 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 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à.

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 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 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 tutti 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 una grafica 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 ID client dell'applicazione web esistenti. 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.

Identifica il codice interessato e testa

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 delle funzionalità che verranno presto ritirate, 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 dei cookie di G_AUTH2_MIGRATION:

• enforced Non caricare il modulo gapi.auth2.
• informational Registra l'utilizzo delle funzionalità deprecate nella console JS. Esegui anche il logging nell'archiviazione della sessione quando è impostato un nome facoltativo della chiave: 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 solo per l'autenticazione, vengono mostrati codice di esempio e rendering del pulsante di accesso 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 un reindirizzamento sicuro all'endpoint di accesso del server di backend.

Il metodo precedente

<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 scenario di accesso solo per l'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 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'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 scegliere tra diverse opzioni di 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. Inoltre, non è più necessario utilizzare metodi di accesso in 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.

Consenso degli utenti e revoca dell'autorizzazione

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 è equivalente alla revoca di un token di accesso nella raccolta 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, è consigliabile utilizzare revoke per scollegare la tua app dal suo Account Google.

In precedenza, potevi utilizzare auth2.signOut() per gestire la uscita degli utenti dalla tua app. Deve essere rimosso qualsiasi utilizzo di auth2.signOut() e l'app deve gestire direttamente lo stato della sessione e dello stato di accesso dell'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 e 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 alla tua app sono indipendenti l'uno dall'altro, tranne al momento dell'accesso, in cui sai che l'utente si è autenticato correttamente e 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 per gli utenti della tua app web. In precedenza, Accedi con Google aiutava a 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. 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 descritta la relativa tipologia. Consulta Modalità di utilizzo dei cookie da parte di Google per ulteriori informazioni sugli altri tipi di cookie utilizzati da Google.

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

  • 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 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 Visualizzare One Tap su più sottodomini per ulteriori istruzioni sull'utilizzo del cookie g_state.

Riferimento alla migrazione degli oggetti per l'accesso utente