Esegui la migrazione a FedCM

Questa guida ti aiuta a comprendere le modifiche all'applicazione web introdotte dall'API Federated Credential Management (FedCM).

Quando FedCM è attivato, il browser mostra richieste all'utente e non vengono utilizzati cookie di terze parti.

Panoramica

FedCM consente flussi di accesso più privati senza richiedere l'utilizzo di cookie di terze parti. Il browser controlla le impostazioni dell'utente, mostra le richieste all'utente e contatta un fornitore di servizi di identità come Google solo dopo che l'utente ha dato il suo consenso esplicito.

Per la maggior parte dei siti web, la migrazione avviene senza problemi tramite aggiornamenti compatibili con le versioni precedenti della libreria JavaScript di Google Identity Services.

Aggiornamenti sulla funzionalità di accesso automatico

La versione beta di Federated Credential Management (FedCM) per Google Identity Services è stata lanciata ad agosto 2023. Molti sviluppatori hanno testato l'API e fornito un feedback prezioso.

Una delle risposte ricevute da Google dagli sviluppatori riguarda il requisito relativo al gesto dell'utente per il flusso di accesso automatico di FedCM. Per una maggiore privacy, Chrome richiede agli utenti di confermare di voler accedere al sito web con l'Account Google in ogni istanza di Chrome, anche se l'utente ha approvato il sito web prima dell'implementazione di FedCM. Questa riconferma una tantum viene eseguita facendo clic una sola volta sul prompt One Tap per dimostrare l'intenzione dell'utente di accedere. Questa modifica potrebbe causare un'interruzione iniziale dei tassi di conversione per l'accesso automatico per alcuni siti web.

Di recente, in M121, Chrome ha apportato una modifica all'esperienza utente del flusso di accesso automatico di FedCM. La riconferma è obbligatoria solo quando i cookie di terze parti sono soggetti a limitazioni. Ciò significa che:

  1. L'accesso automatico a FedCM non richiede la riconferma per gli utenti di ritorno. Se gli utenti confermano di nuovo con l'interfaccia utente di FedCM, questa conferma verrà conteggiata ai fini del requisito relativo ai gesti utente per l'era successiva al 3PCD.

  2. L'accesso automatico a FedCM controllerà lo stato della riconferma quando i cookie di terze parti sono limitati manualmente dagli utenti oggi o per impostazione predefinita nella versione futura di Chrome.

Con questa modifica, consigliamo a tutti gli sviluppatori di accesso automatico di eseguire la migrazione a FedCM il prima possibile per ridurre l'interruzione dei tassi di conversione di accesso automatico.

Per il flusso di accesso automatico, GIS JavaScript non attiverà FedCM su una versione precedente di Chrome (prima di M121), anche se il tuo sito web sceglie di attivare FedCM.

Differenze nel percorso dell'utente

Le esperienze One Tap che utilizzano FedCM e quelle che non lo utilizzano sono simili, con alcune piccole differenze.

Nuovo utente di singola sessione

Se utilizzi FedCM, One Tap mostra il nome di dominio di primo livello anziché il nome dell'applicazione.

Utilizzo di FedCM Senza FedCM
Nuovo utente di singola sessione che utilizza FedCM Nuovo utente di singola sessione senza FedCM

Utente di ritorno con una singola sessione (con accesso automatico disattivato)

Se utilizzi FedCM, One Tap mostra il nome di dominio di primo livello anziché il nome dell'applicazione.

Utilizzo di FedCM Senza FedCM
Percorso dell'utente di ritorno con una singola sessione che utilizza FedCM (con accesso automatico disattivato) Percorso dell'utente di ritorno con una singola sessione senza FedCM (con accesso automatico disattivato)

Utente di ritorno di una singola sessione (con accesso automatico abilitato)

Con FedCM, gli utenti possono fare clic su X per annullare l'accesso automatico entro 5 secondi anziché fare clic sul pulsante Annulla.

Utilizzo di FedCM Senza FedCM
Percorso dell'utente di ritorno con una singola sessione che utilizza FedCM (con accesso automatico abilitato) Percorso dell'utente di ritorno con una singola sessione senza FedCM (con accesso automatico abilitato)

Multisessione

Se utilizzi FedCM, One Tap mostra il nome di dominio di primo livello anziché il nome dell'applicazione.

Utilizzo di FedCM Senza FedCM
Utente con più sessioni che utilizza FedCM Utente con più sessioni senza FedCM

Prima di iniziare

Verifica che le impostazioni e la versione del browser supportino l'API FedCM. È consigliabile eseguire l'aggiornamento alla versione più recente.

  • L'API FedCM è disponibile in Chrome 117 o versioni successive.

  • L'impostazione Accesso di terze parti è attivata in Chrome.

  • Se la versione del browser Chrome è 119 o precedente, apri chrome://flags e attiva la funzionalità sperimentale FedCmWithoutThirdPartyCookies. Questo passaggio non è necessario con il browser Chrome versione 120 o successive.

Esegui la migrazione dell'app web

Per attivare FedCM, valutare il potenziale impatto della migrazione e, se necessario, apportare modifiche all'applicazione web esistente:

1. Aggiungi un flag booleano per attivare FedCM durante l'inizializzazione utilizzando:

2. Rimuovi l'utilizzo dei metodi isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason() nel codice.

Per migliorare la privacy degli utenti, il callback google.accounts.id.prompt non restituisce più alcuna notifica relativa al momento di visualizzazione nell'objeto PromptMomentNotication. Rimuovi qualsiasi codice che dipende dai metodi correlati al momento di visualizzazione. Si tratta dei metodi isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason().

3. Rimuovi l'utilizzo del metodo getSkippedReason() nel codice.

Anche se il momento di salto, isSkippedMoment(), verrebbe comunque chiamato dal callback google.accounts.id.prompt nell'oggetto PromptMomentNotication, non verrà fornito un motivo dettagliato. Rimuovi dal codice qualsiasi codice che dipende dal metodo getSkippedReason().

Tieni presente che la notifica relativa al momento ignorato, isDismissedMoment(), e il metodo del motivo dettagliato correlato, getDismissedReason(), rimangono invariati quando è attiva la funzionalità FedCM.

4. Rimuovi gli attributi di stile position da data-prompt_parent_id e intermediate_iframes.

Il browser controlla le dimensioni e la posizione delle richieste all'utente. Le posizioni personalizzate per One Tap su computer non sono supportate.

5. Aggiorna il layout della pagina, se necessario.

Il browser controlla le dimensioni e la posizione delle richieste all'utente. A seconda del layout delle singole pagine, alcuni contenuti potrebbero essere sovrapposti perché le posizioni personalizzate per One Tap su computer non sono supportate in alcun modo, ad esempio l'attributo style, data-prompt_parent_id, intermediate_iframes, iframe personalizzati e altri modi creativi.

Modifica il layout della pagina per migliorare l'esperienza utente quando le informazioni importanti sono coperte. Non basare l'esperienza utente sulla richiesta One Tap anche se supponi che sia nella posizione predefinita. Poiché l'API FedCM è mediata dal browser, i diversi fornitori di browser potrebbero posizionare la richiesta in modo leggermente diverso.

6. Aggiungi l'attributo allow="identity-credentials-get" al frame principale se la tua app web chiama l'API One Tap da iframe cross-origin.

Un iframe è considerato interorigine se la sua origine non è esattamente uguale all'origine principale. Ad esempio:

  • Domini diversi: https://example1.com e https://example2.com
  • Domini di primo livello diversi: https://example.uk e https://example.jp
  • Sottodomini: https://example.com e https://login.example.com

Quando utilizzi One Tap in un iframe cross-origin, gli utenti potrebbero riscontrare un'esperienza confusa. La richiesta One Tap mostra il nome del dominio di primo livello, non dell'iframe, come misura di sicurezza per impedire il furto delle credenziali. Tuttavia, gli ID token vengono emessi per l'origine dell'iframe. Per maggiori dettagli, consulta questo problema GitHub.

Poiché questa discrepanza può essere fuorviante, l'utilizzo di One Tap solo negli iframe cross-origin, ma nello stesso sito, è un metodo supportato. Ad esempio, una pagina sul dominio di primo livello https://www.example.com che utilizza iframe per incorporare una pagina con One Tap su https://login.example.com. Il prompt One Tap mostrerà "Accedi a example.com con google.com".

Tutti gli altri casi, come domini diversi, non sono supportati. Valuta invece metodi di integrazione alternativi, come:

  • Implementazione del pulsante Accedi con Google.
  • Implementazione di One Tap sul dominio di primo livello
  • Utilizzo degli endpoint OAuth 2.0 di Google per un'integrazione più personalizzata.
  • Se incorpori un sito di terze parti in un iframe e non puoi modificarne l'implementazione di One Tap, puoi impedire la visualizzazione della richiesta di One Tap all'interno dell'iframe. A tal fine, rimuovi l'attributo allow="identity-credentials-get" dal tag iframe nel frame principale. In questo modo, la richiesta verrà eliminata e potrai indirizzare gli utenti direttamente alla pagina di accesso del sito incorporato.

Quando l'API One Tap viene chiamata da iframe cross-origin, devi aggiungere l'attributo allow="identity-credentials-get" in ogni tag frame principale iframe:

  <iframe src="https://your.cross-origin/onetap.page" allow="identity-credentials-get"></iframe>

Se la tua app utilizza un iframe che contiene un altro iframe, devi assicurarti che l'attributo venga aggiunto a ogni iframe, inclusi tutti gli iframe secondari.

Ad esempio, considera il seguente scenario:

  • Il documento principale (https://www.example.uk) contiene un iframe denominato "Iframe A", che incorpora una pagina (https://logins.example.com).

  • Questa pagina incorporata (https://logins.example.com) contiene anche un iframe chiamato "Iframe B", che incorpora ulteriormente una pagina (https://onetap.example2.com) che ospita One Tap.

    Per assicurarti che One Tap possa essere visualizzato correttamente, l'attributo deve essere aggiunto sia ai tag Iframe A che ai tag Iframe B.

    Preparati per le richieste relative al prompt One Tap non visualizzato. Altri siti con origini diverse potrebbero incorporare le tue pagine che ospitano One Tap nei propri iframe. Potresti ricevere un numero maggiore di richieste di assistenza relative alla mancata visualizzazione di One Tap da parte di utenti finali o altri proprietari di siti. Anche se gli aggiornamenti possono essere apportati solo dai proprietari delle pagine, puoi fare quanto segue per attenuare l'impatto:

  • Aggiorna la documentazione per gli sviluppatori in modo da includere la procedura per configurare correttamente l'iframe per chiamare il tuo sito. Puoi inserire un link a questa pagina nella documentazione.

  • Aggiorna la pagina delle domande frequenti per gli sviluppatori, se applicabile.

  • Comunica al team di assistenza questa modifica imminente e preparati in anticipo alla risposta alla richiesta.

  • Contatta in modo proattivo i partner, i clienti o i proprietari di siti interessati per una transizione senza problemi a FedCM.

7. Aggiungi queste direttive al tuo criterio di sicurezza del contenuto (CSP).

Questo passaggio è facoltativo perché non tutti i siti web scelgono di definire un CSP.

  • Se il tuo sito web non utilizza CSP, non è necessaria alcuna modifica.

  • Se il tuo fornitore di servizi di pagamento funziona per l'attuale One Tap e non utilizzi connect-src, frame-src, script-src, style-src o default-src, non sono necessarie modifiche.

  • In caso contrario, segui questa guida per configurare il tuo CSP. Senza una configurazione corretta del CSP, FedCM One Tap non verrà visualizzato sul sito.

8. Rimuovi il supporto di Accelerated Mobile Pages (AMP) per l'accesso.

Il supporto dell'accesso utente per AMP è una funzionalità facoltativa di GIS che la tua app web potrebbe aver implementato. In questo caso:

Elimina eventuali riferimenti a:

  • Elemento personalizzato amp-onetap-google e 
  • <script async custom-element="amp-onetap-google" src="https://cdn.ampproject.org/v0/amp-onetap-google-0.1.js"></script>

    Valuta la possibilità di reindirizzare le richieste di accesso da AMP al flusso di accesso HTML del tuo sito web. Tieni presente che Intermediate Iframe Support API correlato non è interessato.

Testa e verifica la migrazione

Dopo aver apportato le modifiche necessarie in base ai passaggi precedenti, puoi verificare che la migrazione sia andata a buon fine.

  1. Verifica che il browser supporti FedCM e che tu abbia già una sessione dell'Account Google.

  2. Vai alle pagine One Tap nella tua applicazione.

  3. Verifica che la richiesta di un solo tocco venga visualizzata e sovrapponga in modo sicuro i contenuti di base.

  4. Verifica che al tuo endpoint o metodo di callback venga restituita una credenziale corretta quando accedi alla tua applicazione utilizzando One Tap.

  5. Se l'accesso automatico è abilitato, verifica che l'annullamento funzioni e che le credenziali corrette vengano restituite all'endpoint o al metodo di callback.

Periodo di attesa di One Tap

Se fai clic su One Tap nell'angolo in alto a destra, la richiesta viene chiusa e viene attivato il periodo di attesa, che impedisce temporaneamente la visualizzazione della richiesta One Tap. In Chrome, se vuoi che la richiesta di One Tap venga visualizzata di nuovo prima del termine del periodo di attesa, puoi reimpostare lo stato del periodo di attesa facendo clic sull'icona a forma di lucchetto nella barra degli indirizzi e sul pulsante Reimposta autorizzazione.

Periodo di riposo per l'accesso automatico

Quando testi l'accesso automatico One Tap utilizzando FedCM, è presente un periodo di inattività di 10 minuti tra ogni tentativo di accesso automatico. Il periodo di silenzio non può essere reimpostato. Per attivare di nuovo l'accesso automatico, dovrai attendere 10 minuti o utilizzare un altro Account Google per i test.

Risorse utili

Privacy Sandbox Analysis Tool (PSAT) è un'estensione di Chrome DevTools che aiuta ad adottare API alternative come FedCM. Il suo funzionamento consiste nel eseguire la scansione del sito per rilevare le funzionalità interessate e fornire un elenco di modifiche consigliate.