Este guia explicativo ajuda você a tomar decisões sobre todos os principais problemas de integração.
Fazer login com o Google no resumo
Veja abaixo as etapas gerais para os usuários fazerem login ou se inscreverem no seu site.
Os usuários fazem login em um site do Google.
Para que o "Fazer login com o Google" funcione, é necessário que haja uma sessão do Google ativa no navegador. Um toque e o login automático 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 precisam fazer login no Google quando o botão é pressionado.
Os usuários navegam nas suas páginas da Web em que o botão de um toque, de login automático ou "Fazer login com o Google" está incorporado.
Os usuários interagem com um toque, o botão "Fazer login com o Google" e os fluxos de UX subsequentes para:
- Selecione uma sessão do Google ativa para continuar.
- Peça aos usuários finais para compartilhar informações de perfil com seu site, caso ainda não tenham consentido.
Quando há apenas uma sessão do Google ativa no navegador,
- Um toque seleciona a única sessão automaticamente e, assim, ignora 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 vai aparecer.
Depois da aprovação, o Google registra a decisão para pular a página de consentimento na próxima vez.
Uma credencial JSON Web Token, também conhecida como token de ID, que contém o nome, o e-mail e a foto do perfil do usuário é compartilhada por um gerenciador de callback JavaScript ou um envio de postagem para o serviço de back-end.
O objetivo de retornar tokens de ID ao gerenciador de callback JavaScript do lado do cliente não é decodificá-lo no código JavaScript, mas sim enviá-lo ao servidor do seu jeito. Um bom exemplo é usar um XmlHttpRequest para evitar a atualização da página causada pelo envio da postagem.
No lado do servidor, a credencial JWT emitida pelo Google é validada e consumida para criar uma nova conta ou estabelecer uma sessão autenticada no seu site.
Você 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 seu app são independentes entre si, exceto durante o momento do login em que você sabe que o usuário foi autenticado e conectado à Conta do Google. Os usuários podem permanecer conectados, podem 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 recurso 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, poderá ser necessário integrar também a API de autorização, caso seu site precise acessar as APIs e os serviços do Google em nome dos usuários autenticados. Enquanto a autenticação fornece ao site tokens de ID para autenticar usuários, a autorização fornece 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
Caso seu site precise chamar as APIs de autenticação e autorização, elas precisam ser chamadas 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 juntos no passado, ao usar a biblioteca JavaScript dos Serviços de Identificação do Google, será necessário ajustar sua UX para separar o momento da autenticação do momento da autorização.
- No momento da autenticação, o site pode ser integrado ao botão de um toque, login automático ou "Fazer login com o Google" para que os usuários possam fazer login ou se inscrever no site.
- No momento da autorização, seu site pode invocar a API de autorização para receber as permissões e os tokens de acesso às APIs ou aos serviços do Google.
Para uma transição tranquila da experiência do usuário e redução da complexidade, uma prática comum é dividir o processo em duas etapas separadas.
- Refatore a UX para separar os momentos de autenticação e autorização.
Migre para a biblioteca JavaScript dos Serviços de Identificação do Google.
API HTML versus API JavaScript
É possível usar a API HTML ou a API JavaScript para integrar o botão de um toque, de login automático ou de "Fazer login com o Google" às suas páginas da Web.
Com a API HTML, você tem mais recursos integrados. Por exemplo:
- Renderização com 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 que a UX de um toque, login automático ou pop-up/redirecionamento de botão for concluída. - Evite ataques CSRF com o método double-submit-cookie.
- Use o gerador de código para gerar o código HTML. Depois, basta copiá-lo nas suas páginas HTML.
Com a API HTML, você também pode escrever códigos JavaScript para personalizar o comportamento.
É possível 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 ao seu servidor, a fim de evitar o recarregamento da página causado pelo envio de postagens padrão.
Com a API JavaScript, você tem mais flexibilidade em alguns cenários, como mostrado abaixo.
- Renderização com 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 é mostrada.
- Gerar 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 será carregada mais tarde.
O código da API HTML só pode ser invocado uma vez no evento onload da página ou no evento 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 um toque e um botão. Verifique seu código, HTML e JavaScript, para saber onde 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()ourender()são invocados no seu código JavaScript, independentemente de estarem inline ou carregados em um arquivo JavaScript separado.
As APIs JavaScript abaixo podem ser usadas de forma independente 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 de pop-up, especialmente na Web para computadores, pode fornecer uma UX melhor 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 parecida com uma caixa de diálogo oferece uma experiência no contexto para a concessão de permissões.
Com a UX de pop-up, o provedor de identidade precisa criar usando canais de comunicação de origem cruzada do lado do cliente para transmitir as respostas OAuth da janela pop-up, onde a página de consentimento do provedor de identidade aparece, para a janela principal, onde a página de terceiros é mostrada. Normalmente, os códigos JavaScript são necessários em ambos os lados para enviar e receber a resposta OAuth nas janelas.
A UX de pop-up e de redirecionamento tem suporte do botão "Fazer login com o Google".
Por padrão, a UX pop-up é usada. É possível mudar a UX definindo o
atributo data-ux_mode.
Há algumas diferenças entre os fluxos de redirecionamento do botão "Fazer login com o Google" e o de redirecionamento do OAuth.
- O fluxo de redirecionamento do botão "Fazer login com o Google" sempre usa o método
POSTpara enviar a credencial ao seu servidor da Web, enquanto o redirecionamento do OAuth normalmente usa o métodoGET. - 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.
Independentemente da UX usada por desenvolvedores que usam a API HTML, as credenciais
sempre são enviadas ao data-login_uri com o método POST e os
mesmos parâmetros. Isso permite trocar o modo 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 há suporte para o uso do seu próprio botão. Não há API para iniciar programaticamente um fluxo de botão.
Para ativar o fluxo de botões "Fazer login com o Google", basta renderizar um ou mais botões desse recurso nas suas páginas da Web. O fluxo dos 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 projetar os botões de maneira interativa. Mesmo que você use a API JavaScript, é possível gerar o código HTML primeiro e depois copiá-lo nos campos correspondentes na API JavaScript.
Não há API para permitir que os sites controlem se as informações personalizadas serão usadas para renderizar os botões. Os botões personalizados serão exibidos se todas as condições forem atendidas. Veja mais detalhes 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. Você pode executá-lo várias vezes e copiar o código <div class='g_id_signin' ...></div> gerado para a página da Web.
Práticas recomendadas para renderização de botões
Por motivos de privacidade, o botão personalizado é mostrado em um iframe do domínio accounts.google.com. Carregar um iframe pode ser demorado em uma rede lenta. Para atenuar esse problema de latência, os botões são renderizados em duas etapas, da seguinte maneira:
- Uma versão de 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.
- 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 de 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 quanto antes. Considere carregar a biblioteca JavaScript antes de 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 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 Login no menu.
Considerações sobre o recurso de um toque
Login automático
O login automático cancelável oferece os benefícios a seguir.
- Ele pode melhorar a taxa de login ao salvar uma ação do usuário.
- Ao contrário do login silencioso fornecido pela biblioteca JavaScript de Login do Google descontinuada, os usuários sempre veem alguma IU quando o login automático acontece, o que dá a eles o contexto do motivo e de como eles se conectaram 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.
Ativar o login automático é uma decisão que você precisa tomar com base nos requisitos de UX e de negócios do seu site. Se a maioria das logouts do seu site for causada 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 recuperar o status da sessão.
Quando exibir a IU de um toque
Com a API HTML, o recurso "Um toque" sempre é exibido no carregamento da página. Com a API JavaScript
API, você pode controlar quando a interface de um toque é exibida. Observe que a IU de um toque nem sempre é exibida depois que a API é invocada, por alguns motivos, conforme descrito abaixo.
- Nenhuma sessão do Google ativa no navegador.
- Todas as sessões do Google ativas serão desativadas.
- O período de espera está em andamento.
Não tente exibir somente a interface de um toque em um evento de clique de botão. A IU de um toque pode não ser mostrada pelos motivos acima, e os usuários podem ter uma UX corrompida, já que nada é mostrado após a ação do usuário. Em um evento de clique de botão:
Recomendável
- Mostre a caixa de diálogo 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 recebam um método de login para seu site.
Não recomendado
- Com apenas um toque, os usuários poderão ter uma experiência de login corrompida se o recurso não for exibido.
- Uso de um callback de status da IU para mostrar outra IU se um toque não for exibido. Isso não é recomendado, já que o callback do status da IU pode não funcionar bem com o gerenciamento de credenciais federado 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 o Chrome no iOS, Safari e Firefox. Nesses navegadores, é fornecida uma UX diferente, começando com uma página de boas-vindas.
Se você quiser, a UX com um toque em navegadores ITP pode ser desativada. Consulte Suporte a um toque em navegadores ITP para mais detalhes.
Não há como ativar essa UX em navegadores que não sejam ITP, como o Chrome no Android/macOS/Linux e no Edge.
Cancelar a solicitação se o usuário sair da página
Por padrão, a solicitação de um toque será fechada automaticamente se o usuário clicar fora da solicitação. Esse comportamento pode ser alterado se você quiser.
Recomendamos manter a solicitação de um toque aberta na Web para computadores, já que o tamanho da tela é grande o suficiente.
Alterar 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, já que não é compatível com o 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 IU de um toque é usada em um contexto de login. A linguagem da IU contém textos específicos, como "fazer login". Você pode mudar o atributo de contexto para criar um conjunto diferente de palavras. É possível selecionar o cabeçalho com 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" |
Status da IU do recurso Ouvir com um toque
Para se integrar perfeitamente ao seu fluxo maior de UX, o recurso de um toque pode notificar você quando o status da IU mudar. No entanto, esse recurso não tem suporte em 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 site exibe um toque em vários subdomínios, é necessário indicar isso no código da API.
Um toque em páginas HTML estáticas
Por padrão, a biblioteca GIS pressupõe 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 de um toque deverá ser incluído na página resultante para acionar o recurso com um toque e permitir que os usuários façam login no seu site.
- Se os usuários já estiverem conectados, o código HTML de 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 HTML com um toque pode funcionar de outra maneira, que é projetada para sites que hospedam muito conteúdo HTML estático. Você sempre 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 já houver um cookie de sessão, o fluxo de um toque será ignorado.
Nesse caso, a ativaçã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 One Tap na sua página da Web.
Integração do lado do servidor
Depois que o fluxo de UX do botão "Fazer login com o Google", do login automático por um toque ou do botão "Fazer login com o Google" é concluído, um token de ID é emitido e compartilhado com seu site. Para autenticar o usuário, algumas alterações do 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 própria origem para lidar com as respostas no lado do servidor. Os fatores abaixo podem afetar a UX resultante.
- Se um toque ou o recurso "Fazer login com o Google" é acionado.
- Indica se a API HTML ou a API JavaScript é usada.
- Define se o URI de login ou a função de callback do JavaScript é usado para processar a resposta.
A UX real que você consegue é descrita abaixo.
Para o modo de UX de redirecionamento do botão "Fazer login com o Google":
- Se a API HTML ou a API JavaScript for usada, você precisará 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 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 IU do Google para seleção e aprovação da sessão.
Depois, uma
POSTde página inteira é enviada para o URI de login especificado.
Para o modo de UX do botão "Um toque" ou "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 callback do 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 concluírem a UX na janela de solicitação ou pop-up para seleção e aprovação da sessão, a função de callback do JavaScript receberá as respostas. A UX subsequente é decidida pela forma como a função de callback envia as respostas ao servidor.
Caso contrário (a API HTML com o caso do 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 concluem a UX na solicitação ou janela pop-up para
seleção e aprovação da sessão, as respostas de autenticação são enviadas usando
um envio
POSTde página inteira para o URL de login especificado.
Recomendamos usar uma maneira consistente para enviar as respostas de um toque e 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 pós-envio acionado pela biblioteca JavaScript do cliente do serviço de identidade do Google, é possível usar o padrão integrado de envio duplo de cookies. Consulte Verificar o token de código do Google no lado do servidor para mais detalhes.
- Para enviar para sua própria origem usando um XmlHttpRequest, use o cabeçalho HTTP personalizado ou outras medidas de segurança aprovadas por sua equipe de segurança.
Para verificar os tokens de ID nas respostas de autenticação, é recomendável usar uma biblioteca de cliente das APIs do Google para sua plataforma ou uma biblioteca JWT de uso geral.
Perguntas frequentes
O botão "Um toque e fazer login com o Google" está disponível em WebViews?
Não. Por questões de segurança, os usuários não devem adicionar sessões do Google a WebViews. Assim, os SIGs 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 biblioteca JavaScript do Login do Google, as partes confiáveis podiam usar as Diretrizes da promoção de 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 "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 "Fazer login com o Google" inconsistentes em todos os sites.
- Ao gerar pela biblioteca, não é necessário fazer mudanças quando as diretrizes da promoção de marca de login mudam.
Para aplicar essa regra, a biblioteca JavaScript apenas expõe uma API para renderizar um botão, mas não a API para iniciar o fluxo de login.
E se meu site ativar apenas o botão com um toque, mas não o botão "Fazer login com o Google"?
Recomendamos usar um toque e o botão "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 quiserem fazer login no seu site com as Contas do Google deles, eles poderão acessar a caixa de diálogo principal e usar 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 com um toque para que ele possa ser mostrado no próximo login. Outros fluxos de botões do Google não podem limpar os status de espera 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", talvez você note uma queda no desempenho do fluxo com um toque, já que os status de espera exponencial não são apagados 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 Identificação do Google analisa e executa o código da API HTML no evento de carregamento da biblioteca JavaScript ou no evento DomContentcarregado, o que ocorrer por último.
- Se o evento DomContentLoader 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 DomContentLoader. 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 independentes.
- Após a análise e a execução, as alterações subsequentes no código da API HTML serão ignoradas.
- Não há uma API para que os desenvolvedores acionem o processo de análise ou execução.