Migrar do Login do Google

Este guia ajuda a entender as mudanças necessárias e as etapas para migrar as bibliotecas JavaScript da biblioteca anterior da plataforma de Login do Google para a mais recente biblioteca de Serviços de Identificação do Google para autenticação.

Se o cliente estiver usando a biblioteca de cliente da API do Google para JavaScript ou outras bibliotecas anteriores para autorização, consulte Migrar para os serviços de identidade do Google para mais informações.

Autenticação e autorização

A autenticação estabelece quem é alguém e é comumente chamada de inscrição ou login do usuário. A autorização é o processo de conceder ou rejeitar o acesso a dados ou recursos. Por exemplo, seu app solicita o consentimento do usuário para acessar o Google Drive.

Assim como a biblioteca da plataforma Login do Google, a nova biblioteca de serviços de identidade do Google foi criada para oferecer suporte aos processos de autenticação e autorização.

No entanto, a biblioteca mais recente separa os dois processos para reduzir a complexidade para os desenvolvedores integrarem as Contas do Google ao seu app.

Se o caso de uso estiver relacionado apenas à autenticação, continue lendo esta página.

Se seu caso de uso incluir autorização, leia Como funciona a autorização do usuário e Migre para os Serviços de Identificação do Google para garantir que seu aplicativo esteja usando as APIs novas e aprimoradas.

O que mudou

Para os usuários, a nova biblioteca de Serviços de Identificação do Google oferece várias melhorias de usabilidade. Alguns destaques:

  • Novos fluxos de baixo atrito com um toque e login automático com menos etapas individuais.
  • um botão de login atualizado com personalização do usuário,
  • branding consistente e um comportamento uniforme de login em toda a Web melhoram a compreensão e a confiança,
  • acessar o conteúdo rapidamente. Os usuários podem se inscrever e fazer login diretamente de qualquer lugar do site, sem precisar acessar uma página de login ou da conta.

Para os desenvolvedores, nosso foco tem sido reduzir a complexidade, melhorar a segurança e tornar a integração o mais rápido possível. Algumas dessas melhorias incluem:

  • A opção de adicionar o login do usuário ao conteúdo estático do seu site usando apenas HTML,
  • separação entre autenticação de login, autorização e compartilhamento de dados do usuário, a complexidade de uma integração com o OAuth 2.0 não é mais necessária para fazer o login dos usuários no seu site.
  • os modos pop-up e de redirecionamento continuam a ser suportados, mas a infraestrutura do OAuth 2.0 do Google agora redireciona para o endpoint de login do seu servidor de back-end,
  • consolidação dos recursos das bibliotecas JavaScript anteriores do Google Identity e da API do Google em uma única nova biblioteca,
  • Para respostas de login, agora você decide se quer ou não usar uma Promise e a indireção por meio de funções de estilo getter foi removida para simplificar.

Exemplo de migração de login

Se você estiver migrando do botão de Login do Google e só tiver interesse em fazer o login dos usuários no seu site, a mudança mais simples será atualizar para o novo botão personalizado. Isso pode ser feito trocando as bibliotecas JavaScript e atualizando sua base de código para usar um novo objeto de login.

Bibliotecas e configuração

As antigas bibliotecas da plataforma de Login do Google (apis.google.com/js/platform.js) e a biblioteca de cliente de APIs do Google para JavaScript (gapi.client) não são mais necessárias para autenticação e autorização do usuário. Elas foram substituídas por uma única nova biblioteca JavaScript dos Serviços de Identificação do Google: accounts.google.com/gsi/client.

Os três módulos JavaScript anteriores: api, client e platform usados para login são carregados de apis.google.com. Para ajudar a identificar locais em que a biblioteca anterior pode ser incluída no seu site, faça o seguinte:

  • o botão de login padrão carrega apis.google.com/js/platform.js,
  • um gráfico de botão personalizado carrega apis.google.com/js/api:client.js, e
  • O uso direto de gapi.client carrega apis.google.com/js/api.js.

Na maioria dos casos, é possível continuar usando suas credenciais de ID do cliente do aplicativo da Web. Como parte da migração, recomendamos que você analise nossas políticas do OAuth 2.0 e use o Console de APIs do Google para confirmar e, se necessário, atualizar as seguintes configurações do cliente:

  • os apps de teste e produção usam projetos separados e têm IDs do cliente próprios;
  • o Tipo de ID do cliente OAuth 2.0 for "Aplicativo da Web" e
  • O HTTPS é usado para origens autorizadas do JavaScript e URIs de redirecionamento.

Identificar o código afetado e testar

Um cookie de depuração pode ajudar a localizar o código afetado e testar o comportamento após a descontinuação.

Em apps grandes ou complexos, pode ser difícil encontrar todo o código afetado pela descontinuação do módulo gapi.auth2. Para registrar no console o uso de recursos que serão descontinuados em breve, defina o valor do cookie G_AUTH2_MIGRATION como informational. Se quiser, adicione dois-pontos seguidos por um valor de chave para também registrar no armazenamento de sessão. Depois do login e do recebimento das credenciais, a revisão ou o envio dos registros coletados para um back-end para análise posterior. Por exemplo, informational:showauth2use salva a origem e o URL em uma chave de armazenamento de sessão chamada showauth2use.

Para verificar o comportamento do app quando o módulo gapi.auth2 não estiver mais carregado, defina o valor do cookie G_AUTH2_MIGRATION como enforced. Isso permite testar o comportamento pós-suspensão antes da data de aplicação.

Possíveis valores de cookie G_AUTH2_MIGRATION:

  • enforced Não carrega o módulo gapi.auth2.
  • informational registra o uso de recursos descontinuados no console JS. Registrar também no armazenamento de sessão quando um nome de chave opcional for definido: informational:key-name.

Para minimizar o impacto no usuário, recomendamos que você primeiro defina esse cookie localmente durante o desenvolvimento e o teste, antes de usá-lo em ambientes de produção.

HTML e JavaScript

Nesse cenário de login apenas de autenticação, são exibidos o código de exemplo e as renderizações do botão de Login do Google. Selecione o modo pop-up ou de redirecionamento para ver as diferenças na maneira como a resposta de autenticação é tratada por um callback JavaScript ou pelo redirecionamento seguro para o endpoint de login do servidor de back-end.

A maneira anterior

Renderize o botão de Login do Google e use um callback para processar o login diretamente no navegador do usuário.

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

Modo de redirecionamento

Renderize o botão de Login do Google, terminando com uma chamada AJAX do navegador do usuário para o endpoint de login dos servidores de back-end.

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Renderizado

Os novos atributos visuais simplificam o método anterior de criação de um botão personalizado, eliminam chamadas para gapi.signin2.render() e a necessidade de hospedar e manter imagens e recursos visuais no seu site.

Login do Google

Login do Google

Texto do botão para atualizações do status de login do usuário.

O novo jeito

Para usar a nova biblioteca em um cenário de login somente de autenticação, selecione no modo pop-up ou de redirecionamento e use o exemplo de código para substituir a implementação atual na página de login.

Use um callback para processar o login diretamente do navegador do usuário.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

Modo de redirecionamento

O Google invoca seu endpoint de login conforme especificado pelo atributo data-login_url. Anteriormente, você era responsável pela operação POST e pelo nome do parâmetro. A nova biblioteca publica o token de ID no endpoint no parâmetro credential. Por fim, verifique o token de ID no servidor de back-end.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

Renderizado

Use visual-attributes para personalizar o tamanho, a forma e a cor do botão "Fazer login com o Google". Mostre o pop-up de um toque junto com o botão personalizado para melhorar a taxa de login.

botão &quot;Fazer login com o Google&quot; Pop-up com um toque

O estado de login do usuário não atualiza o texto do botão de "Fazer login" para "Conectado". Depois de dar o consentimento ou em visitas de retorno, o botão personalizado inclui o nome, e-mail e foto do perfil do usuário.

Neste exemplo somente de autenticação, a nova biblioteca accounts.google.com/gsi/client, a classe g_id_signin e o objeto g_id_onload substituem a biblioteca apis.google.com/js/platform.js e o objeto g-signin2 anteriores.

Além de renderizar o novo botão personalizado, o código de exemplo também mostra o novo pop-up de um toque. Sempre que você exibir o botão personalizado, recomendamos que também mostre o pop-up de um toque para minimizar o atrito do usuário durante a inscrição e o login.

Embora não seja recomendado devido ao maior atrito no login, o novo botão personalizado pode ser mostrado sozinho, sem exibir simultaneamente a caixa de diálogo "Um toque". Para fazer isso, defina o atributo data-auto_prompt como false.

APIs HTML e JavaScript

O exemplo anterior mostra como usar a nova API HTML para adicionar login ao seu site. Como alternativa, você pode usar a API JavaScript com funcionalidade equivalente ou combinar as APIs HTML e JavaScript no seu site.

Para conferir opções de personalização de botões de maneira interativa, como tipo de callback e atributos, como cor, tamanho, forma, texto e tema, confira nosso gerador de código. Com ele, é possível comparar diferentes opções rapidamente e gerar snippets HTML para uso no seu site.

Faça login em qualquer página com um toque

Um toque é uma nova maneira simples para os usuários se inscreverem ou fazerem login no seu site. Ele permite que você ative o login do usuário diretamente de qualquer página do seu site e elimina a necessidade de os usuários visitarem uma página de login dedicada. Em outras palavras, isso reduz o atrito das inscrições e do login, oferecendo aos usuários a flexibilidade de se inscrever e fazer login em outras páginas além da página de login.

Para ativar o login em qualquer página, recomendamos que você inclua g_id_onload em um cabeçalho, rodapé ou outro objeto compartilhado em todo o site.

Também recomendamos adicionar g_id_signin, que mostra o botão de login personalizado, apenas nas páginas de login ou de gerenciamento da conta de usuário. Ofereça aos usuários opções de inscrição ou login exibindo o botão ao lado de outros botões do provedor de identidade federado e campos de entrada de nome de usuário e senha.

Resposta do token

O login do usuário não exige mais que você entenda ou trabalhe com códigos de autorização, tokens de acesso ou tokens de atualização do OAuth 2.0. Em vez disso, um token de ID do JSON Web Token (JWT) é usado para compartilhar o status de login e o perfil de usuário. Para simplificar, não é mais necessário usar métodos de acesso do estilo "getter" para trabalhar com dados de perfil de usuário.

Uma credencial de token de ID JWT assinada pelo Google é retornada:

  • para o gerenciador de callback do JavaScript baseado no navegador do usuário no modo pop-up ou
  • ao servidor de back-end por um redirecionamento do Google para o endpoint de login quando o botão "Fazer login com o Google" ux_mode estiver definido como redirect.

Em ambos os casos, atualize os gerenciadores de callback atuais removendo:

  • chamadas para googleUser.getBasicProfile(),
  • referências a BasicProfile e chamadas associadas aos métodos getId(), getName(), getGivenName(), getFamilyName(), getImageUrl() e getEmail();
  • uso do objeto AuthResponse.

Em vez disso, use referências diretas aos subcampos credential no novo objeto CredentialResponse do JWT para trabalhar com dados do perfil do usuário.

Além disso, para o modo de redirecionamento somente, evite a falsificação de solicitações entre sites (CSRF, na sigla em inglês) e a opção Verificar o token de ID do Google no servidor de back-end.

Para entender melhor como os usuários estão interagindo com seu site, o campo select_by na CredentialResponse pode ser usado para determinar o resultado do consentimento do usuário e o fluxo de login específico usado.

Quando um usuário faz login no seu site pela primeira vez, o Google pede autorização para compartilhar o perfil da conta dele com seu app. O perfil do usuário é compartilhado com seu app em um payload de credencial do token de ID somente após dar o consentimento. Revogar o acesso a esse perfil equivale a revogar um token de acesso na biblioteca de login anterior.

Os usuários podem revogar permissões e desconectar seu app da Conta do Google em https://myaccount.google.com/permissions. Como alternativa, eles podem se desconectar diretamente do app acionando uma chamada de API que você implementa. O método disconnect anterior foi substituído pelo método revoke mais recente.

Quando um usuário exclui a própria conta na sua plataforma, a prática recomendada é usar o revoke para desconectar seu app da Conta do Google.

Anteriormente, auth2.signOut() podia ser usado para ajudar a gerenciar a sair do usuário do seu app. Qualquer uso de auth2.signOut() precisaria ser removido, e seu app precisaria gerenciar diretamente o estado da sessão do usuário e o status de login.

Estado da sessão e listeners

A nova biblioteca não mantém o status de login ou o estado da sessão para seu app da Web.

O status de login de uma Conta do Google, bem como o estado da sessão e o status de login do app são conceitos diferentes e separados.

O status de login do usuário na Conta do Google e no seu app são independentes, exceto durante o momento do login, quando você sabe que o usuário foi autenticado com êxito e está conectado à Conta do Google.

Quando o recurso Fazer login com o Google, o login automático ou com um toque são incluídos no seu site, os usuários precisam primeiro fazer login na Conta do Google para:

  • autorizar o compartilhamento do perfil de usuário no primeiro login ou no seu site;
  • e depois para fazer login quando retornar ao site.

Os usuários podem permanecer conectados, desconectados ou alternar para outra Conta do Google, mantendo uma sessão ativa e conectada no seu site.

Agora você é responsável por gerenciar diretamente o status de login dos usuários do seu app da Web. Anteriormente, o Login do Google ajudava a monitorar o estado da sessão do usuário.

Remova todas as referências a auth2.attachClickHandler() e aos gerenciadores de callback registrados.

Antes, os Listeners eram usados para compartilhar mudanças no status de login da Conta do Google de um usuário. Não há mais suporte para listeners.

Remova todas as referências a listen(), auth2.currentUser e auth2.isSignedIn.

Cookies

O recurso Fazer login com o Google faz uso limitado de cookies. Veja a seguir uma descrição desses cookies. Consulte Como o Google usa cookies para mais informações sobre os outros tipos de cookies usados pelo Google.

O cookie G_ENABLED_IDPS definido pela biblioteca anterior da plataforma de Login do Google não é mais usado.

A nova biblioteca de Serviços de Identificação do Google pode definir esses cookies de vários domínios com base nas suas opções de configuração:

  • g_state armazena o status de logout do usuário e é definido quando o pop-up com um toque ou o login automático são utilizados.

  • g_csrf_token é um cookie de envio duplo usado para evitar ataques CSRF e definido quando o endpoint de login é chamado. O valor do URI de login pode ser definido explicitamente ou pode assumir como padrão o URI da página atual. O endpoint de login pode ser chamado sob estas condições ao usar:

    • API HTML com data-ux_mode=redirect ou quando data-login_uri for definido ou

    • API JavaScript com ux_mode=redirect e em que google.accounts.id.prompt() não é usado para mostrar login com um toque ou automático.

Se você tiver um serviço que gerencie cookies, adicione os dois novos cookies e remova o anterior quando a migração estiver concluída.

Se você gerencia vários domínios ou subdomínios, consulte Exibir um toque em subdomínios para mais instruções sobre como trabalhar com o cookie g_state.

Referência de migração de objetos para login do usuário

Antiga Novo Observações
Bibliotecas JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Substitua antigo por novo.
apis.google.com/js/api.js accounts.google.com/gsi/client Substitua antigo por novo.
GoogleAuth e métodos associados:
GoogleAuth.AttachClickHandler() IdConfiguration.callback para JS e data-callback Substitua antigo por novo.
GoogleAuth.currentUser.get() (link em inglês) CredentialResponse Use CredentialResponse, que não é mais necessária.
GoogleAuth.currentUser.listen(). Remover. O status de login atual de um usuário no Google não está disponível. Os usuários precisam fazer login no Google para consentimento e momentos de login. O campo select_by em CredentialResponse pode ser usado para determinar o resultado do consentimento do usuário com o método de login utilizado.
GoogleAuth.disconnect(). google.accounts.id.revoke (link em inglês) Substitua antigo por novo. A revogação também pode ocorrer em https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess(). Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
GoogleAuth.isSignedIn.get() Remover. O status de login atual de um usuário no Google não está disponível. Os usuários precisam fazer login no Google para consentimento e momentos de login.
GoogleAuth.isSignedIn.listen() Remover. O status de login atual de um usuário no Google não está disponível. Os usuários precisam fazer login no Google para consentimento e momentos de login.
GoogleAuth.signIn(). Remover. O carregamento do DOM em HTML do elemento g_id_signin ou a chamada do JS para google.accounts.id.renderButton aciona o login do usuário em uma Conta do Google.
GoogleAuth.signOut(). Remover. O status de login do usuário no seu app e em uma Conta do Google é independente. O Google não gerencia o estado da sessão do seu aplicativo.
GoogleAuth.then() Remover. O uso do GoogleAuth foi descontinuado.
GoogleUser e métodos associados:
GoogleUser.disconnect(). google.accounts.id.revoke (link em inglês) Substitua antigo por novo. A revogação também pode ocorrer em https://myaccount.google.com/permissions
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile(). CredentialResponse Use credential e subcampos diretamente em vez de métodos BasicProfile.
GoogleUser.getgrantedScopes() Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
Função GoogleUser.getHostedDomain() CredentialResponse Em vez disso, use credential.hd diretamente.
GoogleUser.getId(). CredentialResponse Em vez disso, use credential.sub diretamente.
GoogleUser.grantOff-lineAccess(). Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
GoogleUser.grant() Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
GoogleUser.hasgrantedScopes() Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
GoogleUser.isSignedIn() Remover. O status de login atual de um usuário no Google não está disponível. Os usuários precisam fazer login no Google para consentimento e momentos de login.
GoogleUser.reloadAuthResponse() Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
objeto gapi.auth2 e os métodos associados:
Objeto gapi.auth2.authorizedConfig Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
Objeto gapi.auth2.authorizedResponse Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
Objeto gapi.auth2.AuthResponse Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
gapi.auth2.authorized(). Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
gapi.auth2.ClientConfig(). Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
gapi.auth2.getAuthInstance() Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
gapi.auth2.init(). Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
Objeto gapi.auth2.offlineAccessOptions Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
Objeto gapi.auth2.SignInOptions Remover. Um token de ID substituiu os escopos e tokens de acesso do OAuth 2.0.
o objeto gapi.signin2 e os métodos associados:
gapi.signin2.render() Remover. O carregamento do DOM em HTML do elemento g_id_signin ou a chamada do JS para google.accounts.id.renderButton aciona o login do usuário em uma Conta do Google.