Considerações sobre integração

Este guia explicativo ajuda você a tomar decisões sobre os principais problemas de integração.

Fazer login com o Google no resumo

Confira a seguir as etapas gerais para os usuários fazerem login / se inscreverem no seu site.

  1. Os usuários fazem login em um site do Google.

    Para que o recurso "Fazer login com o Google" funcione, é necessário que haja uma sessão ativa do Google no navegador. O recurso "Um toque" e o login automático são acionados apenas quando os usuários fazem login no Google antes de carregar suas páginas da Web. Essa etapa é opcional para o fluxo do botão "Fazer login com o Google", já que os usuários são solicitados a fazer login no Google quando o botão é pressionado.

  2. Os usuários navegam nas suas páginas da Web em que o botão "Um toque", "Login automático" ou "Fazer login com o Google" está incorporado.

  3. Os usuários interagem com o One Tap, o botão "Fazer login com o Google" e os fluxos de UX subsequentes para:

    • Selecione uma sessão ativa do Google para continuar.
    • Receba o consentimento dos usuários finais para compartilhar informações do perfil com seu site, se ainda não tiver recebido.

    Quando há apenas uma sessão ativa do Google no navegador,

    • O recurso "Um toque" seleciona a única sessão automaticamente e, portanto, pula a página de escolha da conta.
    • O botão "Fazer login com o Google" permanece na página de escolha da conta, o que permite que os usuários adicionem uma nova sessão do Google quando necessário.

    Se a Conta do Google selecionada não tiver sido usada antes com seu site ou a permissão tiver sido revogada, uma página de consentimento será exibida.

    Tela de consentimento do botão "Fazer login com o Google"

    Depois que a aprovação for concedida, o Google vai registrar a decisão para pular a página de consentimento na próxima vez.

  4. Uma credencial de token da Web JSON (também chamada de token de ID) contendo o nome, o e-mail e a foto do perfil do usuário é compartilhada usando um gerenciador de callback JavaScript ou um envio de postagem para o serviço de back-end.

    O objetivo de retornar tokens de ID para o manipulador de callback JavaScript no lado do cliente não é para você decodificá-lo no código JavaScript, mas para que você o envie ao servidor da sua própria maneira. Um bom exemplo é usar um XmlHttpRequest para evitar a recarga da página causada pelo envio da postagem.

  5. No lado do servidor, a credencial JWT emitida pelo Google é validada e usada para criar uma nova conta ou estabelecer uma sessão autenticada no seu site.

    Você vai gerenciar o status de login do usuário no seu próprio site.

    O status de login da Conta do Google do usuário e o app são independentes um do outro, exceto durante o próprio login, quando você sabe que o usuário foi autenticado e fez login na Conta do Google. 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.

Em resumo, assim como o login baseado em senha, o Assine com o Google oferece outra maneira de autenticar usuários na Web. O recurso Fazer login com o Google não oferece recursos para o gerenciamento de sessões no seu site após a autenticação.

Acesse APIs e serviços do Google

Embora você tenha integrado a API de autenticação, conforme descrito anteriormente, talvez também seja necessário integrar a API de autorização se o site precisar acessar APIs e serviços do Google em nome de usuários autenticados. Enquanto a autenticação oferece ao seu site tokens de ID para autenticar usuários, a autorização oferece ao site tokens de acesso (separados) e permissões para usar APIs e serviços do Google. Consulte Como autorizar para a Web para mais informações.

Separação de UX para autenticação e autorização

Se o site precisar chamar as APIs de autenticação e autorização, faça isso separadamente em momentos diferentes. Consulte Como separar os momentos de autenticação e autorização.

Se o site já solicitou tokens de autenticação e autorização juntos no passado, ao usar a biblioteca JavaScript do Google Identity Services, é necessário ajustar a UX para separar o momento da autenticação do momento da autorização.

  • No momento da autenticação, seu site pode ser integrado ao One Tap, ao login automático ou ao botão "Fazer login com o Google" para permitir que os usuários façam login ou se inscrevam no seu site.
  • No momento da autorização, seu site pode invocar a API de autorização para receber as permissões e os tokens necessários para acessar as APIs ou os serviços do Google.

Para uma transição de UX suave e redução da complexidade, uma prática comum é dividir o processo em duas etapas separadas.

  1. Reformule a UX para separar os momentos de autenticação e autorização.
  2. Migrar para a biblioteca JavaScript dos Serviços de Identificação do Google.

API HTML e API JavaScript

É possível usar a API HTML ou a API JavaScript para integrar o botão "Fazer login com o Google", "Fazer login automático" ou "Fazer login com um toque" às suas páginas da Web.

Com a API HTML, você tem mais recursos integrados. Por exemplo,

  • Renderização do botão "Um toque" ou "Fazer login com o Google" no carregamento da página.
  • Envie a credencial retornada para o endpoint do servidor, que é especificado pelo atributo data-login_uri, depois que a UX do pop-up/redirecionamento de botão ou do login automático for concluída.
  • Evite ataques CSRF usando o cookie de envio duplo.
  • Use o gerador de código para gerar o código HTML e copie-o nas suas páginas HTML.

Com a API HTML, você também pode escrever JavaScript para personalizar o comportamento.

  • Você pode escrever seu próprio gerenciador de callbacks e definir o nome da função como o atributo data-callback. Um bom exemplo é usar um XmlHttpRequest para enviar a credencial retornada ao servidor, evitando a recarga da página causada pelo envio de postagem padrão.

Com a API JavaScript, você tem mais flexibilidade em alguns cenários.

  • Renderização do One Tap e do botão "Fazer login com o Google" em um momento posterior. Por exemplo, depois que os usuários selecionam Login no menu.
  • Chamar a API várias vezes. Por exemplo, o botão "Fazer login com o Google" precisa ser renderizado sempre que a caixa de diálogo de login for renderizada.
  • Geração dinâmica de páginas HTML, o que dificulta a incorporação de códigos de chamada de API a elas.
  • Você carrega a biblioteca JavaScript dos Serviços de Identificação do Google muito mais tarde.

O código da API HTML só pode ser invocado uma vez no evento de carregamento da página ou no evento de carregamento da biblioteca JavaScript dos Serviços de identidade do Google, o que ocorrer mais tarde. Use a API JavaScript se o comportamento da API HTML não atender às suas expectativas.

Não use a API HTML com a API JavaScript na mesma página da Web para inicializar a página ou para renderizar o botão e o recurso Um toque. Verifique se há lugares em que o código, HTML e JavaScript, se sobrepõem. Observe o seguinte:

  • Você está usando a API HTML se um ou mais dos elementos em <div id='g_id_onload' ... ><id> ou <div class='g_id_signin' ...></div> existirem no código HTML.
  • Você está usando a API JavaScript se um ou mais dos métodos em initialize(), prompt() ou render() são invocados no código JavaScript, não importa se eles são inline ou carregados de um arquivo JavaScript separado.

As APIs JavaScript a seguir podem ser usadas independentemente da inicialização ou da renderização de um toque e do botão. Elas não têm APIs HTML correspondentes:

Considerações sobre o botão "Fazer login com o Google"

Esta seção discute as considerações para integrar o botão "Fazer login com o Google" ao seu site.

Pop-up e redirecionamento

A especificação OAuth 2.0 considera o redirecionamento HTTP, mas não tem orientação sobre como renderizar caixas de diálogo pop-up. A UX do pop-up, especialmente na Web para computador, pode proporcionar uma melhor experiência para os usuários finais. Isso ocorre porque os usuários não são redirecionados para fora das páginas de terceiros, e uma janela pop-up semelhante a uma caixa de diálogo oferece uma experiência no contexto para a concessão de permissão.

Com a UX do pop-up, o provedor de identidade precisa criar canais de comunicação entre origens do lado do cliente para transmitir respostas do OAuth da janela pop-up, em que a página de consentimento do provedor de identidade está sendo exibida, para a janela principal, em que a página de terceiros está sendo exibida. Normalmente, os códigos JavaScript são necessários em ambos os lados para enviar e receber a resposta OAuth em várias janelas.

A UX do pop-up e do redirecionamento são compatíveis com o botão "Fazer login com o Google". Por padrão, a UX do pop-up é usada. É possível mudar a UX definindo o atributo data-ux_mode.

Há algumas diferenças entre o fluxo de redirecionamento do botão "Fazer login com o Google" e o fluxo de redirecionamento do OAuth.

  • O fluxo de redirecionamento do botão "Fazer login com o Google" sempre usa o método POST para enviar a credencial ao servidor da Web, enquanto o redirecionamento do OAuth normalmente usa o método GET.
  • Os parâmetros enviados pelo fluxo de redirecionamento do botão "Fazer login com o Google" são diferentes dos do fluxo de redirecionamento do OAuth.

Para desenvolvedores que usam a API HTML, não importa qual UX é usada, as credenciais são sempre enviadas para o data-login_uri com o método POST e os mesmos parâmetros. Isso permite alternar o modo de UX sem outras mudanças de código. Para a UX de redirecionamento, o data-login_uri precisa ser adicionado aos URIs de redirecionamento autorizados do seu cliente no Console das APIs do Google.

Personalização de botões

Não é possível usar seu próprio botão. Não há uma API para iniciar programaticamente um fluxo de botão.

Para ativar o fluxo do botão "Fazer login com o Google", basta renderizar um ou mais botões "Fazer login com o Google" nas suas páginas da Web. O fluxo de botões é inicializado e processado de forma transparente quando os usuários clicam nesses botões.

A API de renderização de botões permite personalizar a aparência do botão "Fazer login com o Google". Recomendamos o uso do gerador de código para projetar os botões de forma interativa. Mesmo que você use a API JavaScript, é possível gerar o código HTML primeiro e, em seguida, copiar o código para os campos correspondentes na API JavaScript.

Não há uma API que permita que os sites controlem se as informações personalizadas precisam ser usadas para renderizar os botões. Os botões personalizados vão ser exibidos se todas as condições forem atendidas. Mais detalhes em Como entender o botão "Personalizado".

É possível colocar vários botões na mesma página da Web. O gerador de código só pode criar um botão por vez. Você pode executá-lo várias vezes e copiar o código <div class='g_id_signin' ...></div> gerado na página da Web.

Práticas recomendadas de renderização de botões

Por motivos de privacidade, o botão personalizado é mostrado em um iframe do domínio accounts.google.com. O carregamento de um iframe pode ser demorado em uma rede lenta. Para reduzir esse problema de latência, os botões são renderizados em duas etapas, da seguinte maneira:

  1. Uma versão do botão inline é renderizada na árvore DOM do seu site. É apenas um botão de texto, nenhuma informação personalizada pode ser usada. O objetivo é permitir que os usuários vejam o botão o mais rápido possível.
  2. Uma solicitação de iframe é enviada ao Google para carregar o iframe do botão, que pode ter informações personalizadas. Quando o iframe do botão é carregado, o botão da versão inline é removido.

Confira algumas práticas recomendadas para minimizar a latência de exibição do botão do fluxo de botões "Fazer login com o Google".

  • Carregue a biblioteca JavaScript dos Serviços de Identificação do Google o mais cedo possível. Considere carregar a biblioteca JavaScript antes de algumas outras bibliotecas grandes, especialmente na Web para dispositivos móveis.
  • Se o botão "Fazer login com o Google" for renderizado somente depois que o usuário selecionar Fazer login no menu. Você pode renderizar o botão "Fazer login com o Google" em um elemento oculto primeiro e depois torná-lo visível depois que o usuário selecionar Fazer login no menu.

Considerações sobre o recurso Um toque

Login automático

O recurso de login automático permite que os usuários façam login no seu site sem clicar no comando "Um toque" se tiverem concedido permissão ao site.

O login automático cancelável oferece os seguintes benefícios:

  • Isso pode melhorar a taxa de login salvando uma ação do usuário.
  • Ao contrário do login silencioso fornecido pela biblioteca JavaScript Login do Google anterior e descontinuada, os usuários sempre veem uma interface quando o login automático acontece, o que fornece o contexto de por que e como eles estão conectados ao seu site. Os usuários também podem cancelar se quiserem.
  • Ele seleciona automaticamente a conta que o usuário usou antes, o que pode impedir que o usuário crie contas duplicadas no seu site.

A decisão de ativar o login automático precisa ser tomada com base no UX e nos requisitos de negócios do seu site. Especialmente se a maioria dos deslogamentos do seu site forem causados pelo tempo limite da sessão em vez de escolhas explícitas do usuário, o login automático pode ser uma boa maneira de os usuários recuperarem o status da sessão.

Quando mostrar a interface de um toque

Com a API HTML, o botão "Um toque" aparece sempre que a página é carregada. Com a API JavaScript, você pode controlar quando a interface de um toque é exibida. A interface do One Tap pode não aparecer sempre após a invocação da API pelos seguintes motivos.

  • Nenhuma sessão ativa do Google no navegador.
  • Todas as sessões ativas do Google estão desativadas.
  • O tempo de espera está em andamento.

Não tente mostrar apenas a interface de um toque em um evento de clique de botão. A interface do One Tap pode não aparecer devido aos motivos listados, e os usuários podem ter uma UX corrompida, já que nada aparece após a ação do usuário. Em um evento de clique em botão:

Recomendado

  • Mostre a caixa de diálogo de login com a senha e o botão "Fazer login com o Google" e chame a API One Tap ao mesmo tempo. Isso garante que os usuários sempre tenham um método de login para o site.

Não recomendado

  • Se você oferecer apenas o recurso Um toque, os usuários poderão ter uma experiência de login interrompida se ele não for exibido.
  • Usar um callback de status da interface para mostrar outra interface se o recurso Um toque não aparecer. Isso não é recomendado, porque o callback de status da interface pode não funcionar bem com o gerenciamento de credenciais federadas em uma versão futura.

Um toque em navegadores ITP

Devido à Prevenção de Rastreamento Inteligente (ITP, na sigla em inglês), a UX normal de um toque não funciona em navegadores ITP, como o Chrome no iOS, Safari e Firefox. Uma UX diferente, que começa com uma página de boas-vindas, é fornecida nesses navegadores.

A UX de um toque em navegadores com ITP pode ser desativada, se você quiser. Consulte Suporte ao recurso One Tap em navegadores ITP para mais detalhes.

Não é possível ativar essa UX em navegadores que não são ITP, como o Chrome no Android/macOS/Linux e o Edge.

Cancelar a solicitação se o usuário clicar em outro lugar

Por padrão, o comando "Um toque" é fechado automaticamente se o usuário clicar fora dele. Esse comportamento pode ser alterado, se você quiser.

Recomendamos manter o comando de um toque aberto na Web para computador, já que o tamanho da tela é grande o suficiente.

Mudar a posição da UX de um toque

Na Web para computador, é possível mudar a posição do comando "Um toque". No entanto, esse recurso não é recomendado, já que não tem suporte do gerenciamento de credenciais federadas em uma versão futura.

Mudar o contexto de login

O recurso "Um toque" precisa fazer parte de um fluxo de UX maior no seu site. Por padrão, a interface One Tap é usada em um contexto de login. A linguagem na interface contém expressões específicas, como "fazer login". É possível mudar o atributo de contexto para criar um conjunto diferente de palavras. É possível selecionar um dos cabeçalhos de um toque que melhor se adapta ao seu fluxo de UX.

Contexto
signin "Fazer login com o Google"
signup "Inscrever-se com o Google"
use "Usar com o Google"

Ouvir o status da interface do recurso "Com um toque"

Para integrar perfeitamente ao seu fluxo de UX maior, o One Tap pode notificar você quando o status da IU mudar. No entanto, esse recurso não é compatível com versões futuras do gerenciamento de credenciais federadas.

Um toque em subdomínios

Por padrão, o tempo de espera do recurso Um toque e outros status são rastreados por origem. Se o site mostrar o recurso Um toque em vários subdomínios, você precisará indicar isso no código da API.

Um toque em páginas HTML estáticas

Por padrão, a biblioteca GIS presume que suas páginas da Web são geradas dinamicamente. Seu servidor HTTP verifica o status de login do usuário ao gerar o código HTML.

  • Se nenhum usuário estiver conectado, o código HTML do One Tap precisará ser incluído na página resultante para acionar o One Tap e permitir que os usuários façam login no site.
  • Se os usuários já estiverem conectados, o código HTML do One Tap não será incluído na página resultante.

Nesse caso, é responsabilidade do servidor da Web adicionar ou remover o código da API HTML do One Tap.

O código da API One Tap HTML pode funcionar de outra maneira, que foi projetada para sites que hospedam muito conteúdo HTML estático. Você pode incluir o código da API HTML One Tap nas páginas HTML estáticas e especificar o nome do cookie de sessão usado no site.

  • Se o cookie de sessão não existir, o fluxo de um toque será acionado.
  • Se o cookie de sessão existir, o fluxo do One Tap será ignorado.

Nesse caso, o acionamento do fluxo de um toque é controlado pelo status do cookie da sessão, e não pela existência do código da API HTML de um toque na página da Web.

Integração do lado do servidor

Depois que o OneTap, o login automático ou o fluxo de UX do botão "Fazer login com o Google" for concluído, um token de ID será emitido e compartilhado com seu site. Para autenticar o usuário, algumas mudanças no servidor são necessárias para receber e validar o token de ID.

Considerações sobre UX

Normalmente, é necessário adicionar um endpoint HTTP na sua própria origem para processar as respostas no servidor. Os fatores a seguir podem afetar a UX resultante.

A UX real que você recebe é descrita da seguinte maneira.

  1. Para o modo de UX de redirecionamento do botão "Fazer login com o Google":

    • Seja a API HTML ou a API JavaScript, é necessário definir o URI de login. É impossível usar uma função de callback JavaScript para processar a resposta, já que os usuários já foram redirecionados para fora da página da Web.
    • Resumo da UX: depois de clicar no botão "Fazer login com o Google", os usuários veem um redirecionamento de página inteira para uma interface do Google para seleção e aprovação da sessão. Depois disso, uma POST de página inteira é enviada para o URI de login especificado.
  2. Para o modo de UX do pop-up do botão "Fazer login com o Google" ou "Fazer login com o Google", se a API JavaScript for usada ou se a API HTML for usada e uma função de callback JavaScript for fornecida:

    • As respostas de autenticação são transmitidas de volta para a função de callback JavaScript.
    • Resumo da UX: o comando "One Tap" ou uma janela pop-up é mostrado acima da página da Web. Depois que os usuários concluem a UX na janela de comando ou pop-up para seleção e aprovação da sessão, a função de callback do JavaScript recebe as respostas. A UX subsequente é decidida por como a função de callback envia as respostas para o servidor.
  3. Caso contrário (a API HTML com o caso de URI de login):

    • As respostas de autenticação são enviadas ao URI de login.
    • Resumo da UX: o comando "One Tap" ou uma janela pop-up é mostrado acima da página da Web. Depois que os usuários concluem a UX na janela de solicitação ou pop-up para seleção e aprovação da sessão, as respostas de autenticação são enviadas usando um envio de POST de página inteira para o URL de login especificado.

Recomendamos que você use uma maneira consistente para enviar as respostas do recurso Um toque e as respostas do botão Fazer login com o Google.

Considerações sobre segurança

Para evitar ataques de falsificação de solicitações entre sites,

  • Para o envio de postagens acionado pela biblioteca JavaScript do cliente do serviço de identidade do Google, use o padrão de envio duplo de cookies integrado. Consulte Verificar o token de ID do Google no servidor para mais detalhes.
  • Para envio à sua própria origem usando um XmlHttpRequest, use o cabeçalho HTTP personalizado ou outras medidas de segurança aprovadas pela equipe de segurança.

Para verificar os tokens de ID nas respostas de autenticação, é recomendável usar uma biblioteca de cliente de API do Google para sua plataforma ou uma biblioteca JWT de uso geral.

Perguntas frequentes

  • O botão "Fazer login com o Google" e "Um toque" está disponível em visualizações da Web?

    Não. Por motivos de segurança, os usuários não podem adicionar sessões do Google a visualizações da Web. Portanto, as SIGs são desativadas em visualizações da Web, já que nenhuma sessão do Google deve estar presente.

  • Posso usar meu próprio botão "Fazer login com o Google"? Não. Com o fluxo do lado do servidor do OAuth ou a versão anterior da biblioteca JavaScript do Login do Google, as partes confiáveis podiam usar as Diretrizes de branding do Login para criar as próprias versões dos botões do Login do Google.

    No entanto, o recurso "Fazer login com o Google" foi removido. Todos os botões do recurso Fazer login com o Google precisam ser gerados pela biblioteca JavaScript dos Serviços de Identificação do Google. Há dois motivos para essa mudança.

    • Algumas partes confiáveis não seguiram as diretrizes, o que resulta em botões "Fazer login com o Google" inconsistentes nos sites.
    • Ao gerar pela biblioteca, não é necessário fazer mudanças quando as Diretrizes de branding de login mudam.

    Para aplicar essa regra, a biblioteca JavaScript expõe apenas uma API para renderizar um botão, mas não a API para iniciar o fluxo de login.

  • E se meu site só ativar o recurso "Um toque", mas não o botão "Fazer login com o Google"?

    Recomendamos usar o recurso Um toque e o botão "Fazer login com o Google" no seu site. Devido ao tempo de espera exponencial, o recurso Um toque pode não ser exibido sempre. Quando os usuários realmente quiserem fazer login no seu site com as próprias Contas do Google, eles poderão acessar a caixa de diálogo de login principal e fazer login com o botão "Fazer login com o Google". Um login bem-sucedido usando o botão "Fazer login com o Google" limpa o status de espera do recurso para que ele possa ser mostrado no próximo login. Outros fluxos de botões do Google não podem limpar os status de tempo de espera do recurso Um toque, porque eles estão em binários JavaScript diferentes.

    Se o site só ativar o recurso Um toque, mas não o botão "Fazer login com o Google", a performance do fluxo Um toque pode cair, já que os status de espera não são limpos a tempo.

  • Quando meu código da API HTML é analisado? Posso mudar meu código da API HTML mais tarde?

    A biblioteca JavaScript dos Serviços de identidade do Google analisa e executa o código da API HTML no evento de carregamento da biblioteca JavaScript ou no evento DomContentLoaded, o que ocorrer por último.

    • Se o evento DomContentLoaded for acionado quando a biblioteca JavaScript for carregada, o código da API HTML será analisado e executado imediatamente.
    • Caso contrário, a biblioteca JavaScript vai adicionar um listener para o evento DomContentLoaded. Quando acionado, o listener analisa e executa o código da API HTML.

    Além disso, a análise e a execução do código da API HTML são desativadas.

    • Após a análise e execução, todas as mudanças subsequentes no código da API HTML são ignoradas.
    • Não há uma API para que os desenvolvedores acionem o processo de análise ou execução.