Migrar do Login do Google

Este guia ajuda a entender as mudanças e etapas necessárias para migrar com sucesso as bibliotecas JavaScript da biblioteca da plataforma Login do Google para a biblioteca de Serviços de Identificação do Google mais recente 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 verifica a identidade de alguém e também pode ser chamada de inscrição ou login do usuário. A autorização é o processo de conceder ou negar acesso a dados ou recursos. Por exemplo, seu app pede o consentimento do usuário para acessar o Google Drive dele.

Assim como a biblioteca da plataforma Google Sign-In, a nova biblioteca de Serviços de Identificação do Google (em inglês) 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 de integração das Contas do Google ao app para desenvolvedores.

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

Se o seu caso de uso incluir autorização, leia Como funciona a autorização do usuário e Migrar 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 login automático e com um toque de baixa fricção com menos etapas individuais.
  • um botão de login atualizado com personalização do usuário;
  • uma marca consistente e um comportamento de login uniforme na 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 seu site sem precisar acessar uma página de login ou de conta.

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

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

Exemplo de migração de login

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

Bibliotecas e configuração

A biblioteca da plataforma de Login do Google anterior: apis.google.com/js/platform.js e a biblioteca de cliente das 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 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 fazer login são carregados de apis.google.com. Para ajudar você a identificar locais em que a biblioteca anterior pode estar incluída no seu site, geralmente:

  • o botão de login padrão carrega apis.google.com/js/platform.js,
  • um gráfico de botão personalizado é carregado 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 as credenciais do ID do cliente do aplicativo da Web. Como parte da migração, recomendamos que você revise 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:

  • seus apps de teste e produção usam projetos separados e têm IDs de cliente próprios.
  • o tipo de ID do cliente OAuth 2.0 é "Aplicativo da Web", e
  • O HTTPS é usado para origens JavaScript autorizadas 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 o uso atual de recursos que serão descontinuados em breve no console, defina o valor do cookie G_AUTH2_MIGRATION como informational. Opcionalmente, adicione dois-pontos seguidos por um valor de chave para também registrar no armazenamento de sessão. Depois de fazer login e receber credenciais, revise ou envie os 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 é mais carregado, defina o valor do cookie G_AUTH2_MIGRATION como enforced. Isso permite testar o comportamento pós-suspensão de uso antes da data de aplicação.

Valores possíveis de cookies G_AUTH2_MIGRATION:

  • enforced Não carregue o módulo gapi.auth2.
  • informational Registra o uso de recursos descontinuados no console JS. Também faça o registro 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

Neste cenário de login somente para autenticação, são mostrados exemplos de código e renderizações do botão de Login do Google. Selecione o modo pop-up ou redirecionamento para ver as diferenças em como a resposta de autenticação é processada por um callback JavaScript ou por um redirecionamento seguro para o endpoint de login do servidor de back-end.

A maneira anterior

Renderize o botão "Fazer login com o Google" e use um callback para processar o login diretamente do 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

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

Usuário conectado ao Google

O texto do botão de atualização do status de login do usuário.

Como será agora

Para usar a nova biblioteca em um cenário de login somente de autenticação, selecione o modo pop-up ou de redirecionamento e use o exemplo de código para substituir sua 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 o endpoint de login conforme especificado pelo atributo data-login_url. Antes, você era responsável pela operação POST e pelo nome do parâmetro. A nova biblioteca envia o token de ID para seu 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 do Um Toque junto com o botão personalizado para melhorar a taxa de login.

Botão Fazer login com o Google Pop-up de 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 consentimento ou em visitas recorrentes, o botão personalizado inclui o nome, o e-mail e a foto do perfil do usuário.

Neste exemplo 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 exemplo de código também mostra o novo pop-up do um toque. Recomendamos que você mostre o pop-up de um toque sempre que exibir o botão personalizado para minimizar o atrito do usuário durante o registro e o login.

Embora não seja recomendado devido ao aumento da dificuldade de login, o novo botão personalizado pode ser mostrado sozinho, sem exibir simultaneamente a caixa de diálogo do 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 o login ao seu site. Como alternativa, use a API JavaScript, que tem a mesma funcionalidade, ou combine APIs HTML e JavaScript no seu site.

Para conferir interativamente as opções de personalização de botões, como tipo de callback e atributos como cor, tamanho, forma, texto e tema, acesse nosso gerador de código. Ele pode ser usado para comparar rapidamente diferentes opções e gerar snippets de HTML para uso no seu site.

Fazer login em qualquer página com o recurso "Login com um toque"

O recurso "Um toque" é uma nova maneira de os usuários se inscreverem ou fazerem login no seu site com menos atrito. 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 acessarem uma página de login dedicada. Em outras palavras, isso reduz o atrito de inscrição e login, aos usuários a flexibilidade de se inscrever e fazer login em páginas diferentes da sua página de login.

Para ativar o login em qualquer página, recomendamos incluir 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 de contas de usuário. Ofereça opções aos usuários para inscrição ou login mostrando o botão ao lado de outros botões de provedor de identidade federada e campos de entrada de nome de usuário e senha.

Resposta de 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 JSON Web Token (JWT) é usado para compartilhar o status de login e o perfil do usuário. Para simplificar ainda mais, não é mais necessário usar métodos de acesso no estilo "getter" para trabalhar com dados de perfil do usuário.

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

  • para o gerenciador de callback JavaScript baseado em navegador do usuário no modo pop-up, ou
  • para seu servidor de back-end por um redirecionamento do Google para seu 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:

  • ligações 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 JWT CredentialResponse para trabalhar com dados de perfil do usuário.

Além disso, e somente para o modo de redirecionamento, evite a falsificação de solicitações entre sites (CSRF) e verifique o token de ID do Google no servidor de back-end.

Para entender melhor como os usuários interagem com seu site, o campo select_by em 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 solicita o consentimento dele para compartilhar o perfil da conta com seu app. Somente depois de dar o consentimento, o perfil do usuário é compartilhado com seu app em uma carga útil de credencial do token de ID. Revogar o acesso a esse perfil é equivalente 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 acessando https://myaccount.google.com/permissions. Como alternativa, eles podem se desconectar diretamente do app acionando uma chamada de API implementada por você. O método disconnect anterior foi substituído pelo método revoke mais recente.

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

Antes, o auth2.signOut() podia ser usado para gerenciar o encerramento da sessão do usuário no app. Remova qualquer uso do auth2.signOut() e faça com que o app gerencie diretamente o estado da sessão por usuário e o status de login.

Estado da sessão e listeners

A nova biblioteca não mantém o status conectado nem o estado da sessão do seu app da Web.

O status de login de uma Conta do Google e o estado da sessão e o status de login do seu app são conceitos distintos 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 e fez login na Conta do Google.

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

  • dar consentimento para compartilhar o perfil de usuário ao se inscrever ou fazer login no seu site pela primeira vez;
  • e depois para fazer login em visitas recorrentes ao seu site.

Os usuários podem permanecer conectados, sair ou mudar 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. Antes, 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 manipuladores de callback registrados.

Antes, os Listeners eram usados para compartilhar mudanças no status de login de uma Conta do Google de um usuário. Os listeners não são mais compatíveis.

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

Cookies

O recurso Fazer login com o Google usa cookies de forma limitada. Confira uma descrição deles a seguir. 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 de plataforma de login do Google anterior não é mais usado.

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

  • O g_state armazena o status de saída do usuário e é definido ao usar o pop-up de um toque ou o login automático.

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

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

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

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

Se você gerencia vários domínios ou subdomínios, consulte Mostrar o One Tap 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

Antigo Novidade Observações
Bibliotecas JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Substitua o antigo pelo novo.
apis.google.com/js/api.js accounts.google.com/gsi/client Substitua o antigo pelo novo.
Objeto GoogleAuth e métodos associados:
GoogleAuth.attachClickHandler() IdConfiguration.callback para JS e HTML data-callback Substitua o antigo pelo novo.
GoogleAuth.currentUser.get() CredentialResponse Use CredentialResponse. Não é mais necessário.
GoogleAuth.currentUser.listen() Remover. O status de login atual de um usuário no Google está indisponível. Os usuários precisam fazer login no Google para consentir e fazer login. O campo select_by em CredentialResponse pode ser usado para determinar o resultado do consentimento do usuário junto com o método de login usado.
GoogleAuth.disconnect() google.accounts.id.revoke Substitua o antigo pelo novo. A revogação também pode ocorrer em https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
GoogleAuth.isSignedIn.get() Remover. O status de login atual de um usuário no Google está indisponível. Os usuários precisam fazer login no Google para consentir e fazer login.
GoogleAuth.isSignedIn.listen() Remover. O status de login atual de um usuário no Google está indisponível. Os usuários precisam fazer login no Google para consentir e fazer login.
GoogleAuth.signIn() Remover. O carregamento do DOM HTML do elemento g_id_signin ou a chamada 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 são independentes. O Google não gerencia o estado da sessão do seu app.
GoogleAuth.then() Remover. O GoogleAuth foi descontinuado.
Objeto GoogleUser e métodos associados:
GoogleUser.disconnect() google.accounts.id.revoke Substitua o antigo pelo novo. A revogação também pode ocorrer em https://myaccount.google.com/permissions
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() CredentialResponse Use diretamente credential e subcampos em vez de métodos BasicProfile.
GoogleUser.getGrantedScopes() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
GoogleUser.getHostedDomain() CredentialResponse Em vez disso, use credential.hd diretamente.
GoogleUser.getId() CredentialResponse Em vez disso, use credential.sub diretamente.
GoogleUser.grantOfflineAccess() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
GoogleUser.grant() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
GoogleUser.hasGrantedScopes() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
GoogleUser.isSignedIn() Remover. O status de login atual de um usuário no Google está indisponível. Os usuários precisam fazer login no Google para consentir e fazer login.
GoogleUser.reloadAuthResponse() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
Objeto gapi.auth2 e métodos associados:
Objeto gapi.auth2.AuthorizeConfig Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
Objeto gapi.auth2.AuthorizeResponse Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
Objeto gapi.auth2.AuthResponse Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
gapi.auth2.authorize() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
gapi.auth2.ClientConfig() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
gapi.auth2.getAuthInstance() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
gapi.auth2.init() Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
Objeto gapi.auth2.OfflineAccessOptions Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
Objeto gapi.auth2.SignInOptions Remover. Um token de ID substituiu os tokens de acesso e escopos do OAuth 2.0.
Objeto gapi.signin2 e métodos associados:
gapi.signin2.render() Remover. O carregamento do DOM HTML do elemento g_id_signin ou a chamada JS para google.accounts.id.renderButton aciona o login do usuário em uma Conta do Google.