Eseguire la migrazione da Accedi con Google

Questa guida ti aiuta a comprendere le modifiche necessarie e i passaggi da seguire per eseguire correttamente la migrazione delle librerie JavaScript dalla versione precedente di Accedi con Google libreria di Google Cloud alla più recente libreria Servizi di identità Google per l'autenticazione.

Se il client utilizza la libreria client dell'API di Google per JavaScript o altri librerie precedenti per l'autorizzazione, consulta Eseguire la migrazione a Google Identity Services per saperne di più.

Autenticazione e autorizzazione

L'autenticazione stabilisce chi è una persona e viene comunemente definita come registrazione o accesso dell'utente. L'autorizzazione è il processo di concessione o o negare l'accesso a dati o risorse. Ad esempio, la tua app richiede il consenso dell'utente ad accedere al suo Google Drive.

Come la precedente libreria di piattaforme Accedi con Google, la nuova versione di Google Identity La libreria di servizi è concepita per supportare sia l'autenticazione che l'autorizzazione i processi di machine learning.

Tuttavia, la libreria più recente separa i due processi per ridurre la complessità per consentire agli 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 l'articolo Come funziona l'autorizzazione utente e Esegui la migrazione ai Servizi di identità Google per assicurarti che la tua applicazione sia utilizzando le API nuove e migliorate.

Che cosa è cambiato

Per gli utenti, la nuova libreria Servizi di identità Google offre numerose a migliorare l'usabilità. I punti salienti includono:

  • Nuovi flussi One Tap e accesso automatico a basso attrito con meno utenti individuali passaggi,
  • un pulsante di accesso aggiornato con la personalizzazione dell'utente,
  • un branding coerente e un comportamento di accesso uniforme su tutto il web migliorano comprensione e fiducia,
  • rapidamente i contenuti; gli utenti possono registrarsi e accedere direttamente da qualsiasi luogo sul tuo sito senza dover prima visitare la pagina di accesso o dell'account.

Per gli sviluppatori, ci siamo concentrati sulla riduzione della complessità, sul miglioramento della sicurezza e rendere l'integrazione il più rapida possibile. Ecco alcuni di questi miglioramenti:

  • L'opzione per aggiungere l'accesso utente ai contenuti statici del tuo sito utilizzando HTML,
  • separazione tra l'autenticazione dell'accesso e l'autorizzazione e la condivisione dati utente, non è più necessaria la complessità di un'integrazione OAuth 2.0 per far accedere gli utenti al tuo sito,
  • entrambe le modalità popup e di reindirizzamento continuano a essere supportate, ma OAuth di Google L'infrastruttura 2.0 ora reindirizza all'endpoint di accesso del server di backend,
  • le funzionalità di entrambe le identità Google precedenti e le librerie JavaScript delle API di Google in un'unica nuova libreria,
  • per le risposte all'accesso, ora puoi decidere se utilizzare Le funzioni di stile getter Promise e indiretta rimosso per semplicità.

Esempio di migrazione dell'accesso

Se stai eseguendo la migrazione dal pulsante Accedi con Google esistente e ti trovi solo interessati ad accedere al tuo sito, la modifica più diretta è per passare al nuovo pulsante personalizzato. A questo scopo, scambia librerie JavaScript e l'aggiornamento del codebase per l'utilizzo di 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 per l'autenticazione e l'autorizzazione degli utenti. Sono state sostituita 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 gli accessi vengono caricati tutti da apis.google.com. Per identificare più facilmente le località dove la libreria precedente poteva essere inclusa nel tuo sito, in genere:

  • il pulsante di accesso predefinito carica apis.google.com/js/platform.js,
  • viene caricata una grafica di un pulsante personalizzato 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 continuare a utilizzare l'ID client dell'applicazione web esistente. e credenziali. Come parte della migrazione, ti consigliamo di consultare le nostre Criteri di OAuth 2.0 e utilizza la console API di Google. per confermare e, se necessario, aggiornare le seguenti impostazioni del client:

  • le app di test e di produzione utilizzano progetti separati e avranno 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ò aiutarti a individuare il codice interessato e a testare dopo il ritiro comportamento degli utenti.

Nelle app di grandi dimensioni o complesse, può essere difficile trovare tutto il codice interessato dal il ritiro del modulo gapi.auth2. Per registrare l'utilizzo esistente di a breve funzionalità deprecate alla console, imposta il valore dell'attributo G_AUTH2_MIGRATION a informational. Facoltativamente, aggiungi i due punti seguiti da una coppia chiave-valore e accedere anche allo spazio di archiviazione sessione. Dopo l'accesso e la ricezione di per esaminare le credenziali o inviare i log raccolti a un backend per analisi successive. Per Ad esempio, informational:showauth2use salva l'origine e l'URL in un spazio di archiviazione della sessione chiave denominata showauth2use.

Per verificare il comportamento dell'app quando il modulo gapi.auth2 non è più caricato, imposta il valore del cookie G_AUTH2_MIGRATION in enforced. Ciò consente di testare comportamento successivo al ritiro prima della data di applicazione.

Possibili valori dei cookie G_AUTH2_MIGRATION:

  • enforced Non caricare il modulo gapi.auth2.
  • informational Registra l'utilizzo delle funzionalità deprecate nella console JS. Registra anche allo spazio di archiviazione della sessione quando è impostato un nome di 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 in ambienti di produzione.

HTML e JavaScript

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

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

Esegui il rendering del pulsante Accedi con Google, terminando con una chiamata AJAX dall'interfaccia utente browser all'endpoint di accesso ai 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>

Sottoposto a rendering

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

Accedi con Google

Accesso eseguito da Google

Testo del pulsante per gli aggiornamenti dello stato di accesso dell'utente.

Il nuovo modo

Per utilizzare la nuova libreria in uno scenario di accesso solo per l'autenticazione, seleziona dalla modalità popup o di reindirizzamento e utilizzare l'esempio di codice per sostituire un'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 il tuo endpoint di accesso come specificato da data-login_url . In precedenza, eri responsabile dell'operazione POST e del parametro. La nuova libreria pubblica il token ID nel tuo endpoint nella sezione Parametro credential. Infine, verifica il token ID sul backend server web.

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

Sottoposto a rendering

Utilizza visual-attributes per personalizzare il pulsante Accedi con Google dimensioni, forma, colore. Mostra il popup One Tap insieme al prompt personalizzato per migliorare la percentuale di accesso.

Accedi con Google
. Un tocco
popup

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, include il nome, l'indirizzo email e l'immagine del profilo dell'utente.

In questo esempio basato solo sull'autenticazione, il nuovo accounts.google.com/gsi/client libreria, classe g_id_signin e oggetto g_id_onload sostituiscono il precedente libreria apis.google.com/js/platform.js e oggetto g-signin2.

Oltre a eseguire il rendering del nuovo pulsante personalizzato, il codice di esempio mostra il nuovo popup One Tap. Ovunque mostri il pulsante personalizzato, ti consigliamo vivamente di mostrare anche il popup One Tap per ridurre in caso di problemi durante la registrazione e l'accesso.

Sebbene non sia consigliato a causa della maggiore difficoltà di accesso, il nuovo il pulsante personalizzato può essere mostrato da solo, senza visualizzare contemporaneamente 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 a del tuo sito web. In alternativa, puoi utilizzare l'equivalente funzionale API JavaScript oppure combina e abbina le API HTML e JavaScript nel tuo sito.

Per visualizzare in modo interattivo le opzioni di personalizzazione dei pulsanti, ad esempio Tipo di callback e come colore, dimensione, forma, testo e tema, controlla il nostro Codice generatore. Può essere usato per confrontare rapidamente diverse opzioni e generare Snippet HTML da utilizzare sul tuo sito.

Accedi da qualsiasi pagina con un tocco

One Tap è un nuovo modo semplice per consentire agli utenti di registrarsi o accedere al tuo sito. Ti permette di consentire l'accesso degli utenti direttamente da qualsiasi pagina del tuo sito e elimina la necessità per gli utenti di visitare una pagina di accesso dedicata. In altre parole, Ciò riduce le difficoltà legate a registrazioni e accessi offrendo agli utenti la flessibilità di accesso e registrazione da pagine diverse dalla 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 anche di aggiungere g_id_signin, che mostra l'accesso personalizzato , solo nelle pagine di accesso o di gestione dell'account utente. Offri agli utenti la possibilità di scegliere per la registrazione o l'accesso mostrando il pulsante accanto ad altre i pulsanti del provider di identità e i campi di immissione di nome utente e password.

Risposta del token

L'accesso degli utenti non richiede più la conoscenza o l'utilizzo di OAuth 2.0 codici di autorizzazione, token di accesso o token di aggiornamento. Invece un token web JSON (JWT) ID Token viene utilizzato per condividere lo stato di accesso e il profilo utente. Come semplifichiamo ulteriormente, non devi più usare "getter" stile metodi della funzione di accesso per lavorare con i dati del profilo utente.

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

  • al gestore callback JavaScript basato su browser dell'utente in modalità popup oppure
  • al tuo server di backend tramite un reindirizzamento 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(), getEmail() e
  • dell'oggetto AuthResponse.

Utilizza invece riferimenti diretti ai campi secondari credential nel nuovo JWT CredentialResponse in modo che interagisca con i dati del profilo utente.

Inoltre, e solo per la modalità di reindirizzamento, assicurati di impedire le richieste tra siti Falsificazione (CSRF) e verifica 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 di CredentialResponse può essere utilizzato per determinare l'utente il risultato del consenso e lo specifico flusso di accesso 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 profilo dell'utente condiviso con la tua app in un payload credenziali di token ID. La revoca dell'accesso a questo profilo equivale a revocare un token di accesso nel 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 un'API. che implementi; il metodo disconnect precedente è stato sostituito dal nuovo metodo revoke.

Quando un utente elimina il proprio account sulla piattaforma, è consigliabile utilizzarlo 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 la tua app deve gestire direttamente lo stato della sessione utente e lo stato dell'accesso.

Stato sessione e listener

La nuova libreria non mantiene lo stato di accesso o della sessione per il tuo sito web dell'app.

Lo stato di accesso di un Account Google, nonché lo stato della sessione e "accesso" sono concetti distinti e separati.

Lo stato di accesso dell'utente al proprio Account Google e la tua app sono indipendenti da ogni l'altro, tranne durante il momento dell'accesso stesso, quando sai che l'utente ha autenticata correttamente e ha eseguito l'accesso al proprio Account Google.

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

  • Fornire il consenso a condividere il proprio profilo utente alla prima registrazione o di accedere al tuo sito,
  • e in un secondo momento per accedere alle visite di ritorno al tuo sito.

Gli utenti potrebbero rimanere collegati all'account, uscire dall'account o passare a un altro Account Google mantenendo una sessione attiva con accesso al sito web.

Ora sei responsabile della gestione diretta dello stato di accesso per gli utenti di la tua app web. In precedenza, Accedi con Google aiutava a monitorare la sicurezza stato della sessione.

Rimuovi tutti i riferimenti a auth2.attachClickHandler() e ai relativi dati registrati e i gestori di callback.

In precedenza, i Listener venivano utilizzati per condividere le modifiche allo stato di accesso per un l'Account Google dell'utente. I listener non sono più supportati.

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

Cookie

Accedi con Google fa un uso limitato dei cookie. Una descrizione di questi cookie . Leggi l'articolo 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 libreria della piattaforma Accedi con Google precedente non viene più utilizzato.

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

  • g_state memorizza lo stato di disconnessione dell'utente e viene impostato quando si usa One Tap popup o 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 in modo esplicito o può utilizzare per impostazione predefinita l'URI della pagina corrente. Il tuo l'endpoint di accesso può essere chiamato in queste condizioni quando si utilizza:

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

    • API JavaScript con ux_mode=redirect e dove google.accounts.id.prompt() non è usato per visualizzare One Tap o Accesso automatico.

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

Se gestisci più domini o sottodomini, consulta l'articolo Display One Tap su Sottodomini per ulteriori istruzioni sull'utilizzo del cookie g_state.

Riferimento alla migrazione degli oggetti per l'accesso degli utenti

Vecchio Nuovo Note
Librerie JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Sostituisci il vecchio con quello nuovo.
apis.google.com/js/api.js accounts.google.com/gsi/client Sostituisci il vecchio con quello nuovo.
Oggetto GoogleAuth e metodi associati:
GoogleAuth.attachClickHandler() IdConfiguration.callback per data-callback JS e HTML Sostituisci il vecchio con quello nuovo.
GoogleAuth.currentUser.get() CredentialResponse Usa CredentialResponse perché 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 consentire il consenso e i momenti di accesso. La select_by in CredentialResponse può essere utilizzato per determinare il risultato consenso dell'utente e il metodo di accesso utilizzato.
GoogleAuth.disconnect() google.accounts.id.revoke Sostituisci il vecchio con quello nuovo. La revoca può avvenire anche all'indirizzo 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 consentire 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 consentire il consenso e i momenti di accesso.
GoogleAuth.signIn() Rimuovi. Caricamento del DOM HTML della classe g_id_signin o una 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 è stato ritirato.
Oggetto GoogleUser e metodi associati:
GoogleUser.disconnect() google.accounts.id.revoke Sostituisci il vecchio con quello nuovo. La revoca può avvenire anche all'indirizzo https://myaccount.google.com/permissions
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() CredentialResponse Usa direttamente i campi 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 Usa direttamente credential.hd.
GoogleUser.getId() CredentialResponse Usa 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 consentire 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.PermissionsConfig Rimuovi. Un token ID ha sostituito gli ambiti e i token di accesso OAuth 2.0.
Oggetto gapi.auth2.AuthorizedResponse 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. Caricamento del DOM HTML della classe g_id_signin o una chiamata JS a google.accounts.id.renderButton attiva l'accesso dell'utente a un Account Google.