Migrar do Login do Google

Este guia ajuda a entender as mudanças e etapas necessárias para migrar bibliotecas JavaScript da biblioteca da plataforma do Login do Google anterior para a nova biblioteca dos 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 Identificação 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, o app solicita o consentimento do usuário para acessar o Google Drive dele.

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

No entanto, a biblioteca mais recente separa os dois processos para reduzir a complexidade da integração de Contas do Google com o app.

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

Se o caso de uso incluir autorização, leia Como a autorização do usuário funciona e Migrar para os Serviços de identidade do Google para garantir que o 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 com um toque e automáticos de baixa fricção com menos etapas individuais,
• um botão de login atualizado com personalização para os usuários,
• O branding consistente e o comportamento uniforme de login em toda a Web melhoram a compreensão e a confiança,
• acessar rapidamente o conteúdo. Os usuários podem se inscrever e fazer login diretamente em qualquer lugar do seu site sem precisar acessar uma página de login ou conta.

Para desenvolvedores, nosso foco tem sido 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 o login do usuário ao conteúdo estático do 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 dos usuários no seu site.
• Os modos de 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 anteriores do Google Identity e da API JavaScript do Google em uma única biblioteca nova,
• Para respostas de login, agora você pode decidir se vai usar ou não uma Promise, e a inversão por 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ó 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 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 do Login do Google: 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 a 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 você a identificar locais em que a biblioteca anterior pode ser incluída no seu site, geralmente 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, você pode 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:

• 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 JavaScript autorizadas 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 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 de recursos que serão descontinuados no console, defina o valor do cookie G_AUTH2_MIGRATION como informational. Opcionalmente, adicione dois-pontos seguidos de um valor de chave para também fazer o registro no armazenamento de sessão. Após o login e o recebimento da análise de credenciais ou o envio de 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-descontinuação antes da data de ativação.

Valores possíveis do cookie G_AUTH2_MIGRATION:

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

Para minimizar o impacto no usuário, recomendamos que você 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 de autenticação, são mostrados exemplos de código e renderizações do botão de Login do Google atual. Selecione o modo pop-up ou redirecionamento para conferir as diferenças na forma como a resposta de autenticação é processada por um callback do JavaScript ou por um redirecionamento seguro para o endpoint de login do servidor de back-end.

Como era antes

<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 o modo pop-up ou de redirecionamento e use o exemplo de código para substituir a implementação atual na 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 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 exibe o novo pop-up de um toque. Onde quer que você mostre o botão personalizado, recomendamos que você também mostre o pop-up de um toque para minimizar a fricção do usuário durante o registro 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 com 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, você pode usar a API JavaScript funcionalmente equivalente ou misturar 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, confira nosso gerador de código. Ele pode ser usado para comparar rapidamente diferentes opções e gerar trechos de HTML para uso no seu site.

Fazer login em qualquer página com um toque

O recurso "Com um toque" é uma nova maneira fácil de 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 acessarem uma página de login dedicada. Em outras palavras, isso reduz o atrito na inscrição e no login, aos usuários a flexibilidade de fazer login e se inscrever em outras páginas.

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 exibe o botão de login personalizado, somente nas páginas de login ou de gerenciamento da conta do usuário. Dê aos usuários opções de inscrição ou login mostrando o botão com outros botões de provedor de identidade federado 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 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 de estilo "getter" para trabalhar com dados de perfil de usuário.

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

• ao gerenciador de callback JavaScript baseado no navegador do usuário no modo pop-up ou
• para seu 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 retorno de chamada existentes 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 a subcampos credential no novo objeto CredentialResponse do JWT para trabalhar com dados do perfil do usuário.

Além disso, e apenas no modo de redirecionamento, evite a falsificação de solicitações entre sites (CSRF, na sigla em inglês) e verifique 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.

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 para compartilhar o perfil da conta dele com o app. Somente após o consentimento é que o perfil do usuário é compartilhado com o app em um payload de credencial de token de ID. 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 abrindo 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, é recomendável usar revoke para desconectar o app da Conta do Google.

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

Estado da sessão e listeners

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

O status de login de uma Conta do Google e o estado e o status de login do app são conceitos distintos.

O status de login do usuário na Conta do Google e no seu app são independentes um do outro, exceto durante o próprio login, quando você sabe que o usuário se autenticou e fez login na Conta do Google.

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

• consentir em 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 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. Antes, o Login do Google ajudava a monitorar o estado de 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. 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" faz uso limitado de cookies. Confira a 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 de plataforma do Google Sign-In anterior não é mais usado.

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

• O g_state armazena o status de desativação 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 CSRF e é definido quando o endpoint de login é chamado. O valor do URI de login pode ser definido explicitamente ou pode ser definido como 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 é 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 cookies novos e remova o anterior quando a migração for concluída.

Se você gerenciar vários domínios ou subdomínios, consulte Exibir o botão "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