Considerações sobre integração

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

Fazer login com o Google em resumo

Abaixo estão 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, é preciso haver uma sessão ativa do Google no navegador. O login automático e com um toque são acionados somente 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 recebem uma solicitação para fazer login no Google quando o botão é pressionado.

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

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

    • Selecione uma sessão ativa do Google para continuar.
    • Solicite o consentimento dos usuários finais para compartilhar informações de perfil com seu site, caso ainda não tenham feito isso.

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

    • Um toque seleciona a única sessão automaticamente e, assim, pula a página do seletor de conta.
    • O botão "Fazer login com o Google" permanece na página do seletor de 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 se a permissão tiver sido revogada, uma página de consentimento será exibida.

    Consentimento do botão "Fazer login com o Google"

    Após a aprovação, o Google registrará a decisão para pular a página de consentimento na próxima vez.

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

    O objetivo de retornar tokens de ID ao gerenciador de callbacks do JavaScript no lado do cliente não é que você os decodifique no código JavaScript, mas sim que eles sejam enviados ao seu servidor do seu próprio jeito. Um bom exemplo é usar um XmlHttpRequest para evitar a atualização da página causada pelo envio da postagem.

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

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

    O status de login na Conta do Google do usuário e seu app são independentes um do outro, exceto durante o próprio momento de login, quando você sabe que o usuário foi autenticado com êxito e fez login na Conta do Google. Os usuários podem permanecer conectados, sair ou mudar para uma Conta do Google diferente, mantendo uma sessão ativa conectada no seu site.

Em resumo, assim como o login baseado em senha, o Fazer login 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 acima, 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 fornece tokens de ID ao site para autenticar os usuários, a autorização fornece 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 da UX para autenticação e autorização

Se o site precisar chamar 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á tiver solicitado tokens de autenticação e autorização antes, ao usar a biblioteca JavaScript dos Serviços de Identificação do Google, será necessário ajustar a UX para separar o momento de autenticação do momento de autorização.

  • No momento da autenticação, seu site pode ser integrado aos botões de um toque, login automático ou 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 tranquila de UX e redução de complexidade, uma prática comum é dividir o processo em duas etapas separadas.

  1. Refatorar a UX para separar os momentos de autenticação e autorização.

  2. Migre para a biblioteca JavaScript dos Serviços de Identificação do Google.

API HTML versus API JavaScript

Você pode usar a API HTML ou a API JavaScript para integrar os botões de um toque, de login automático ou de login com o Google às suas páginas da Web.

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

  • Renderizando um toque ou o botão "Fazer login com o Google" no carregamento da página.
  • Envie a credencial retornada para o endpoint do lado do servidor, que é especificado pelo atributo data-login_uri, depois de um toque, login automático ou UX de pop-up/redirecionamento de botão.
  • Evite ataques CSRF com o double-submit-cookie.
  • 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 código JavaScript para personalizar o comportamento.

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

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

  • Renderizando um toque e o botão "Fazer login com o Google" em um momento posterior. Por exemplo, depois que os usuários selecionarem 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.
  • gerar suas páginas HTML dinamicamente, dificultando a incorporação de código de chamada de API nelas;
  • A biblioteca JavaScript dos Serviços de Identificação do Google é carregada muito mais tarde.

O código da API HTML só pode ser invocado uma vez no evento onload da página ou no evento onload da biblioteca JavaScript dos Serviços de Identificação do Google, o que ocorrer depois. 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 com um toque e botão. Verifique seu código, HTML e JavaScript, para ver os locais em que eles podem se sobrepor. Observe o seguinte:

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

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

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

Pop-up versus redirecionamento

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

Com a UX pop-up, o provedor de identidade precisa se basear nos canais de comunicação de origem cruzada do lado do cliente para transmitir respostas OAuth da janela pop-up, em que a página de consentimento do provedor de identidade é exibida, para a janela principal, em que a página de terceiros é exibida. Normalmente, os códigos JavaScript são necessários nos dois lados para enviar e receber a resposta OAuth em todas as janelas.

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

Existem 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 daqueles do fluxo de redirecionamento do OAuth.

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

Personalização do botão

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

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

A API de renderização do botão permite personalizar a aparência do botão "Fazer login com o Google". Recomendamos usar o gerador de código para criar seus botões de maneira interativa. Mesmo que você use a API JavaScript, pode gerar o código HTML primeiro e depois copiá-lo nos campos correspondentes na API.

Não há 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 aparecer se todas as condições forem atendidas. Saiba mais em Entender o botão personalizado.

Você pode colocar vários botões na mesma página da Web. O gerador de código só pode criar um botão por vez. É possível 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 é exibido 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, desta maneira:

  1. Uma versão de botão inline é renderizada na árvore do 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. Depois que o iframe do botão for carregado, o botão da versão in-line será removido.

Algumas práticas recomendadas para minimizar a latência da exibição do botão de fluxo do botão "Fazer login com o Google" estão listadas abaixo.

  • 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 grandes bibliotecas, 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. Primeiro, você pode renderizar o botão "Fazer login com o Google" em um elemento oculto e, em seguida, torná-lo visível depois que o usuário selecionar Login no menu.

Considerações com um toque

Login automático

O login automático cancelável oferece os benefícios a seguir.

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

A ativação do login automático é uma decisão que você precisa tomar com base nos requisitos de UX e de negócios do seu site. O login automático pode ser uma boa maneira de recuperar o status da sessão se a maioria das saídas do seu site for causada pelo tempo limite da sessão, e não por escolhas explícitas do usuário.

Quando exibir a interface de um toque

Com a API HTML, um toque sempre é exibido no carregamento da página. Com a API JavaScript, você pode controlar quando a interface de um toque é mostrada. A interface de um toque nem sempre é mostrada depois que a API é invocada, por alguns motivos descritos abaixo.

  • Não há sessões do Google ativas no navegador.
  • Todas as sessões ativas do Google são desativadas.
  • O resfriamento está em andamento.

Não tente exibir apenas a interface de um toque em um evento de clique de botão. A interface de um toque pode não ser mostrada pelos motivos acima, e os usuários podem ter uma UX corrompida, já que nada é mostrada após a ação do usuário. Em um evento de clique de botão:

Recomendável

  • Mostre a caixa de diálogo de login com o login por senha e o botão "Fazer login com o Google" e chame a API com um toque ao mesmo tempo. Isso garante que os usuários sempre recebam algum método de login no seu site.

Não recomendado

  • Com a opção de apenas um toque, os usuários podem ter uma experiência de login corrompida se "Um toque" não for exibido.
  • Usar um callback de status da interface para mostrar outra interface se um toque não for exibido. Isso não é recomendado porque o callback de status da interface pode não funcionar bem com o gerenciamento de credenciais federados 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 com um toque não funciona em navegadores ITP, como Chrome no iOS, Safari e Firefox. Uma UX diferente começando com uma página de boas-vindas é fornecida nesses navegadores.

A UX com um toque em navegadores ITP pode ser desativada se você quiser. Consulte Suporte com um toque em navegadores ITP para mais detalhes.

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

Cancelar a solicitação se o usuário sair da página

Por padrão, a solicitação de um toque é fechada automaticamente se o usuário clica fora da solicitação. É possível mudar isso.

Recomendamos manter a solicitação de um toque aberta na Web para computadores, já que o tamanho da tela é grande o suficiente.

Mudar a posição da UX com um toque

Na Web para computadores, você pode mudar a posição da solicitação de um toque. No entanto, esse recurso não é recomendado porque não tem suporte do gerenciamento de credenciais federados em uma versão futura.

Mudar o contexto de login

Um toque deve fazer parte de um fluxo maior de UX no seu site. Por padrão, a interface de um toque é usada em um contexto de login. O idioma da interface contém textos específicos, como "fazer login". É possível alterar o atributo de contexto para criar um conjunto diferente de palavras. É possível selecionar o cabeçalho de um toque mais adequado ao seu fluxo de UX.

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

Ouvir o status da interface com um toque

Para se integrar perfeitamente ao seu fluxo de UX maior, um toque pode enviar uma notificação quando o status da interface mudar. No entanto, esse recurso não será compatível com versões futuras do gerenciamento de credenciais federados.

Um toque em vários subdomínios

Por padrão, o período de espera com um toque e outros status são rastreados por origem. Se o seu site exibir um toque em vários subdomínios, você precisará indicar isso no seu código de API.

Um toque em páginas HTML estáticas

Por padrão, a biblioteca de SIG presume que suas páginas da Web são geradas dinamicamente. O 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 com um toque precisará ser incluído na página resultante para acionar um toque e permitir que os usuários façam login no seu site.
  • Se os usuários já tiverem feito login, o código HTML com um toque não deverá ser incluído na página resultante.

Nesse caso, é responsabilidade do servidor da Web adicionar ou remover o código da API HTML com um toque.

O código da API One Tap HTML pode funcionar de outra maneira, projetada para sites que hospedam muito conteúdo HTML estático. Você pode incluir o código da API HTML com um toque nas suas páginas HTML estáticas e especificar o nome do cookie de sessão usado no seu 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 de um toque será ignorado.

Nesse caso, a ativação ou não do fluxo de um toque é controlada pelo status do cookie de sessão, em vez da existência do código da API HTML com um toque na sua página da Web.

Integração do lado do servidor

Após um toque, o login automático ou o fluxo de UX do botão "Fazer login com o Google", um token de ID é emitido e compartilhado com seu site. Para autenticar o usuário, algumas alterações no lado do 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 lidar com as respostas no lado do servidor. Os fatores a seguir podem ter um impacto na UX resultante.

A UX real recebida está descrita abaixo.

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

    • Se a API HTML ou a API JavaScript forem usadas, você precisará definir o URI de login. É impossível usar uma função de callback JavaScript para lidar com a resposta, porque os usuários já foram redirecionados para fora da sua 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, um POST de página inteira será enviado ao URI de login especificado.

  2. Para o modo de UX pop-up de um toque ou do botão "Fazer login com o Google", se a API JavaScript for usada ou a API HTML for usada e uma função de callback JavaScript for fornecida:

    • As respostas de autenticação são retornadas à função de retorno de chamada JavaScript.
    • Resumo da UX: a solicitação de um toque ou uma janela pop-up é mostrada acima da página da Web. Depois que os usuários terminam a UX na solicitação ou na janela pop-up para seleção e aprovação da sessão, a função de callback JavaScript recebe as respostas. A UX subsequente é decidida pela forma como a função de callback envia as respostas ao servidor.

  3. Caso contrário (a API HTML com o URI de login):

    • As respostas de autenticação são enviadas ao URI de login.
    • Resumo da UX: a solicitação de um toque ou uma janela pop-up é mostrada acima da página da Web. Depois que os usuários terminam a UX na solicitação ou na janela 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 usar uma maneira consistente de enviar as respostas de 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 envios de postagens acionados pela biblioteca JavaScript de cliente do Google Identity Service, use o padrão integrado de cookies de envio duplo. Consulte Verificar o token de ID do Google no seu servidor para mais detalhes.
  • Para fazer o envio à sua própria origem usando um XmlHttpRequest, use o cabeçalho HTTP personalizado ou outras medidas de segurança aprovadas pela sua equipe de segurança.

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

Perguntas frequentes

  • O botão "Um toque e login com o Google" está disponível nas WebViews?

    Não. Por questões de segurança, os usuários não devem adicionar sessões do Google em WebViews. Portanto, os SIG são desativados em WebViews, já que nenhuma sessão do Google deve estar lá.

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

    No entanto, o recurso "Fazer login com o Google" removeu esse recurso. Todos os botões do 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 leva a botões do "Fazer login com o Google" inconsistentes nos sites.
    • Ao gerar pela biblioteca, não é necessário fazer mudanças quando as próprias diretrizes da promoção de marca 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 ativar o botão "Um toque", mas não o "Fazer login com o Google"?

    Recomendamos usar os botões "Um toque" e "Fazer login com o Google" no seu site. Devido ao resfriamento exponencial, é possível que o recurso "Um toque" não seja exibido todas as vezes. Quando os usuários realmente querem fazer login no seu site com as Contas do Google, eles podem acessar a caixa de diálogo de login principal e usar o botão "Fazer login com o Google". Um login bem-sucedido usando o botão "Fazer login com o Google" limpará o status de resfriamento com um toque para que ele possa ser exibido no próximo login. Outros fluxos de botões do Google não podem limpar os status de resfriamento com um toque, já que eles estão em binários JavaScript diferentes.

    Se o site ativar apenas um toque, mas não o botão "Fazer login com o Google", poderá haver uma queda no desempenho do fluxo de um toque, já que os status de resfriamento exponencial não são apagados a tempo.

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

    A biblioteca JavaScript dos Serviços de Identificação 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 depois.

    • 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 adicionará um listener ao 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 seu código da API HTML são únicas.

    • Após a análise e a execução, todas as alterações subsequentes no código da API HTML serão ignoradas.
    • Os desenvolvedores não têm uma API para acionar o processo de análise ou execução.