Migrar para o FedCM

Este guia ajuda a entender as mudanças no seu aplicativo da Web introduzidas pela API Federated Credential Management (FedCM, na sigla em inglês).

Quando o FedCM está ativado, o navegador mostra solicitações ao usuário e nenhum cookie de terceiros é usado.

Visão geral

O FedCM permite fluxos de login mais privados sem exigir o uso de cookies de terceiros. O navegador controla as configurações do usuário, exibe solicitações do usuário e só entra em contato com um provedor de identidade, como o Google, após o consentimento explícito do usuário.

Para a maioria dos sites, a migração ocorre sem problemas com atualizações compatíveis com versões anteriores para a biblioteca JavaScript dos Serviços de Identificação do Google.

Dica: durante os experimentos do Google e os testes de origem do Chrome, uma porcentagem do número total de usuários que fazem login no seu site vai usar a API FedCM. A porcentagem específica varia e pode mudar sem aviso prévio. Antes que o FedCM se torne obrigatório para todos os logins, use data-use_fedcm_for_prompt ou use_fedcm_for_prompt para escolher o fluxo de login. Isso pode melhorar sua capacidade de depurar, coletar métricas ou alternar todos os logins para o FedCM após concluir a migração.

Atualizações sobre o recurso de login automático

A versão Beta do Gerenciador de credenciais federadas (FedCM, na sigla em inglês) para os Serviços de Identificação do Google foi lançada em agosto de 2023. Muitos desenvolvedores testaram a API e enviaram feedback valioso.

Uma resposta que o Google recebeu dos desenvolvedores é sobre o requisito de gesto do usuário do fluxo de login automático do FedCM. Para melhorar a privacidade, o Chrome exige que os usuários confirmem novamente que querem fazer login no site com a Conta do Google em cada instância do Chrome, mesmo que o usuário tenha aprovado o site antes do lançamento do FedCM. Essa reconfirmação única é feita com um único clique no comando de um toque ou no fluxo de botões com o FedCM para demonstrar a intenção do usuário de fazer login. Essa mudança pode causar uma interrupção inicial nas taxas de conversão de login automático em alguns sites.

Recentemente, na M121, o Chrome fez uma mudança na UX do fluxo de login automático do FedCM. A nova confirmação é necessária apenas quando os cookies de terceiros são restritos. Isso significa:

1. O login automático do FedCM não requer nova confirmação para usuários recorrentes. Se os usuários confirmarem novamente com a interface do FedCM, essa nova confirmação vai contar para o requisito de gesto do usuário para a era pós-3PCD.

2. O login automático do FedCM vai verificar o status de nova confirmação quando os cookies de terceiros forem restritos manualmente pelos usuários hoje ou por padrão no Chrome no futuro.

Com essa mudança, recomendamos que todos os desenvolvedores de login automático migrem para o FedCM assim que possível para reduzir a interrupção das taxas de conversão de login automático.

Para o fluxo de login automático, o JavaScript do GIS não vai acionar o FedCM em um Chrome mais antigo (antes do M121), mesmo que seu site escolha ativar o FedCM.

Diferenças na jornada do usuário

As experiências do One Tap usando FedCM e sem FedCM são semelhantes, mas com pequenas diferenças.

Novo usuário de sessão única

Com o FedCM, o One Tap mostra o nome do domínio de nível superior em vez do nome do aplicativo.

Como usar o FedCM	Sem FedCM

Usuário recorrente de sessão única (com login automático desativado)

Com o FedCM, o One Tap mostra o nome do domínio de nível superior em vez do nome do aplicativo.

Como usar o FedCM	Sem FedCM

Usuário recorrente de sessão única (com login automático ativado)

Com o FedCM, os usuários podem clicar em X para cancelar o login automático em até 5 segundos, em vez de clicar no botão Cancelar.

Como usar o FedCM	Sem FedCM

Várias sessões

Com o FedCM, o One Tap mostra o nome do domínio de nível superior em vez do nome do aplicativo.

Como usar o FedCM	Sem FedCM

Consulte a página do botão Fazer login com o Google para conferir as principais jornadas do usuário para o fluxo do botão FedCM.

Antes de começar

Verifique se as configurações e a versão do navegador têm suporte à API FedCM. É recomendável atualizar para a versão mais recente.

• A API FedCM está disponível no Chrome 117 ou mais recente.

• A configuração Login de terceiros está ativada no Chrome. A configuração só afeta o One Tap e não tem impacto no fluxo do botão do FedCM.

• Se a versão do navegador Chrome for 119 ou anterior, abra chrome://flags e ative o recurso experimental FedCmWithoutThirdPartyCookies. Essa etapa não é necessária com o navegador Chrome versão 120 ou mais recente.

Migrar seu app da Web

Siga estas etapas para ativar o FedCM, avaliar o possível impacto da migração e, se necessário, fazer alterações no seu aplicativo da Web atual:

1. Adicione uma flag booleana para ativar o FedCM para o One Tap ao inicializar usando:

• HTML, defina o atributo data-use_fedcm_for_prompt como true.

• No JavaScript, defina use_fedcm_for_prompt como true no objeto IdConfiguration.

2. Adicionar uma flag booleana para ativar o FedCM para Button ao inicializar usando: {:#fedcm_button_flag} (opcional)

• HTML, defina o atributo data-use_fedcm_for_button como true para ativar o fluxo do botão FedCM. Com o fluxo de botão do FedCM ativado, você também pode definir o atributo data-use_fedcm_for_button como true para ativar o novo recurso de seleção automática.

• No JavaScript, defina use_fedcm_for_button como true no objeto IdConfiguration para ativar o fluxo do botão FedCM. Com o fluxo de botão FedCM ativado, também é possível definir o atributo button_auto_select como true para ativar o novo recurso seleção automática.

  Observação: esta etapa é opcional. Se você optar por não ativar o FedCM para o fluxo de botões, ele continuará usando o fluxo não FedCM.

3. Remova o uso dos métodos isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason() para o recurso Um toque no código.

Para melhorar a privacidade do usuário, o callback google.accounts.id.prompt não retorna mais nenhuma notificação de momento de exibição no objeto PromptMomentNotication. Remova qualquer código que dependa dos métodos relacionados ao momento de exibição. Eles são os métodos isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason().

4. Remova o uso do método getSkippedReason() para o recurso Toque único no código.

Embora o momento de pular, isSkippedMoment(), ainda fosse chamado pelo callback google.accounts.id.prompt no objeto PromptMomentNotication, o motivo detalhado não seria fornecido. Remova qualquer código que dependa do método getSkippedReason().

A notificação de momento dispensado, isDismissedMoment(), e o método de motivo detalhado relacionado, getDismissedReason(), não são alterados quando o FedCM está ativado.

5. Remover os atributos de estilo position de data-prompt_parent_id e intermediate_iframes para o recurso Um toque.

O navegador controla o tamanho e a posição dos comandos do usuário. Não é possível usar posições personalizadas para o recurso de um toque no computador.

6. Atualize o layout da página, se necessário, para o recurso Um toque.

O navegador controla o tamanho e a posição das solicitações do usuário. Dependendo do layout de páginas individuais, parte do conteúdo pode ser sobreposta como posições personalizadas para o recurso Um toque no computador não têm suporte de nenhuma forma, como atributo style, data-prompt_parent_id, intermediate_iframes, iframe personalizado e outras formas criativas.

Mude o layout da página para melhorar a experiência do usuário quando informações importantes estiverem obscurecidas. Não crie sua UX em torno do comando de um toque, mesmo que você suponha que ele esteja na posição padrão. Como a API FedCM é mediada pelo navegador, diferentes fornecedores de navegadores podem posicionar o comando de maneira diferente.

7. Adicione o atributo allow="identity-credentials-get" ao frame pai se o app da Web chamar a API One Tap ou Button de iframes de origem cruzada.

Um iframe é considerado de origem cruzada se a origem dele não for exatamente igual à origem pai. Por exemplo:

• Domínios diferentes: https://example1.com e https://example2.com
• Domínios de nível superior diferentes: https://example.uk e https://example.jp
• Subdomínios: https://example.com e https://login.example.com

Ao usar o One Tap em um iframe de origem cruzada, os usuários podem ter uma experiência confusa. O comando "One Tap" mostra o nome do domínio de nível superior, não o do iframe, como uma medida de segurança para evitar a coleta de credenciais. No entanto, os tokens de ID são emitidos para a origem do iframe. Confira mais detalhes neste problema do GitHub.

Como essa discrepância pode ser enganosa, usar apenas o One Tap em origens diferentes, mas iframes do mesmo site é um método com suporte. Por exemplo, uma página no domínio de nível superior https://www.example.com usando iframe para incorporar uma página com o recurso Um toque em https://login.example.com. O comando "Um toque" vai mostrar "Fazer login em example.com com google.com".

Todos os outros casos, como domínios diferentes, não são compatíveis. Em vez disso, considere métodos de integração alternativos, como:

• Implementar o botão Fazer login com o Google sem o FedCM ativado.
• Implementar o recurso Um toque no domínio de nível superior
• Use os endpoints do OAuth 2.0 do Google para uma integração mais personalizada.
• Se você estiver incorporando um site de terceiros em um iframe e não puder modificar a implementação do recurso Um toque, é possível impedir que o comando apareça no iframe. Para fazer isso, remova o atributo allow="identity-credentials-get" da tag iframe no frame pai. Isso vai suprimir a solicitação, e você poderá direcionar os usuários diretamente para a página de login do site incorporado.

Quando a API One Tap ou Button é chamada de iframes de origem cruzada, é necessário adicionar o atributo allow="identity-credentials-get" em cada tag iframe do frame pai:

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

Se o app usar um iframe que contém outro iframe, será necessário garantir que o atributo seja adicionado a todos os iframes, incluindo todos os subaframes.

Por exemplo, considere este cenário:

• O documento principal (https://www.example.uk) contém um iframe chamado "Iframe A", que incorpora uma página (https://logins.example.com).

• Essa página incorporada (https://logins.example.com) também contém um iframe chamado "Iframe B", que incorpora uma página (https://onetap.example2.com) que hospeda o Toque inteligente ou o botão.

  Para garantir que o botão ou o recurso "Um toque" sejam exibidos corretamente, o atributo precisa ser adicionado às tags Iframe A e Iframe B.

  Observação: a API Intermediate Iframe oferece suporte a iframes de origem cruzada do FedCM. Nenhum atributo adicional é necessário. No entanto, se você incorporar uma página usando a API Intermediate Iframe em outro iframe, será necessário adicionar o atributo allow="identity-credentials-get" a todos os iframes pai. Ative a FedCM para testar e garantir a configuração adequada da política de permissão em todas as camadas.

  Prepare-se para perguntas sobre o comando ou o botão do recurso Um toque que não aparece. Outros sites com origens diferentes podem incorporar suas páginas que hospedam o recurso Um toque nos iframes deles. Você pode receber um aumento no número de solicitações de suporte relacionadas ao botão ou ao recurso Um toque que não aparecem para usuários finais ou outros proprietários de sites. Embora as atualizações só possam ser feitas pelos proprietários do site nas páginas deles, você pode fazer o seguinte para reduzir o impacto:

• Atualize a documentação para desenvolvedores e inclua como configurar o iframe corretamente para chamar seu site. Você pode vincular esta página na sua documentação.

• Atualize a página de perguntas frequentes para desenvolvedores, se aplicável.

• Informe sua equipe de suporte sobre essa mudança e prepare a resposta à consulta com antecedência.

• Entre em contato proativamente com os parceiros, clientes ou proprietários de sites afetados para uma transição tranquila do FedCM.

  Observação: na página afetada, você vai encontrar a mensagem de erro no console das Ferramentas para Desenvolvedores do navegador Chrome: [GSI_LOGGER]: FedCM get() rejects with NotAllowedError: The 'identity-credentials-get' feature is not enabled in this document.

8. Adicione estas diretivas à sua Política de Segurança de Conteúdo (CSP).

Esta etapa é opcional, já que nem todos os sites definem um CSP.

• Se a CSP não for usada no seu site, não será necessário fazer mudanças.

• Se o CSP funcionar para o One Tap ou o botão atual e você não usar connect-src, frame-src, script-src, style-src ou default-src, não será necessário fazer mudanças.

• Caso contrário, siga este guia para configurar o CSP. Sem a configuração adequada do CSP, o botão ou o recurso FedCM One Tap não será exibido no site.

  Observação: na página afetada, você vai encontrar a mensagem de erro no console das Ferramentas para Desenvolvedores do navegador Chrome: [GSI_LOGGER]: FedCM get() rejects with NetworkError: Failed to execute 'get' on 'CredentialsContainer': Refused to connect to 'https://accounts.google.com/gsi/fedcm.json' because it violates the document's Content Security Policy.

9. Remova o suporte para login nas Accelerated Mobile Pages (AMP).

O suporte ao login do usuário para AMP é um recurso opcional do SIG que seu app da Web pode ter implementado. Se esse for o caso,

Exclua todas as referências a:

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

  Considere redirecionar as solicitações de login do AMP para o fluxo de login do HTML do seu site. O Intermediate Iframe Support API relacionado não é afetado.

Testar e verificar a migração

Depois de fazer as mudanças necessárias com base nas etapas anteriores, você pode verificar se a migração foi bem-sucedida.

1. Confirme se o navegador oferece suporte ao FedCM e se você tem uma sessão da Conta do Google.

2. Navegue até as páginas de um toque ou do botão no seu app.

3. Confirme se o botão ou comando de um toque é exibido e se ele sobrepõe o conteúdo subjacente com segurança.

4. Confirme se uma credencial correta é retornada ao endpoint ou ao método de callback ao fazer login no seu aplicativo usando o recurso One Tap ou o botão.

5. Se o login automático estiver ativado, verifique se o cancelamento funciona e se a credencial correta é retornada ao endpoint ou ao método de callback.

Período de espera do recurso Um toque

Clicar em "One Tap" no canto superior direito fecha a solicitação e entra no período de espera, que impede a exibição temporária da solicitação. No Chrome, se você quiser que o comando de um toque seja mostrado novamente antes do término do período de espera, redefina o status de espera clicando no ícone de bloqueio na barra de endereço e no botão Redefinir permissão.

Período de silêncio do login automático

Ao testar o login automático One Tap usando o FedCM, há um período de 10 minutos entre cada tentativa de login automático. O período de silêncio não pode ser redefinido. Você precisa esperar 10 minutos ou usar uma Conta do Google diferente para testar e acionar o login automático novamente.

Recursos úteis

A Ferramenta de análise de dados do Sandbox de privacidade (PSAT, na sigla em inglês) é uma extensão do Chrome DevTools para ajudar na adoção de APIs alternativas, como o FedCM. Ele verifica seu site em busca de recursos afetados e fornece uma lista de mudanças recomendadas.