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 trattati includono Tempistiche e Passaggi successivi per un aggiornamento compatibile con le versioni precedenti della libreria, 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. Vengono inoltre illustrate le opzioni per gestire il periodo di transizione e le modalità per 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 scoprire di più, consulta la sezione Ritiro del supporto e ritiro.

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 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.
  • È iniziato il periodo di transizione di luglio 2024 e verrà aggiunto il supporto della libreria di piattaforme Accedi con Google per le API FedCM. 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.
  • Adozione obbligatoria di 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 dell'utente utilizzano FedCM.

Passaggi successivi

Hai a disposizione tre opzioni:

  1. Esegui una valutazione dell'impatto e, se necessario, aggiorna l'app web. Questo approccio valuta se le funzionalità che richiedono modifiche all'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 dispendiosa, 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

Le API browser e la versione più recente della libreria della piattaforma Accedi con Google sono necessarie per utilizzare FedCM durante l'accesso degli utenti.

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 con versioni precedenti.

  • Apri chrome://flags e imposta le seguenti funzionalità su questi valori:

    • #fedcm-authz abilitato
    • #tracking-protection-3pcd Abilitato
    • #third-party-cookie-deprecation-trial Disattivato
    • #tpcd-metadata-grants disabilitato
    • #tpcd-heuristics-grants Disattivato

    e riavvia Chrome.

  • Imposta use_fedcm su true durante l'inizializzazione della 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}).

  • invalida le versioni memorizzate nella cache della libreria della piattaforma Accedi con Google. In genere 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 Google API Console

    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 completo. 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 in 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 per la libreria di Accedi con Google

Controlla 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.
  • Se viene utilizzato un iframe, potrebbero essere necessarie modifiche cross-origin.

Per verificare se è presente un iframe:

  • Seleziona il riquadro Elementi in Chrome DevTools e
  • Utilizza 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 del documento. Gli iframe possono essere nidificati, quindi assicurati di aggiungere l'istruzione 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.

Verificare la presenza di modifiche alle richieste dell'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
  • GoogleAuth.signIn viene chiamato.

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 come 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 demo uno, 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 onload della pagina restituisce le credenziali utente. L'interazione dell'utente è necessaria per accedere e stabilire una nuova sessione.

    L'inizializzazione della libreria 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 demo due, un elemento <div>, gli stili CSS e un'immagine 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.

  • Richiesta di 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. È necessaria l'interazione dell'utente per accedere e stabilire una nuova sessione.

    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 onload della pagina 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, auth2.SignIn viene chiamato per restituire le credenziali per gli 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, viene utilizzato un gesto dell'utente per richiedere un codice di autorizzazione 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 degli utenti 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 è 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, tutte le impostazioni di use_fedcm vengono ignorate dalla libreria della piattaforma Accedi con Google.

Ricevi assistenza

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