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.
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 "Um toque" 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 para 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 que:
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.
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 ou por padrão no Chrome.
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 recurso Um toque mostra o nome de 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 recurso Um toque mostra o nome de 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 recurso Um toque mostra o nome de domínio de nível superior em vez do nome do aplicativo.
| Como usar o FedCM | Sem 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.
Se a versão do navegador Chrome for 119 ou anterior, abra
chrome://flagse ative o recurso experimentalFedCmWithoutThirdPartyCookies. Essa etapa não é necessária com a versão 120 ou mais recente do navegador Chrome.
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 ao inicializar usando:
HTML, defina o atributo
data-use_fedcm_for_promptcomotrue.No JavaScript, defina
use_fedcm_for_promptcomotrueno objetoIdConfiguration.
2. Remova o uso dos métodos isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason() 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().
3. Remova o uso do método getSkippedReason() 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.
4. Remova os atributos de estilo position de data-prompt_parent_id e intermediate_iframes.
O navegador controla o tamanho e a posição dos comandos do usuário. Não há suporte para posições personalizadas para o recurso Um toque no computador.
5. Atualize o layout da página, se necessário.
O navegador controla o tamanho e a posição das solicitações do usuário. Dependendo
do layout de cada página, 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 ligeiramente diferente.
6. Adicione o atributo allow="identity-credentials-get" ao frame pai se o app da Web chamar a API One Tap 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.comehttps://example2.com - Domínios de nível superior diferentes:
https://example.ukehttps://example.jp - Subdomínios:
https://example.comehttps://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".
- 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 aviso 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 é 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, é 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 One Tap.Para garantir que o recurso Um Toque seja exibido corretamente, o atributo precisa ser adicionado às tags Iframe A e Iframe B.
Prepare-se para perguntas sobre o comando "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 na quantidade de tíquetes de suporte relacionada à não exibição do recurso Um toque de 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 parceiros, clientes ou proprietários de sites afetados para uma transição tranquila do FedCM.
7. Adicione estas diretivas à sua Política de Segurança de Conteúdo (CSP).
Esta etapa é opcional, porque 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 atual e você não usar
connect-src,frame-src,script-src,style-srcoudefault-src, nenhuma mudança será necessária.Caso contrário, siga este guia para configurar o CSP. Sem a configuração adequada do CSP, o FedCM One Tap não é exibido no site.
8. Remova o suporte para login nas Accelerated Mobile Pages (AMP).
O suporte ao login do usuário para AMP é um recurso opcional do GIS que seu app da Web pode ter implementado. Se esse for o caso,
Exclua todas as referências a:
- Elemento personalizado
amp-onetap-googlee <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 APIrelacionado 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.
Confirme se o navegador oferece suporte ao FedCM e se você tem uma sessão da Conta do Google.
Acesse as páginas do One Tap no seu app.
Confirme se a solicitação de um toque é exibida e se ela sobrepõe o conteúdo subjacente com segurança.
Confirme se uma credencial correta é retornada ao endpoint ou método de callback ao fazer login no seu aplicativo usando o recurso One Tap.
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.