Migrar do Login do Google

Este guia ajuda a entender as mudanças e etapas necessárias para migrar bibliotecas JavaScript da versão anterior do Login do Google da plataforma 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 das APIs do Google para JavaScript ou outros bibliotecas anteriores para autorização, consulte Migrar para o Google Identity Services para mais informações.

Autenticação e autorização

A autenticação estabelece quem é uma pessoa 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, o app solicita o consentimento do usuário para acessar o Google Drive dele.

Assim como a biblioteca da plataforma de Login do Google, o novo modelo de identidade A biblioteca de serviços foi criada para dar suporte à autenticação e à autorização processos de negócios seguros.

No entanto, a biblioteca mais recente separa os dois processos para reduzir a complexidade para que os desenvolvedores integrem Contas do Google ao seu aplicativo.

Se o seu caso de uso diz respeito apenas à autenticação, continue lendo esta página.

Se seu caso de uso incluir autorização, leia Como funciona a autorização de usuários. e Migrar para os Serviços de Identificação do Google para garantir que seu aplicativo seja 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ários melhorias na usabilidade. Alguns destaques:

• Novos fluxos de login com um toque e de login automático de baixo atrito, com menos fluxos passos,
• um botão de login atualizado com personalização para os usuários,
• branding consistente e comportamento de login uniforme em toda a Web melhoram compreensão e confiança,
• acesso rápido ao conteúdo, os usuários podem se inscrever e fazer login diretamente de qualquer lugar no seu site sem precisar acessar a página de login ou da conta.

Para os desenvolvedores, nosso foco tem sido reduzir a complexidade, melhorar a segurança e para que sua integração seja o mais rápida possível. Estas são algumas dessas melhorias:

• A opção de adicionar o login do 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 OAuth 2.0 não é mais necessária para fazer login de usuários no seu site,
• os modos pop-up e de redirecionamento continuam a ser suportados, mas o OAuth do Google A infraestrutura do 2.0 agora redireciona para o endpoint de login do servidor de back-end,
• consolidação dos recursos das edições anteriores de identidade e bibliotecas JavaScript da API do Google em uma única biblioteca nova,
• para respostas de login, agora você pode decidir se quer ou não usar um Promise e a indireção por meio de funções de estilo getter têm foram removidos para simplificar.

Um exemplo de migração de login

Se você estiver migrando do botão de Login do Google atual e estiver apenas em fazer login dos usuários em seu site, a mudança mais direta é para atualizar para o novo botão personalizado. Isso pode ser feito pela troca Bibliotecas JavaScript e atualizando sua base de código para usar um novo objeto de login.

Bibliotecas e configuração

A biblioteca anterior da plataforma de Login do Google, apis.google.com/js/platform.js, e a biblioteca de cliente das APIs do Google para JavaScript: gapi.client, não estão necessário para a autenticação e a autorização do usuário. Eles foram substituído por uma única biblioteca JavaScript nova 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 foram carregados de apis.google.com. Para ajudar você a identificar locais em que a biblioteca anterior pode ser incluída no seu site, normalmente:

• 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 seu ID do cliente do aplicativo da Web atual credenciais. Como parte da migração, recomendamos que você consulte nossas Políticas do OAuth 2.0 e usar o Console de APIs do Google e, se necessário, atualize as seguintes configurações do cliente:

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

Identifique o código afetado e teste

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

Em apps grandes ou complexos, pode ser difícil encontrar todo o código afetado pelo descontinuação do módulo gapi.auth2. Para registrar o uso existente de recursos descontinuados no console, defina o valor do G_AUTH2_MIGRATION para informational. Opcionalmente, adicione dois-pontos seguidos por um valor-chave ao também registrarão no armazenamento de sessão. Depois de fazer login e receber as credenciais revisam ou enviam os registros coletados a um back-end para análise posterior. Para exemplo, informational:showauth2use salva a origem e o URL no armazenamento de uma sessão chamada showauth2use.

Para verificar o comportamento do app quando o módulo gapi.auth2 não estiver mais carregado, defina o do cookie G_AUTH2_MIGRATION para enforced. Isso permite testar 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 Registrar o uso de recursos descontinuados no console JS. Registrar também para o 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ê defina o cookie localmente durante o desenvolvimento e teste, antes de usá-lo em ambientes de produção.

HTML e JavaScript

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

A maneira anterior

<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>

<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>

Como será agora

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

<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>

<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>

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

Além de renderizar o novo botão personalizado, o código de exemplo também exibe o novo pop-up de um toque. Onde quer que você exiba o botão personalizado, é altamente recomendável exibir também o pop-up de um toque para minimizar o atrito durante a inscrição e o login.

Embora não seja recomendado devido ao aumento do atrito no login, a nova o botão personalizado pode ser mostrado sozinho, sem mostrar o Caixa de diálogo de 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 seu site. Como alternativa, use a função equivalente API JavaScript ou combinar APIs HTML e JavaScript no seu site.

Para visualizar interativamente opções de personalização de botões como, tipo de callback e atributos como cor, tamanho, forma, texto e tema, confira nosso Guia de gerador. Ela pode ser usada para comparar rapidamente diferentes opções 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 dos usuários de visitar uma página de login dedicada. Em outras palavras, Isso reduz o atrito na inscrição e no login, proporcionando aos usuários a flexibilidade inscrição e login em outras páginas além da sua.

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

Também recomendamos adicionar g_id_signin, que exibe o login personalizado somente nas páginas de login ou de gerenciamento da conta de usuário. Dar opções aos usuários para inscrição ou login exibindo o botão ao lado de outros provedores de identidade 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 o OAuth 2.0 códigos de autorização, tokens de acesso ou tokens de atualização. Em vez disso, um JSON Web Token O token de ID (JWT) é usado para compartilhar o status de login e o perfil do usuário. Como você não precisa mais usar "getter" estilo métodos do acessador para trabalhar com dados de perfil de usuário.

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

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

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

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

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

Além disso, e apenas no modo de redirecionamento, impeça a solicitação entre sites Falsificação (CSRF) e 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 O campo select_by no CredentialResponse pode ser usado para determinar se o usuário o resultado do consentimento e o fluxo de login específico usado.

Consentimento do usuário e revogação de permissão

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 após o consentimento é o perfil do usuário compartilhado com seu app em um payload de credencial de token de ID. Revogar o acesso a esse perfil equivale a revogar um token de acesso no biblioteca de login anterior.

Os usuários podem revogar permissões e desconectar o app da Conta do Google deles em https://myaccount.google.com/permissions. Como alternativa, eles podem se desconectar diretamente do app acionando uma API. chamada 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, é uma prática recomendada usar revoke para desconectar o app da Conta do Google.

Antes, era possível usar auth2.signOut() para ajudar a gerenciar a saída do usuário. do seu app. O uso do auth2.signOut() precisa ser removido, e seu app devem gerenciar diretamente o estado de sessão e o status de login por usuário.

Estado da sessão e listeners

A nova biblioteca não mantém o status de login ou da sessão na sua Web app.

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

O status de login do usuário na Conta do Google dele e seu app são independentes de cada um outro, exceto durante o próprio momento de login quando você sabe que o usuário autenticado com sucesso e conectado à 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 os usuários do site precisam primeiro fazer login na Conta do Google para:

• consentir em compartilhar o perfil de usuário durante a primeira inscrição; ou fazer login no seu site,
• e depois para fazer login quando retornar ao site.

Os usuários podem permanecer conectados, desconectados ou usar outra Conta do Google enquanto mantém 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 no monitoramento da estado da sessão.

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

Antes, os listeners eram usados para compartilhar alterações no status de login de um Conta do Google do 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. Uma descrição desses cookies segue. 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, opcionalmente, definir essas propriedades com base nas suas opções de configuração:

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

• g_csrf_token é um cookie de envio duplo usado para impedir ataques de CSRF. e é definido quando o endpoint de login é chamado. O valor do URI de login pode ser definido explicitamente ou pode usar o URI da página atual como padrão. Seu 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

  • API JavaScript com ux_mode=redirect e onde google.accounts.id.prompt() não é usado para exibir um toque ou 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 Exibir um toque em vários 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