Referência da API HTML do Sign-in com o Google

Esta página de referência descreve a API de atributos de dados HTML do recurso Fazer Login com o Google, usada para mostrar o botão "Fazer login com o Google" ou o prompt do One Tap em páginas da Web.

Elemento com o ID "g_id_onload"

É possível colocar atributos de dados do recurso 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 descrições:

Tipos de atributo

As seções a seguir contêm detalhes sobre cada tipo de 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 abaixo para mais informações:

data-color_scheme

Este campo é o esquema de cores aplicado à solicitação do One Tap. Consulte a tabela a seguir para mais informações:

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

data-auto_prompt

Esse atributo determina se o recurso Um Toque será exibido ou não. O valor padrão é true. O Google One Tap não é exibido 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 qualquer interação do usuário, se apenas uma sessão do Google tiver aprovado seu app. O valor padrão é false. Consulte a tabela abaixo para mais informações:

data-login_uri

Esse atributo é o URI do 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 em conformidade com nossas regras de validação de URI de redirecionamento.

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

A resposta da 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 abaixo para mais informações:

data-callback

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

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

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

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

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

A função de callback recebe um objeto CredentialResponse como parâmetro. Consulte CredentialResponse para detalhes sobre os possíveis valores de resposta.

data-native_login_uri

Esse atributo é o URL do endpoint do gerenciador de credenciais de senha. 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 é 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 é permitido 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 JavaScript global 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 abaixo 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 desativá-lo, defina o valor como false. Consulte a tabela abaixo para mais informações:

data-prompt_parent_id

Esse atributo define o ID do DOM do elemento de contêiner. Se não estiver definido, o prompt do One Tap será exibido 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 da solicitação de Um Toque. Se o cookie especificado por esse atributo tiver um valor não vazio, a solicitação não será exibida. Consulte a tabela abaixo 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 abaixo para mais informações:

O tamanho do valor de uso único é limitado ao tamanho máximo de JWT aceito pelo ambiente e às restrições de tamanho HTTP do navegador e do servidor.

data-essential_claims

Esse atributo é uma string usada para solicitar que outras declarações sejam incluídas no token de ID retornado pelo Google. Para uma lista completa de declarações aceitas pelo Google, consulte declarações compatíveis.

Consulte a tabela abaixo para mais informações:

data-context

Esse campo muda o texto do título e das mensagens mostradas na solicitação do One Tap, sem efeito para navegadores com ITP. O valor padrão é signin.

Consulte a tabela abaixo 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 prompt. Para mais informações, consulte o tipo de dados PromptMomentNotification.

Consulte a tabela abaixo 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 JavaScript global sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-state_cookie_domain

Se você precisar exibir o recurso Um Toque em um domínio pai e nos subdomínios dele, transmita o domínio pai para esse atributo para que um único cookie de estado compartilhado seja usado. Consulte a tabela abaixo 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 afeta a UX do One Tap. 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 One Tap é 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 valor 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 dele em todos os níveis (por exemplo, news.example.com, login.news.example.com). O que você precisa saber ao usar caracteres curinga:

• 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, já que "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.
• Os domínios 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 isso afeta apenas o iframe intermediário, em vez do iframe do One Tap. A interface do One Tap é removida antes que o callback seja invocado.

As funções JavaScript em um namespace não são compatíveis com a API HTML. Em vez disso, use uma função JavaScript global 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 atualizada do One Tap precisa ser ativada em navegadores compatíveis com a Prevenção Inteligente contra 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 isso acontece, a seleção de conta é ignorada. Os valores aceitos são: um endereço de e-mail ou um campo sub de um 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 essa opção para fornecer uma dica de nome de domínio ao Google. Quando bem-sucedidas, as contas de usuário exibidas durante a seleção de conta são limitadas ao domínio fornecido. Um valor de caractere curinga: * oferece apenas contas do Workspace ao usuário e exclui contas pessoais (user@gmail.com) durante a seleção de contas.

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

data-use_fedcm_for_prompt

Permita que o navegador controle as solicitações de login do usuário e faça a mediação do fluxo de login entre seu site e o Google. O padrão é "falso". 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 do 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 de seleção automática será ativada para o fluxo de botão da FedCM. Se ativado, os usuários recorrentes com uma sessão ativa do Google serão conectados automaticamente, ignorando a solicitação do seletor de contas. O padrão é false. É necessário ativar explicitamente o login automático com um 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 as próprias configurações visuais. As configurações são definidas pelos atributos de dados a seguir.

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 descrições deles:

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	Amostras	Especificações
outline		Preenchimento: #FFFFFF Traço: #747775 | 1px | interno Fonte: #1F1F1F | Roboto Medium | 14/20 Personalizado: #1F1F1F | Roboto | Medium 12/14 | Regular 11/13
filled_blue		Preenchimento: #0B57D0 Traço: #OB57D0 | 1px | interno Fonte: #FFFFFF | Google Sans Medium | 14/20 Personalizado: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
filled_black		Preenchimento: #202124 Traço: #OB57D0 | 1 px | interno Fonte: #FFFFFF | Google Sans Medium | 14/20 Personalizado: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13
outline_dark		Preenchimento: #131314 Traço: #8E918F | 1px | interno Fonte: #FFFFFF | Google Sans Medium | 14/20 Personalizado: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13

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 de botões de ícone que têm atributos data-text diferentes. A única exceção é quando o texto é lido para acessibilidade de tela.

Consulte a tabela abaixo 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 abaixo para mais informações:

data-locale

Opcional. Mostra o texto do botão usando a localidade especificada. Caso contrário, o padrão será a Conta do Google ou as configurações do navegador do usuário. Adicione o parâmetro hl e o código de 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 e, possivelmente, com tamanhos diferentes.

Consulte a tabela abaixo para mais informações:

data-click_listener

É possível definir uma função JavaScript a 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, já que vários botões "Fazer login com o Google" podem ser renderizados na mesma página, é possível atribuir uma string exclusiva a cada botão. A mesma string seria retornada com o token de ID, para que você possa identificar em qual botão o usuário clicou para fazer login.

Consulte a tabela abaixo para mais informações:

Integração no servidor

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

O endpoint do gerenciador de tokens de ID

O endpoint do gerenciador de tokens de ID processa o token de ID. Com base no status da conta correspondente, você pode conectar o usuário e direcioná-lo para uma página de inscrição ou de vinculação de conta para mais informações. Os clientes PRECISAM ignorar parâmetros de resposta não reconhecidos.

Exemplo de solicitação para o 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 é semelhante ao exemplo a seguir:

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 Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "email": "elisa.g.beckett@gmail.com", // 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 creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

Os clientes PRECISAM ignorar declarações JWT não reconhecidas.

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

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

Casos em que o Google é autoritativo:

• email tem o sufixo @gmail.com, que é uma conta do Gmail.
• email_verified for verdadeiro e hd estiver definido, essa será uma conta do Google Workspace.

Os usuários podem se registrar em 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 é autoritativo, e métodos de senha ou outros métodos de desafio são recomendados para verificar o usuário. email_verified também pode ser verdadeiro, já que o Google verificou inicialmente 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 de validade para você verificar o token no servidor. É de uma hora para o token de ID recebido do recurso Fazer Login com o Google. É necessário verificar o token antes do prazo de validade. Não use exp para o gerenciamento de sessões. Um token de ID expirado não significa que o usuário saiu da conta. 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, na sigla em inglês) 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 servidor, ela será considerada inválida.

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, é possível atribuir uma string exclusiva a cada um deles. Portanto, é possível usar esse 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: