Accedi con Google con le API FedCM

Questa guida illustra l'adozione delle API FedCM da parte della libreria della piattaforma di accesso di Google. Gli argomenti includono la Cronologia e i Passaggi successivi per un aggiornamento della raccolta compatibile con le versioni precedenti, come eseguire una valutazione dell'impatto e verificare che l'accesso degli utenti continui a funzionare come previsto e, se necessario, le istruzioni per aggiornare l'app web. Sono inoltre trattate le opzioni per gestire il periodo di transizione e come richiedere assistenza.

Stato della raccolta

Le nuove app web non possono utilizzare la libreria della piattaforma di accesso Google ritirata, mentre le app che la utilizzano possono continuare a farlo fino a nuova comunicazione. Non è stata stabilita una data di ritiro definitiva (ritiro) per la raccolta. Per saperne di più, consulta la sezione Ritiro del supporto e ritiro del prodotto.

Un aggiornamento compatibile con le versioni precedenti aggiunge le API FedCM alla libreria di Accesso Google. Sebbene la maggior parte delle modifiche sia trasparente, l'aggiornamento introduce differenze per quanto riguarda i prompt per l'utente, permissions-policy per gli iframe e il Criterio di sicurezza del contenuto (CSP). Queste modifiche potrebbero influire sulla tua app web e richiedere modifiche al codice dell'applicazione e alla configurazione del sito.

Durante il periodo di transizione, un'opzione di configurazione controlla se le API FedCM vengono utilizzate o meno durante l'accesso dell'utente.

Dopo il periodo di transizione, le API FedCM sono obbligatorie per tutte le app web che utilizzano la libreria di Accedi con Google.

Cronologia

Ultimo aggiornamento: settembre 2024

Di seguito sono riportate le date e le modifiche che influiscono sul comportamento di accesso degli utenti:

  • Marzo 2023 Ritiro del supporto per la libreria della piattaforma di Accedi con Google.
  • Inizia il periodo di transizione di luglio 2024 e viene aggiunto il supporto delle API FedCM alla libreria della piattaforma Accedi con Google. Per impostazione predefinita, Google controlla la percentuale delle richieste di accesso degli utenti che utilizzano FedCM durante questo periodo. Le app web possono aggiustare esplicitamente questo comportamento con il parametro use_fedcm.
  • Adesione obbligatoria a marzo 2025 delle API FedCM da parte della libreria della piattaforma Accedi con Google, dopodiché il parametro use_fedcm viene ignorato e tutte le richieste di accesso utente utilizzano FedCM.

Passaggi successivi

Hai a disposizione tre opzioni:

  1. Esegui una valutazione dell'impatto e, se necessario, aggiorna la tua app web. Questo approccio valuta se le funzionalità che richiedono modifiche alla tua app web sono in uso. Le istruzioni sono riportate nella sezione successiva di questa guida.
  2. Passa alla libreria dei Servizi di identità Google (GIS). Ti consigliamo vivamente di passare alla libreria di accesso più recente e supportata. Per farlo, segui queste istruzioni.
  3. Non fare niente. La tua app web verrà aggiornata automaticamente quando la libreria Accedi con Google passerà alle API FedCM per l'accesso degli utenti. Questa è la procedura meno impegnativa, ma esiste il rischio che gli utenti non riescano ad accedere alla tua app web.

Eseguire una valutazione dell'impatto

Segui queste istruzioni per determinare se la tua app web può essere aggiornata senza problemi tramite un aggiornamento compatibile con le versioni precedenti o se sono necessarie modifiche per evitare che gli utenti non riescano ad accedere quando la libreria della piattaforma di accesso Google adotterà completamente le API FedCM.

Configurazione

Per utilizzare FedCM durante l'accesso dell'utente sono necessarie le API del browser e la versione più recente della libreria della piattaforma Accedi con Google.

Prima di procedere:

  • Esegui l'aggiornamento alla versione più recente di Chrome per computer. Chrome per Android richiede la release M128 o successive e non può essere testato utilizzando versioni precedenti.
  • Imposta use_fedcm su true quando inizili la libreria della piattaforma Accedi con Google nella tua app web. In genere, l'inizializzazione ha il seguente aspetto:
    • gapi.client.init({use_fedcm: true}), oppure
    • gapi.auth2.init({use_fedcm: true}), oppure
    • gapi.auth2.authorize({use_fedcm: true}).
  • Convalida le versioni memorizzate nella cache della libreria della piattaforma Accedi con Google. Di solito questo passaggio non è necessario perché la versione più recente della libreria viene scaricata direttamente nel browser includendo api.js, client.js o platform.js in un tag <script src> (la richiesta può utilizzare uno di questi nomi del bundle per la libreria).

  • Conferma le impostazioni OAuth per il tuo ID client OAuth:

    1. Apri la pagina Credenziali di

    2. Verifica che l'URI del tuo sito web sia incluso nelle Origini JavaScript autorizzate. L'URI include solo lo schema e il nome host completamente qualificato. Ad esempio, https://www.example.com.

    3. Facoltativamente, le credenziali possono essere restituite utilizzando un reindirizzamento a un endpoint ospitato da te anziché tramite un callback JavaScript. In questo caso, verifica che gli URI di reindirizzamento siano inclusi negli URI di reindirizzamento autorizzati. Gli URI di reindirizzamento includono lo schema, il nome host completo e il percorso e devono essere conformi alle regole di convalida degli URI di reindirizzamento. Ad esempio, https://www.example.com/auth-receiver.

Test

Dopo aver seguito le istruzioni nella sezione Configurazione:

Individuare la richiesta della raccolta di Accesso a Google

Verifica se sono necessarie modifiche a permissions-policy e Content Security Policy esaminando la richiesta per la libreria della piattaforma Accedi con Google. Per farlo, individua la richiesta utilizzando il nome e l'origine della libreria:

  • In Chrome, apri il riquadro Rete di DevTools e ricarica la pagina.
  • Utilizza i valori nelle colonne Domain (Dominio) e Name (Nome) per individuare la richiesta della biblioteca:
    • Il dominio è apis.google.com e
    • Il nome è api.js, client.js o platform.js. Il valore specifico di Nome dipende dal pacchetto di librerie richiesto dal documento.

Ad esempio, filtra in base a apis.google.com nella colonna Dominio e platform.js nella colonna Nome.

Controlla le autorizzazioni-policy iframe

Il tuo sito potrebbe utilizzare la libreria della piattaforma Accedi con Google all'interno di un iframe cross-origin. In questo caso, è necessario un aggiornamento.

Dopo aver seguito le istruzioni per individuare la richiesta della libreria di Accedi con Google, seleziona la richiesta della libreria di Accedi con Google nel pannello Rete di DevTools e individua l'intestazione Sec-Fetch-Site nella sezione Intestazioni richiesta della scheda Intestazioni. Se il valore dell'intestazione è:

  • same-siteo same-origin, i criteri cross-origin non vengono applicati e non sono necessarie modifiche.
  • cross-origin potrebbero essere necessarie se viene utilizzato un iframe.

Per verificare se è presente un iframe:

  • Seleziona il riquadro Elementi in Chrome DevTools e
  • Usa Ctrl-F per trovare un iframe nel documento.

Se viene trovato un iframe, controlla il documento per verificare la presenza di chiamate alle funzioni gapi.auth2 o alle direttive script src che caricano la libreria di Accedi con Google all'interno dell'iframe. In questo caso:

Ripeti questa procedura per ogni iframe nel documento. Gli iframe possono essere nidificati, quindi assicurati di aggiungere la direttiva allow a tutti gli iframe principali circostanti.

Controllare i criteri di sicurezza del contenuto

Se il tuo sito utilizza i criteri di sicurezza del contenuto, potresti dover aggiornare il CSP per consentire l'utilizzo della raccolta di Accesso Google.

Dopo aver seguito le istruzioni per individuare la richiesta della libreria di Accedi con Google, seleziona la richiesta della libreria di Accedi con Google nel pannello Rete di DevTools e individua l'intestazione Content-Security-Policy nella sezione Intestazioni di risposta della scheda Intestazioni.

Se l'intestazione non viene trovata, non sono necessarie modifiche. In caso contrario, controlla se alcune di queste istruzioni CSP sono definite nell'intestazione CSP e aggiornale nel seguente modo:

  • Aggiunta di https://apis.google.com/js/, https://accounts.google.com/gsi/ e https://acounts.google.com/o/fedcm/ a qualsiasi direttiva connect-src, default-src o frame-src.

  • Aggiunta di https://apis.google.com/js/bundle-name.js all'istruzione script-src. Sostituisci bundle-name.js con api.js, client.js o platform.jsin base al pacchetto di librerie richiesto dal documento.

Controllare se sono state apportate modifiche alla richiesta all'utente

Esistono alcune differenze nel comportamento della richiesta all'utente: FedCM aggiunge una finestra di dialogo modale visualizzata dal browser e aggiorna i requisiti di attivazione dell'utente.

Immagine della finestra di dialogo modale di FedCM

Controlla il layout del tuo sito per verificare che i contenuti sottostanti possano essere sovrapposti in sicurezza e oscurati temporaneamente dalla finestra di dialogo modale del browser. In caso contrario, potresti dover modificare il layout o la posizione di alcuni elementi del tuo sito web.

Attivazione utente

FedCM include requisiti aggiornati per l'attivazione degli utenti. La pressione di un pulsante o il clic su un link sono esempi di gesti dell'utente che consentono alle origini di terze parti di effettuare richieste di rete o di memorizzare dati. Con FedCM, il browser richiede il consenso dell'utente quando:

  • un utente accede per la prima volta a un'app web utilizzando una nuova istanza del browser oppure
  • Viene chiamato GoogleAuth.signIn.

Attualmente, se l'utente ha già eseguito l'accesso al tuo sito web, puoi ottenere i dati di accesso dell'utente durante l'inizializzazione della libreria di Accesso Google utilizzando gapi.auth2.init, senza ulteriori interazioni dell'utente. Questa operazione non è più possibile, a meno che l'utente non abbia prima completato almeno una volta il flusso di accesso a FedCM.

Se attivi FedCM e chiami GoogleAuth.signIn, la volta successiva che lo stesso utente visita il tuo sito web, GoogleAuth.signIn può ottenere le informazioni di accesso dell'utente durante l'inizializzazione senza alcuna interazione da parte dell'utente.gapi.auth2.init

Casi d'uso comuni

La documentazione per gli sviluppatori della libreria Google Sign-In include guide e esempi di codice per casi d'uso comuni. Questa sezione illustra in che modo FedCM influisce sul loro comportamento.

  • Integrare Accedi con Google nella tua app web

    In questa demo, un elemento <div> e una classe visualizzano il pulsante e, per gli utenti che hanno già eseguito l'accesso, l'evento onload della pagina restituisce le credenziali dell'utente. L'interazione dell'utente è necessaria per accedere e stabilire una nuova sessione.

    L'inizializzazione della libreria viene eseguita dalla classe g-signin2 che chiama gapi.load e gapi.auth2.init.

    Un gesto dell'utente, un evento <div> elemento onclick, chiama auth2.signIn durante l'accesso o auth2.signOut al momento della disconnessione.

  • Creare un pulsante Accedi con Google personalizzato

    Nella prima demo, gli attributi personalizzati vengono utilizzati per controllare l'aspetto del pulsante di accesso e, per gli utenti che hanno già eseguito l'accesso, l'evento pagina onload restituisce le credenziali utente. L'interazione dell'utente è necessaria per accedere e stabilire una nuova sessione.

    L'inizializzazione della raccolta viene eseguita tramite un evento onload per la raccolta platform.js e il pulsante viene visualizzato da gapi.signin2.render.

    Un gesto dell'utente, la pressione del pulsante di accesso, chiama auth2.signIn.

    Nella seconda demo, un elemento <div>, stili CSS e una grafica personalizzata vengono utilizzati per controllare l'aspetto del pulsante di accesso. L'interazione utente è obbligatoria per accedere e stabilire una nuova sessione.

    L'inizializzazione della libreria viene eseguita al caricamento del documento utilizzando una funzione di avvio che chiama gapi.load, gapi.auth2.init e gapi.auth2.attachClickHandler.

    Un gesto dell'utente, un evento onclick dell'elemento <div>, chiama auth2.signIn utilizzando auth2.attachClickHandler durante l'accesso o auth2.signOut al log out.

  • Monitoraggio dello stato della sessione dell'utente

    In questa demo, viene utilizzata la pressione di un pulsante per l'accesso e la disconnessione dell'utente. L'interazione utente è necessaria per accedere e stabilire una nuova sessione.

    L'inizializzazione della libreria viene eseguita chiamando direttamente gapi.load, gapi.auth2.init e gapi.auth2.attachClickHandler() dopo il caricamento di platform.js utilizzando script src.

    Un gesto dell'utente, un evento onclick dell'elemento <div>, chiama auth2.signIn utilizzando auth2.attachClickHandler durante l'accesso o auth2.signOut al log out.

  • Richiedere autorizzazioni aggiuntive

    In questa demo, viene utilizzata la pressione di un pulsante per richiedere ambiti OAuth 2.0 aggiuntivi, ottenere un nuovo token di accesso e, per gli utenti che hanno già eseguito l'accesso, l'evento pagina onload restituisce le credenziali utente. Per accedere e stabilire una nuova sessione è necessaria l'interazione dell'utente.

    L'inizializzazione della libreria viene eseguita dall'evento onload per la libreria platform.js tramite una chiamata a gapi.signin2.render.

    Un gesto dell'utente, ovvero un clic su un elemento <button>, attiva una richiesta di ambiti OAuth 2.0 aggiuntivi utilizzando googleUser.grant o auth2.signOut al momento della disconnessione.

  • Integrare Accedi con Google utilizzando gli ascoltatori

    In questa demo, per gli utenti che hanno già eseguito l'accesso, l'evento pagina onload restituisce le credenziali utente. L'interazione dell'utente è necessaria per accedere e stabilire una nuova sessione.

    L'inizializzazione della libreria viene eseguita al caricamento del documento utilizzando una funzione di avvio che chiama gapi.load, gapi.auth2.init e gapi.auth2.attachClickHandler. Successivamente, auth2.isSignedIn.listen e auth2.currentUser.listen vengono utilizzati per configurare la notifica delle modifiche allo stato della sessione. Infine, viene chiamato auth2.SignIn per restituire le credenziali degli utenti che hanno eseguito l'accesso.

    Un gesto dell'utente, un evento onclick dell'elemento <div>, chiama auth2.signIn utilizzando auth2.attachClickHandler durante l'accesso o auth2.signOut al log out.

  • Accedi con Google per le app lato server

    In questa demo, un gesto dell'utente viene utilizzato per richiedere un codice di autenticazione OAuth 2.0 e un callback JS effettua una chiamata AJAX per inviare la risposta al server di backend per la verifica.

    L'inizializzazione della libreria viene eseguita utilizzando un evento onload per la libreria platform.js, che utilizza una funzione di avvio per chiamare gapi.load e gapi.auth2.init.

    Un gesto dell'utente, ovvero un clic su un elemento <button>, attiva una richiesta di un codice di autorizzazione chiamando auth2.grantOfflineAccess.

  • SSO multipiattaforma

    FedCM richiede il consenso per ogni istanza del browser, anche se gli utenti Android hanno già eseguito l'accesso. È necessario un consenso una tantum.

Gestire il periodo di transizione

Durante il periodo di transizione, una percentuale di accessi utente potrebbe utilizzare FedCM. La percentuale esatta può variare e cambiare nel tempo. Per impostazione predefinita, Google controlla il numero di richieste di accesso che utilizzano FedCM, ma puoi scegliere di attivare o disattivare l'utilizzo di FedCM durante il periodo di transizione. Al termine del periodo di transizione, FedCM diventa obbligatorio e viene utilizzato per tutte le richieste di accesso.

Se scegli di attivare la funzionalità, l'utente viene indirizzato al flusso di accesso FedCM, mentre se scegli di disattivarla, viene indirizzato al flusso di accesso esistente. Questo comportamento viene controllato utilizzando il parametro use_fedcm.

Attiva

Potrebbe essere utile controllare se tutti o alcuni tentativi di accesso al tuo sito utilizzano le API FedCM. Per farlo, imposta use_fedcm su true durante l'inizializzazione della libreria della piattaforma. In questo caso, la richiesta di accesso dell'utente utilizza le API FedCM.

Disattiva

Durante il periodo di transizione, una percentuale di tentativi di accesso degli utenti al tuo sito utilizzerà per impostazione predefinita le API FedCM. Se hai bisogno di più tempo per apportare modifiche alla tua app, puoi disattivare temporaneamente l'utilizzo delle API FedCM. Per farlo, imposta use_fedcm su false durante l'inizializzazione della libreria della piattaforma. In questo caso, la richiesta di accesso dell'utente non utilizzerà le API FedCM.

Dopo l'adozione obbligatoria, eventuali impostazioni use_fedcm vengono ignorate dalla libreria della piattaforma Accedi con Google.

Ricevi assistenza

Cerca o fai domande su StackOverflow utilizzando il tag google-signin.