Referência da API HTML Fazer login com o Google

Esta página de referência descreve a API de atributos de dados HTML do recurso Fazer login com o Google. Você pode usar a API para mostrar o botão "Fazer login com o Google" ou o prompt do recurso "Um toque" nas suas páginas da Web.

Elemento com ID "g_id_onload"

Você pode colocar atributos de dados do Fazer login com o Google em qualquer elemento visível ou invisível, como <div> e <span>. O único requisito é que o ID do elemento seja definido como g_id_onload. Não coloque esse ID em vários elementos.

Atributos de dados

A tabela a seguir lista os atributos de dados com as respectivas descrições:

Tipos de atributo

As seções a seguir contêm detalhes sobre o tipo de cada atributo e um exemplo.

data-client_id

Esse atributo é o ID do cliente do seu app, que é encontrado e criado no console do Google Cloud. Consulte a tabela a seguir para mais informações:

data-auto_prompt

Esse atributo determina se o recurso "Um toque" será exibido ou não. O valor padrão é true. O toque único do Google One não é mostrado quando esse valor é false. Consulte a tabela a seguir para mais informações:

data-auto_select

Esse atributo determina se um token de ID será retornado automaticamente, sem interação do usuário, se apenas uma sessão do Google tiver aprovado seu app. O valor padrão é false. Consulte a tabela a seguir para mais informações:

data-login_uri

Esse atributo é o URI do seu endpoint de login.

O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou na plataforma de autenticação do Google e precisa estar de acordo com nossas regras de validação de URI de redirecionamento.

Esse atributo pode ser omitido se a página atual for sua página de login. Nesse caso, a credencial é postada nessa página por padrão.

A resposta de credencial do token de ID é postada no endpoint de login quando nenhuma função de callback é definida e um usuário clica nos botões "Fazer login com o Google" ou "Um toque", ou quando o login automático é realizado.

O endpoint de login precisa processar solicitações POST que contenham um parâmetro credential com um valor de token de ID no corpo.

Consulte a tabela a seguir para mais informações:

data-callback

Esse atributo é o nome da função JavaScript que processa o token de ID retornado. Consulte a tabela a seguir para mais informações:

Um dos atributos data-login_uri e data-callback pode ser usado. Ele depende das seguintes configurações de componentes e modo de UX:

• O atributo data-login_uri é obrigatório para o modo de UX do botão Fazer login com o Google redirect, que ignora o atributo data-callback.

• Um desses dois atributos precisa ser definido para o modo de UX do Google One Tap e do botão Fazer login com o Google popup. Se ambos forem definidos, o atributo data-callback terá maior precedência.

As funções JavaScript em um namespace não são compatíveis com a API HTML. Em vez disso, use uma função global do JavaScript sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-native_login_uri

Esse atributo é o URL do endpoint do manipulador de credenciais de senha. Se você definir o atributo data-native_login_uri ou o atributo data-native_callback, a biblioteca JavaScript vai usar o gerenciador de credenciais integrado quando não houver uma sessão do Google. Não é permitido definir os atributos data-native_callback e data-native_login_uri. Consulte a tabela a seguir para mais informações:

data-native_callback

Esse atributo é o nome da função JavaScript que processa a credencial de senha retornada pelo gerenciador de credenciais integrado do navegador. Se você definir o atributo data-native_login_uri ou data-native_callback, a biblioteca JavaScript vai usar o gerenciador de credenciais integrado quando não houver uma sessão do Google. Não é possível definir data-native_callback e data-native_login_uri. Consulte a tabela a seguir para mais informações:

As funções JavaScript em um namespace não são compatíveis com a API HTML. Em vez disso, use uma função global do JavaScript sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-native_id_param

Ao enviar a credencial de senha para o endpoint do gerenciador de credenciais de senha, é possível especificar o nome do parâmetro para o campo credential.id. O nome padrão é email. Consulte a tabela a seguir para mais informações:

data-native_password_param

Ao enviar a credencial de senha para o endpoint do gerenciador de credenciais de senha, é possível especificar o nome do parâmetro para o valor credential.password. O nome padrão é password. Consulte a tabela a seguir para mais informações:

data-cancel_on_tap_outside

Esse atributo define se a solicitação do One Tap será cancelada ou não se o usuário clicar fora da solicitação. O valor padrão é true. Para desativar, defina o valor como false. Consulte a tabela a seguir para mais informações:

data-prompt_parent_id

Esse atributo define o ID do DOM do elemento contêiner. Se não estiver definido, o prompt do toque único vai aparecer no canto superior direito da janela. Consulte a tabela a seguir para mais informações:

data-skip_prompt_cookie

Usa um cookie para controlar a exibição do pedido de um toque. Se o cookie especificado por esse atributo tiver um valor não vazio, o aviso não será mostrado. Consulte a tabela a seguir para mais informações:

data-nonce

Esse atributo é uma string aleatória usada pelo token de ID para evitar ataques de repetição. Consulte a tabela a seguir para mais informações:

O comprimento do nonce é limitado ao tamanho máximo do JWT compatível com seu ambiente, e às restrições de tamanho HTTP individuais do navegador e do servidor.

data-context

Esse campo muda o texto do título e das mensagens mostradas no prompt do toque único, sem efeito para navegadores ITP. O valor padrão é signin.

Consulte a tabela a seguir para mais informações:

A tabela a seguir lista todos os contextos disponíveis e as descrições deles:

data-moment_callback

Esse atributo é o nome da função do listener de notificação de status da interface do usuário de solicitação. Para mais informações, consulte o tipo de dados PromptMomentNotification.

Consulte a tabela a seguir para mais informações:

As funções JavaScript em um namespace não são compatíveis com a API HTML. Em vez disso, use uma função global do JavaScript sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-state_cookie_domain

Se você precisar mostrar o recurso "Um toque" em um domínio principal e nos subdomínios dele, transmita o domínio principal para esse atributo para que um único cookie de estado compartilhado seja usado. Consulte a tabela a seguir para mais informações:

data-ux_mode

Esse atributo define o fluxo de UX usado pelo botão "Fazer login com o Google". O valor padrão é popup. Esse atributo não tem impacto na experiência de toque único. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os modos de UX disponíveis e as descrições deles.

data-allowed_parent_origin

As origens que podem incorporar o iframe intermediário. O recurso Um toque é executado no modo de iframe intermediário se esse atributo estiver presente. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os tipos de valores compatíveis e as descrições deles.

Se o valor do atributo data-allowed_parent_origin for inválido, a inicialização do One Tap do modo de iframe intermediário vai falhar e parar.

Prefixos curinga também são aceitos. Por exemplo, "https://*.example.com" corresponde a example.com e aos subdomínios em todos os níveis (por exemplo, news.example.com, login.news.example.com). Ao usar caracteres curinga, tenha em mente o seguinte:

• As strings de padrão não podem ser compostas apenas por um caractere curinga e um domínio de nível superior. Por exemplo, https://.com e https://.co.uk são inválidos porque "https://.example.com" corresponde a example.com e todos os subdomínios dele. Use uma lista separada por vírgulas para representar dois domínios diferentes. Por exemplo, "https://example1.com,https://.example2.com" corresponde aos domínios example1.com, example2.com e aos subdomínios de example2.com
• Domínios com caracteres curinga precisam começar com um esquema https:// seguro. Portanto, "*.example.com" é considerado inválido.

data-intermediate_iframe_close_callback

Substitui o comportamento padrão do iframe intermediário quando os usuários fecham manualmente o One Tap tocando no botão "X" na interface do One Tap. O comportamento padrão é remover o iframe intermediário do DOM imediatamente.

O campo data-intermediate_iframe_close_callback só entra em vigor no modo de iframe intermediário. e tem impacto apenas no iframe intermediário, em vez do iframe do One Tap. A interface de um toque é removida antes da invocação do callback.

As funções JavaScript em um namespace não são compatíveis com a API HTML. Em vez disso, use uma função global do JavaScript sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-itp_support

Esse campo determina se a experiência do usuário do One Tap atualizada deve ser ativada em navegadores que oferecem suporte à Prevenção Inteligente de Rastreamento (ITP, na sigla em inglês). O valor padrão é false. Consulte a tabela a seguir para mais informações:

data-login_hint

Se o aplicativo souber com antecedência qual usuário deve fazer login, ele poderá fornecer uma dica de login ao Google. Quando a operação é bem-sucedida, a seleção de contas é ignorada. Os valores aceitos são: um endereço de e-mail ou um campo sub de token de ID.

Para mais informações, consulte a documentação do OpenID Connect para login_hint.

data-hd

Quando um usuário tem várias contas e só deve fazer login com a conta do Workspace, use isso para fornecer uma dica de nome de domínio ao Google. Quando a operação é bem-sucedida, as contas de usuário mostradas durante a seleção são limitadas ao domínio fornecido. Um valor curinga: * oferece apenas contas do Workspace ao usuário e exclui contas pessoais ([email protected]) durante a seleção de contas.

Para mais informações, consulte a documentação do OpenID Connect para hd.

data-use_fedcm_for_prompt

Permitir que o navegador controle os pedidos de login do usuário e medie o fluxo de login entre seu site e o Google. O padrão é "false". Consulte a página Migrar para a FedCM para mais informações.

data-use_fedcm_for_button

Esse campo determina se a UX do botão FedCM deve ser usada no Chrome (computador M125+ e Android M128+). O padrão é false. Consulte a tabela a seguir para mais informações:

data-button_auto_select

Esse campo determina se a opção seleção automática será ativada para o fluxo de botões da FedCM. Se ativada, os usuários recorrentes com uma sessão do Google ativa vão fazer login automaticamente, ignorando a solicitação do seletor de contas. O padrão é false. É necessário ativar explicitamente o login automático do botão durante o lançamento da ativação. Consulte a tabela a seguir para mais informações:

Elemento com a classe "g_id_signin"

Se você adicionar g_id_signin ao atributo class de um elemento, ele será renderizado como um botão "Fazer login com o Google".

É possível renderizar vários botões "Fazer login com o Google" na mesma página. Cada botão pode ter configurações visuais próprias. As configurações são definidas pelos seguintes atributos de dados.

Atributos de dados visuais

A tabela a seguir lista os atributos de dados visuais e as descrições deles:

Tipos de atributo

As seções a seguir contêm detalhes sobre o tipo de cada atributo e um exemplo.

data-type

O tipo de botão. O valor padrão é standard. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista todos os tipos de botão disponíveis e as respectivas descrições:

Tipo
standard
icon

data-theme

O tema do botão. O valor padrão é outline. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os temas disponíveis e as descrições deles:

Tema
outline
filled_blue
filled_black

data-size

O tamanho do botão. O valor padrão é large. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os tamanhos de botão disponíveis e as descrições deles.

Tamanho
large
medium
small

data-text

O texto do botão. O valor padrão é signin_with. Não há diferenças visuais no texto dos botões de ícone com atributos data-text diferentes. A única exceção é quando o texto é lido para acessibilidade da tela.

Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os textos de botão disponíveis e as descrições deles:

Texto
signin_with
signup_with
continue_with
signin

data-shape

É o formato do botão. O valor padrão é rectangular. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os formatos de botão disponíveis e as descrições deles:

Forma
rectangular
pill
circle
square

data-logo_alignment

O alinhamento do logotipo do Google. O valor padrão é left. Esse atributo se aplica apenas ao tipo de botão standard. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os alinhamentos disponíveis e as descrições deles:

logo_alignment
left
center

data-width

A largura mínima do botão, em pixels. A largura máxima disponível é de 400 pixels.

Consulte a tabela a seguir para mais informações:

data-locale

Opcional. Mostra o texto do botão usando a localidade especificada. Caso contrário, usa as configurações padrão da Conta do Google ou do navegador dos usuários. Adicione o parâmetro hl e o código do idioma à diretiva src ao carregar a biblioteca. Por exemplo: gsi/client?hl=<iso-639-code>.

Se não for definido, será usada a localidade padrão do navegador ou a preferência do usuário da sessão do Google. Portanto, usuários diferentes podem ver versões diferentes de botões localizados, possivelmente com tamanhos diferentes.

Consulte a tabela a seguir para mais informações:

data-click_listener

É possível definir uma função JavaScript para ser chamada quando o botão "Fazer login com o Google" for clicado usando o atributo data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

Neste exemplo, a mensagem Botão "Fazer login com o Google" clicado... é registrada no console quando o botão "Fazer login com o Google" é clicado.

data-state

Opcional. Como vários botões "Fazer login com o Google" podem ser renderizados na mesma página, você pode atribuir uma string exclusiva a cada botão. A mesma string seria retornada com o token de ID. Assim, você pode identificar em qual botão o usuário clicou para fazer login.

Consulte a tabela a seguir para mais informações:

Integração no servidor

Seus endpoints do lado do servidor precisam processar as seguintes solicitações HTTP POST.

O endpoint do gerenciador de token de ID

O endpoint do gerenciador de token de ID processa o token de ID. Com base no status da conta correspondente, você pode fazer login do usuário e direcioná-lo para uma página de inscrição ou de vinculação de contas para mais informações.

Exemplo de solicitação para seu endpoint de login:

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

A solicitação HTTP POST contém as seguintes informações:

credencial

Quando decodificado, o token de ID fica assim:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "[email protected]", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

O campo sub é um identificador globalmente exclusivo da Conta do Google. Use apenas o campo sub como identificador do usuário, já que ele é exclusivo entre todas as Contas do Google e nunca é reutilizado.

Usando os campos email, email_verified e hd, você pode determinar se o Google hospeda e é autoridade para um endereço de e-mail. Nos casos em que o Google é autoridade, o usuário é confirmado como o proprietário legítimo da conta.

Casos em que o Google é autoridade:

• email tem um sufixo @gmail.com, essa é uma conta do Gmail.
• email_verified é verdadeiro e hd está definido, essa é uma conta do Google Workspace.

Os usuários podem se registrar para ter Contas do Google sem usar o Gmail ou o Google Workspace. Quando email não contém um sufixo @gmail.com e hd está ausente, o Google não é autoritário, e é recomendável usar senha ou outros métodos de desafio para verificar o usuário. email_verified também pode ser verdadeiro, já que o Google verificou o usuário quando a Conta do Google foi criada. No entanto, a propriedade da conta de e-mail de terceiros pode ter mudado desde então.

O campo exp mostra o prazo para verificar o token no lado do servidor. É de uma hora para o token de ID obtido com o recurso Fazer login com o Google. Você precisa verificar o token antes do prazo de validade. Não use exp para gerenciamento de sessões. Um token de ID expirado não significa que o usuário está desconectado. Seu app é responsável pelo gerenciamento de sessões dos usuários.

g_csrf_token

Um token de estado antifalsificação. Este é um token de falsificação de solicitação entre sites (CSRF) criado pela biblioteca gsi/client. Um valor aleatório é incluído como um cookie e como um parâmetro de solicitação no corpo do payload POST. Se esses dois valores não corresponderem ao processar a solicitação no seu servidor, ela será considerada inválida.

select_by

A tabela a seguir lista os valores possíveis para o campo select_by. O tipo de botão usado com a sessão e o estado de consentimento são usados para definir o valor.

• O usuário pressionou o botão de um toque ou "Fazer login com o Google" ou usou o processo de login automático sem toque.

• Uma sessão existente foi encontrada, ou o usuário selecionou e fez login em uma Conta do Google para estabelecer uma nova sessão.

• Antes de compartilhar as credenciais do token de ID com seu app, o usuário precisa

  • clicou no botão "Confirmar" para dar consentimento ao compartilhamento de credenciais, ou
  • já tinha concedido consentimento e usado "Selecionar uma conta" para escolher uma Conta do Google.

O valor desse campo é definido como um destes tipos:

estado

Esse parâmetro só é definido quando o usuário clica em um botão "Fazer login com o Google" para fazer login, e o atributo data-state do botão clicado é especificado. O valor desse campo é o mesmo que você especificou no atributo data-state do botão.

Como vários botões "Fazer login com o Google" podem ser renderizados na mesma página, você pode atribuir a cada botão uma string exclusiva. Portanto, você pode usar o parâmetro state para identificar em qual botão o usuário clicou para fazer login.

Endpoint do gerenciador de credenciais de senha

O endpoint do gerenciador de credenciais de senha processa as credenciais de senha que o gerenciador de credenciais integrado recupera.

A solicitação HTTP POST contém as seguintes informações: