Login do Google com APIs FedCM

Este guia discute a adoção de APIs FedCM pela biblioteca da plataforma de Login do Google. Os tópicos incluem a Cronologia e Próximas etapas para uma atualização compatível com versões anteriores da biblioteca, como realizar uma avaliação de impacto e verificar se o login do usuário continua funcionando como esperado e, se necessário, instruções para atualizar seu app da Web. As opções para gerenciar o período de transição e como receber ajuda também são abordadas.

Status da biblioteca

Todos os novos apps da Web estão bloqueados para usar a biblioteca descontinuada da plataforma do Login do Google, enquanto os apps que usam a biblioteca podem continuar até novo aviso. Uma data final de desativação (encerramento) da biblioteca não foi estabelecida. Consulte Descontinuação do suporte e desativação para saber mais.

Uma atualização compatível com versões anteriores adiciona as APIs FedCM à biblioteca do Login do Google. Embora a maioria das mudanças seja simples, a atualização apresenta diferenças nas solicitações do usuário, na policy-permissions do iframe e na Política de Segurança de Conteúdo (CSP). Essas mudanças podem afetar seu app da Web e exigir mudanças no código do aplicativo e na configuração do site.

Durante o período de transição, uma opção de configuração controla se as APIs FedCM são usadas ou não durante o login do usuário.

Após o período de transição, as APIs FedCM são obrigatórias para todos os apps da Web que usam a biblioteca de login do Google.

Cronograma

Última atualização: setembro de 2024

Confira as datas e mudanças que afetam o comportamento de login do usuário:

  • Março de 2023 Descontinuação do suporte à biblioteca da plataforma do Login do Google.
  • O período de transição de julho de 2024 começa, e o suporte da biblioteca da plataforma do Login do Google para APIs FedCM é adicionado. Por padrão, o Google controla a porcentagem de solicitações de login do usuário usando o FedCM durante esse período. Os apps da Web podem modificar explicitamente esse comportamento com o parâmetro use_fedcm.
  • Adoção obrigatória de março de 2025 das APIs FedCM pela biblioteca de plataforma do Login do Google. Depois disso, o parâmetro use_fedcm será ignorado e todas as solicitações de login do usuário vão usar o FedCM.

Próximas etapas

Há três opções:

  1. Faça uma avaliação de impacto e, se necessário, atualize o app da Web. Essa abordagem avalia se os recursos que exigem mudanças no app da Web estão em uso. As instruções estão na próxima seção deste guia.
  2. Mova para a biblioteca de Serviços de Identificação do Google (GIS). É altamente recomendável migrar para a biblioteca de login mais recente e com suporte. Para isso, siga estas instruções.
  3. Não fazer nada: Seu app da Web será atualizado automaticamente quando a biblioteca do Login do Google for movida para as APIs FedCM para fazer login do usuário. Esse é o menos trabalho, mas há algum risco de os usuários não conseguirem fazer login no seu app da Web.

Realizar uma avaliação de impacto

Siga estas instruções para determinar se o app da Web pode ser atualizado de forma transparente com uma atualização compatível com versões anteriores ou se são necessárias mudanças para evitar que os usuários não consigam fazer login quando a biblioteca da plataforma de login do Google adotar totalmente as APIs FedCM.

Configuração

As APIs do navegador e a versão mais recente da biblioteca da plataforma de Login do Google são necessárias para usar o FedCM durante o login do usuário.

Antes de continuar:

  • Atualize para a versão mais recente do Chrome para computador. O Chrome para Android exige a versão M128 ou mais recente e não pode ser testado usando versões anteriores.

  • Abra chrome://flags e defina os seguintes recursos com estes valores:

    • #fedcm-authz Ativado
    • #protecao-contra-rastreamento-3pcd Ativado
    • #third-party-cookie-deprecation-trial Desativado
    • #tpcd-metadata-grants Desativado
    • #tpcd-heuristics-grants Desativada

    e reinicie o Chrome.

  • Defina use_fedcm como true ao inicializar a biblioteca da plataforma do Login do Google no seu app da Web. Normalmente, a inicialização tem esta aparência:

    • gapi.client.init({use_fedcm: true}) ou
    • gapi.auth2.init({use_fedcm: true}) ou
    • gapi.auth2.authorize({use_fedcm: true}).

  • Invalidate as versões em cache da biblioteca da plataforma do Login do Google. Normalmente, essa etapa é desnecessária, porque a versão mais recente da biblioteca é transferida diretamente para o navegador ao incluir api.js, client.js ou platform.js em uma tag <script src>. A solicitação pode usar qualquer um desses nomes de pacote para a biblioteca.

  • Confirme as configurações do OAuth para seu ID do cliente OAuth:

    1. Abra a página "Credenciais" do Google API Console.

    2. Verifique se o URI do site está incluído nas Origens JavaScript autorizadas. O URI inclui apenas o esquema e o nome de host totalmente qualificado. Por exemplo, https://www.example.com.

    3. Opcionalmente, as credenciais podem ser retornadas usando um redirecionamento para um endpoint que você hospeda, em vez de um callback do JavaScript. Nesse caso, verifique se os URIs de redirecionamento estão incluídos nos URIs de redirecionamento autorizados. Os URIs de redirecionamento incluem o esquema, o nome do host totalmente qualificado e o caminho e precisam obedecer às regras de validação do URI de redirecionamento. Por exemplo, https://www.example.com/auth-receiver.

Teste

Depois de seguir as instruções na configuração:

Localizar a solicitação da biblioteca do Login do Google

Verifique se as mudanças na permissions-policy e na Política de Segurança de Conteúdo são necessárias inspecionando a solicitação para a biblioteca da plataforma do Login do Google. Para fazer isso, localize a solicitação usando o nome e a origem da biblioteca:

  • No Chrome, abra o painel Network do DevTools e atualize a página.
  • Use os valores nas colunas Domain e Name para localizar a solicitação da biblioteca:
    • O domínio é apis.google.com e
    • O nome é api.js, client.js ou platform.js. O valor específico de "Nome" depende do pacote de biblioteca solicitado pelo documento.

Por exemplo, filtre apis.google.com na coluna Domínio e platform.js na coluna Nome.

Verificar a policy de permissões de iframe

Seu site pode usar a biblioteca da plataforma do Login do Google em um iframe de origem cruzada. Se sim, é necessário fazer uma atualização.

Depois de seguir as instruções Localizar a solicitação da biblioteca do Login do Google, selecione a solicitação da biblioteca do Login do Google no painel Network das Ferramentas do desenvolvedor e localize o cabeçalho Sec-Fetch-Site na seção Request Headers na guia Headers. Se o valor do cabeçalho for:

  • same-siteou same-origin, as políticas entre origens não se aplicam e nenhuma mudança é necessária.
  • As mudanças de cross-origin podem ser necessárias se um iframe estiver sendo usado.

Para confirmar se um iframe está presente:

  • Selecione o painel Elementos no Chrome DevTools.
  • Use Ctrl + F para encontrar um iframe no documento.

Se um iframe for encontrado, inspecione o documento para verificar se há chamadas para as funções gapi.auth2 ou as diretivas script src que carregam a biblioteca do Login do Google no iframe. Nesse caso:

Repita esse processo para cada iframe no documento. Os iframes podem ser aninhados, então adicione a diretiva "allow" a todos os iframes pai ao redor.

Conferir a Política de Segurança de Conteúdo

Caso seu site use uma Política de Segurança de Conteúdo, talvez seja necessário atualizar a CSP para permitir o uso da biblioteca do Login do Google.

Depois de seguir as instruções para Localizar a solicitação da biblioteca de Login do Google, selecione a solicitação da biblioteca do Login do Google no painel Rede do DevTools e localize o cabeçalho Content-Security-Policy na seção Cabeçalhos de resposta da guia Cabeçalhos.

Se o cabeçalho não for encontrado, nenhuma alteração será necessária. Caso contrário, verifique se alguma destas diretivas está definida no cabeçalho CSP e atualize-as da seguinte forma:

  • Adição de https://apis.google.com/js/, https://accounts.google.com/gsi/ e https://acounts.google.com/o/fedcm/ a qualquer diretiva connect-src, default-src ou frame-src.

  • Adicione https://apis.google.com/js/bundle-name.js à diretiva script-src. Substitua bundle-name.js por api.js, client.js ou platform.js com base no pacote de biblioteca solicitado pelo documento.

Verificar se há mudanças no prompt do usuário

Há algumas diferenças no comportamento do prompt do usuário. O FedCM adiciona uma caixa de diálogo modal mostrada pelo navegador e atualiza os requisitos de ativação do usuário.

Imagem da caixa de diálogo modal do FedCM

Inspecione o layout do seu site para confirmar se o conteúdo subjacente pode ser sobreposto com segurança e temporariamente obscurecido pela caixa de diálogo modal do navegador. Caso contrário, talvez seja necessário ajustar o layout ou a posição de alguns elementos do seu site.

Ativação do usuário

O FedCM inclui requisitos de ativação do usuário atualizados. Apertar um botão ou clicar em um link são exemplos de gestos do usuário que permitem que origens de terceiros façam solicitações de rede ou armazenem dados. Com o FedCM, o navegador solicita o consentimento do usuário quando:

  • um usuário faz login pela primeira vez em um app da Web usando uma nova instância de navegador;
  • A função GoogleAuth.signIn é chamada.

Atualmente, se o usuário já tiver feito login no seu site, você poderá acessar as informações de login dele ao inicializar a biblioteca do Google Sign-In usando gapi.auth2.init, sem mais interações do usuário. Isso não é mais possível, a menos que o usuário tenha passado pelo fluxo de login do FedCM pelo menos uma vez.

Ao ativar o FedCM e chamar GoogleAuth.signIn, na próxima vez que o mesmo usuário visitar seu site, gapi.auth2.init poderá receber as informações de login do usuário durante a inicialização sem interação do usuário.

Casos de uso comuns

A documentação para desenvolvedores da biblioteca do Login do Google inclui guias e exemplos de código para casos de uso comuns. Esta seção discute como a FedCM afeta o comportamento.

  • Como integrar o Login do Google ao seu app da Web

    Nesta demonstração, um elemento <div> e uma classe renderizam o botão. Para usuários que já fizeram login, o evento onload da página retorna as credenciais do usuário. A interação do usuário é necessária para fazer login e estabelecer uma nova sessão.

    A inicialização da biblioteca é feita pela classe g-signin2, que chama gapi.load e gapi.auth2.init.

    Um gesto do usuário, um evento onclick do elemento <div>, chama auth2.signIn durante o login ou auth2.signOut ao sair.

  • Como criar um botão de Login do Google personalizado

    Na Demonstração 1, os atributos personalizados são usados para controlar a aparência do botão de login e, para usuários já conectados, o evento onload da página retorna as credenciais do usuário. A interação do usuário é necessária para fazer login e estabelecer uma nova sessão.

    A inicialização da biblioteca é feita por um evento onload para a biblioteca platform.js, e o botão é mostrado por gapi.signin2.render.

    Um gesto do usuário, pressionando o botão de login, chama auth2.signIn.

    Na segunda demonstração, um elemento <div>, estilos CSS e um gráfico personalizado são usados para controlar a aparência do botão de login. A interação do usuário é necessária para fazer login e estabelecer uma nova sessão.

    A inicialização da biblioteca é feita no carregamento do documento usando uma função inicial que chama gapi.load, gapi.auth2.init e gapi.auth2.attachClickHandler.

    Um gesto do usuário, um evento onclick de elemento <div>, chama auth2.signIn usando o auth2.attachClickHandler durante o login ou auth2.signOut no sair.

  • Monitorar o estado da sessão do usuário

    Nesta demonstração, um botão é usado para o usuário fazer login e sair. A interação do usuário é necessária para fazer login e estabelecer uma nova sessão.

    A inicialização da biblioteca é feita chamando diretamente gapi.load, gapi.auth2.init e gapi.auth2.attachClickHandler() depois que platform.js é carregado usando script src.

    Um gesto do usuário, um evento onclick do elemento <div>, chama auth2.signIn usando auth2.attachClickHandler durante o login ou auth2.signOut ao sair.

  • Como solicitar outras permissões

    Nesta demonstração, um botão é usado para solicitar escopos adicionais do OAuth 2.0, receber um novo token de acesso e, para usuários já conectados, o evento onload da página retorna as credenciais do usuário. A interação do usuário é necessária para fazer login e estabelecer uma nova sessão.

    A inicialização da biblioteca é feita pelo evento onload para a biblioteca platform.js por uma chamada para gapi.signin2.render.

    Um gesto do usuário, clicando em um elemento <button>, aciona uma solicitação para outros escopos do OAuth 2.0 usando googleUser.grant ou auth2.signOut ao sair.

  • Como integrar o Login do Google usando listeners

    Nesta demonstração, para usuários que já fizeram login, o evento onload da página retorna as credenciais do usuário. A interação do usuário é necessária para fazer login e estabelecer uma nova sessão.

    A inicialização da biblioteca é feita no carregamento do documento usando uma função de início que chama gapi.load, gapi.auth2.init e gapi.auth2.attachClickHandler. Em seguida, auth2.isSignedIn.listen e auth2.currentUser.listen são usados para configurar a notificação de mudanças no estado da sessão. Por fim, auth2.SignIn é chamado para retornar credenciais de usuários conectados.

    Um gesto do usuário, um evento onclick de elemento <div>, chama auth2.signIn usando o auth2.attachClickHandler durante o login ou auth2.signOut no sair.

  • Login do Google para apps do lado do servidor

    Nesta demonstração, um gesto do usuário é usado para solicitar um código de autenticação do OAuth 2.0, e um callback JS faz uma chamada AJAX para enviar a resposta ao servidor de back-end para verificação.

    A inicialização da biblioteca é feita usando um evento onload para a biblioteca platform.js, que usa uma função de início para chamar gapi.load e gapi.auth2.init.

    Um gesto do usuário, clicando em um elemento <button>, aciona uma solicitação de um código de autorização chamando auth2.grantOfflineAccess.

  • SSO multiplataforma

    O FedCM exige consentimento para cada instância do navegador, mesmo que os usuários do Android já tenham feito login. Um consentimento único é necessário.

Gerenciar o período de transição

Durante o período de transição, uma porcentagem de logins de usuários pode usar o FedCM. A porcentagem exata pode variar e mudar com o tempo. Por padrão, o Google controla quantas solicitações de login usam o FedCM, mas você pode ativar ou desativar o uso do FedCM durante o período de transição. No final do período de transição, o FedCM se torna obrigatório e é usado para todas as solicitações de login.

A ativação direciona o usuário pelo fluxo de login do FedCM, enquanto a desativação direciona o usuário pelo fluxo de login atual. Esse comportamento é controlado usando o parâmetro use_fedcm.

Ativar

Pode ser útil controlar se todas ou algumas tentativas de login no seu site usam APIs FedCM. Para fazer isso, defina use_fedcm como true ao inicializar a biblioteca da plataforma. A solicitação de login do usuário usa APIs FedCM neste caso.

Desativar

Durante o período de transição, uma porcentagem das tentativas de login do usuário no seu site usará as APIs do FedCM por padrão. Se for necessário mais tempo para fazer mudanças no app, você poderá desativar temporariamente o uso das APIs FedCM. Para fazer isso, defina use_fedcm como false ao inicializar a biblioteca da plataforma. A solicitação de login do usuário não usará as APIs FedCM nesse caso.

Depois que a adoção obrigatória ocorre, todas as configurações de use_fedcm são ignoradas pela biblioteca da plataforma do Login do Google.

Ajuda

Pesquise ou faça perguntas no Stack Overflow usando a tag google-signin.