Sign In With Google HTML API reference

This reference page describes the Sign In With Google HTML data attributes API. You can use the API to display the One Tap prompt or Sign In With Google button on your web pages.

Element with ID "g_id_onload"

You can put Sign In With Google data attributes in any visible or invisible elements, such as <div> and <span> . The only requirement is that the element ID is set to g_id_onload . Don't put this ID on multiple elements.

Data attributes

The following table lists the data attributes with their descriptions:

Attribute types

The following sections contain details about each attribute's type and an example.

data-client_id

This attribute is your app's client ID, which is found and created in the Google Cloud console. See the following table for further information:

data-auto_prompt

This attribute determines whether to display One tap or not. The default value is true . Google One tap is not displayed when this value is false . See the following table for further information:

data-auto_select

This attribute determines whether or not to return an ID token automatically, without any user interaction, if only one Google session has approved your app. The default value is false . See the following table for further information:

data-login_uri

This attribute is the URI of your login endpoint.

The value must exactly match one of the authorized redirect URIs for the OAuth 2.0 client, which you configured in the API Console and must conform to our Redirect URI validation rules .

This attribute may be omitted if the current page is your login page, in which case the credential is posted to this page by default.

The ID token credential response is posted to your login endpoint when no callback function is defined and a user clicks on the Sign In With Google or One Tap buttons, or automatic sign takes place.

See the following table for further information:

Your login endpoint must handle POST requests containing a credential key with an ID token value in the body.

The following is an example request to your login endpoint:

 POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN 

data-callback

This attribute is the name of the JavaScript function that handles the returned ID token. See the following table for further information:

One of the data-login_uri and data-callback attributes might be used. It depends on the following component and UX mode configurations:

• The data-login_uri attribute is required for the Sign In With Google button redirect UX mode, which ignores the data-callback attribute.

• One of these two attributes must be set for Google One Tap and the Google Sign-In button popup UX mode. If both are set, the data-callback attribute has a higher precedence.

JavaScript functions within a namespace are not supported by the HTML API. Instead, use a global JavaScript function without a namespace. For example, use mylibCallback instead of mylib.callback .

data-native_login_uri

This attribute is the URL of your password credential handler endpoint. If you set either the data-native_login_uri attribute or the data-native_callback attribute, the JavaScript library falls back to the native credential manager when there isn't a Google session. You're not allowed to set both the data-native_callback and data-native_login_uri attributes. See the following table for further information:

data-native_callback

This attribute is the name of the JavaScript function that handles the password credential returned from the browser's native credential manager. If you set either the data-native_login_uri attribute or the data-native_callback attribute, the JavaScript library falls back to the native credential manager when there isn't a Google session. You're not allowed to set both data-native_callback and data-native_login_uri . See the following table for further information:

JavaScript functions within a namespace are not supported by the HTML API. Instead, use a global JavaScript function without a namespace. For example, use mylibCallback instead of mylib.callback .

data-native_id_param

When you submit the password credential to the password credential handler endpoint, you can specify the parameter name for the credential.id field. The default name is email . See the following table for further information:

data-native_password_param

When you submit the password credential to the password credential handler endpoint, you can specify the parameter name for the credential.password value. The default name is password . See the following table for further information:

data-cancel_on_tap_outside

This attribute sets whether or not to cancel the One Tap request if the user clicks outside of the prompt. The default value is true . To disable it, set the value to false . See the following table for further information:

data-prompt_parent_id

This attribute sets the DOM ID of the container element. If it's not set, the One Tap prompt is displayed at the top-right corner of the window. See the following table for further information:

data-skip_prompt_cookie

This attribute skips One Tap if the specified cookie has a non-empty value. See the following table for further information:

data-nonce

This attribute is a random string used by the ID token to prevent replay attacks. See the following table for further information:

Nonce length is limited to the maximum JWT size supported by your environment, and individual browser and server HTTP size constraints.

data-context

This attribute changes the text of the title and messages shown in the One Tap prompt. See the following table for further information:

The following table lists allthe available contexts and their descriptions:

data-moment_callback

This attribute is the function name of the prompt UI status notification listener. For more information, refer to the data type PromptMomentNotification .

See the following table for further information:

JavaScript functions within a namespace are not supported by the HTML API. Instead, use a global JavaScript function without a namespace. For example, use mylibCallback instead of mylib.callback .

data-state_cookie_domain

If you need to display One Tap in a parent domain and its subdomains, pass the parent domain to this attribute so that a single shared-state cookie is used. See the following table for further information:

data-ux_mode

This attribute sets the UX flow used by the Sign In With Google button. The default value is popup . This attribute has no impact on the One Tap UX. See the following table for further information:

The following table lists the available UX modes and their descriptions.

data-allowed_parent_origin

The origins that are allowed to embed the intermediate iframe. One Tap runs in the intermediate iframe mode if this attribute presents. See the following table for further information:

The following table lists the supported value types and their descriptions.

If the value of data-allowed_parent_origin attribute is invalid, the One Tap initialization of the intermediate iframe mode would fail and stop.

Wildcard prefixes are also supported. For example, "https://*.example.com" matches example.com and its subdomains at all levels (e.g news.example.com , login.news.example.com ). Things to keep in mind when using wildcards:

• Pattern strings cannot be composed of only a wildcard and a top level domain. For example https://*.com and https://*.co.uk are invalid; As noted above, "https://*.example.com" matches example.com and its subdomains. You can also use a comma separated list to represent 2 different domains. For example, "https://example1.com,https://*.example2.com" matches the domains example1.com , example2.com and subdomains of example2.com
• Wildcard domains must begin with a secure https:// scheme, so "*.example.com" is considered invalid.

data-intermediate_iframe_close_callback

Overrides the default intermediate iframe behavior when users manually close One Tap by tapping on the 'X' button in the One Tap UI. The default behavior is to remove the intermediate iframe from the DOM immediately.

The data-intermediate_iframe_close_callback field takes effect only in intermediate iframe mode. And it has impact only to the intermediate iframe, instead of the One Tap iframe. The One Tap UI is removed before the callback is invoked.

JavaScript functions within a namespace are not supported by the HTML API. Instead, use a global JavaScript function without a namespace. For example, use mylibCallback instead of mylib.callback .

data-itp_support

This field determines if the upgraded One Tap UX should be enabled on browsers that support Intelligent Tracking Prevention (ITP). The default value is false . See the following table for further information:

data-login_hint

If your application knows in advance which user should be signed-in, it can provide a login hint to Google. When successful, account selection is skipped. Accepted values are: an email address or an ID token sub field.

For more information, see the OpenID Connect documentation for login_hint .

data-hd

When a user has multiple accounts and should only sign-in with their Workspace account use this to provide a domain name hint to Google. When successful, user accounts displayed during account selection are limited to the provided domain. A wildcard value: * offers only Workspace accounts to the user and excludes consumer accounts (user@gmail.com) during account selection.

For more information, see the OpenID Connect documentation for hd .

data-use_fedcm_for_prompt

Allow the browser to control user sign-in prompts and mediate the sign-in flow between your website and Google. Defaults to false. See Migrate to FedCM page for more information.

data-enable_redirect_uri_validation

Enable button redirect flow that complies with Redirect URI validation rules .

Element with class "g_id_signin"

If you add g_id_signin to an element's class attribute, the element renders as a Sign In With Google button.

You can render multiple Sign In With Google buttons on the same page. Each button can have its own visual settings. The settings are defined by the following data attributes.

Visual Data attributes

The following table lists visual data attributes and their descriptions:

Attribute types

The following sections contain details about each attribute's type and an example.

data-type

The button type. The default value is standard . See the following table for further information:

The following table lists allthe available button types and their descriptions:

Type
standard
icon

data-theme

The button theme. The default value is outline . See the following table for further information:

The following table lists the available themes and their descriptions:

Theme
outline
filled_blue
filled_black

data-size

The button size. The default value is large . See the following table for further information:

The following table lists the available button sizes and their descriptions.

Size
large
medium
small

data-text

The button text. The default value is signin_with . There are no visual differences for the text of icon buttons that have different data-text attributes. The only exception is when the text is read for screen accessibility.

See the following table for further information:

The following table lists the available button texts and their descriptions:

Text
signin_with
signup_with
continue_with
signin

data-shape

The button shape. The default value is rectangular . See the following table for further information:

The following table lists the available button shapes and their descriptions:

Shape
rectangular
pill
circle
square

data-logo_alignment

The alignment of the Google logo. The default value is left . This attribute only applies to the standard button type. See the following table for further information:

The following table lists the available alignments and their descriptions:

logo_alignment
left
center

data-width

The minimum button width, in pixels. The maximum width available is 400 pixels.

See the following table for further information:

data-locale

Optional. Display button text using the specified locale, otherwise default to the users Google Account or browser settings. Add the hl parameter and language code to the src directive when loading the library, for example: gsi/client?hl=<iso-639-code> .

If it's not set, the browser's default locale or the Google session user's preference is used. Therefore, different users might see different versions of localized buttons, and possibly with different sizes.

See the following table for further information:

data-click_listener

You can define a JavaScript function to be called when the Sign in with Google button is clicked using the data-click_listener attribute.

<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>

In this example, the message Sign in with Google button clicked... is logged to the console when the Sign in with Google button is clicked.

data-state

Optional, as multiple Sign in with Google buttons can be rendered on the same page, you can assign each button with a unique string. The same string would return along with the ID token, so you can identify which button user clicked to sign in.

See the following table for further information:

Server-side integration

Your server-side endpoints must handle the following HTTP POST requests.

The ID token handler endpoint

The ID token handler endpoint processes the ID token. Based on the status of the corresponding account, you can sign the user in and either direct them to a sign-up page or direct them to an account-linking page for additional information.

The HTTP POST request contains the following information:

credential

When decoded , the ID token looks like the following example:

 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" 
 : 
  
 "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 
 's creation time 
  
 "exp" 
 : 
  
 1596477600 
 , 
  
 // 
  
 Unix 
  
 timestamp 
  
 of 
  
 the 
  
 assertion 
 's expiration time 
  
 "jti" 
 : 
  
 "abc161803398874def" 
 } 

The sub field is a globally unique identifier for the Google Account. Onlyuse sub field as identifier for the user as it is unique among all Google Accounts and never reused. Don'tuse email address as an identifier because a Google Account can have multiple email addresses at different points in time.

Using the email , email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is confirmed to be the legitimate account owner.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a Google Workspace account.

Users may register for Google Accounts without using Gmail or Google Workspace. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google Account was created, however ownership of the third party email account may have since changed.

The exp field shows the expiration time for you to verify the token on your server side . It is one hour for the ID token obtained from Sign In With Google. You need to verify the token before the expiration time. Don't use exp for session management.An expired ID token does notmean the user is signed out. Your app is responsible for session management of your users.

select_by

The following table lists the possible values for the select_by field. The type of button used along with the session and consent state are used to set the value,

• The user pressed either the One Tap or Sign In With Google button or used the touchless Automatic sign-in process.

• An existing session was found, or the user selected and signed-in to a Google Account to establish a new session.

• Prior to sharing ID token credentials with your app the user either

  • pressed the Confirm button to grant their consent to share credentials, or
  • had previously granted consent and used Select an Account to choose a Google Account.

The value of this field is set to one of these types,

state

This parameter is only defined when user clicks a Sign in with Google button to sign in, and the clicked button's data-state attribute is specified. The value of this field is the same value you specified in the button's data-state attribute.

As multiple Sign in with Google buttons can be rendered on the same page, you can assign each button with a unique string. Hence, you can this state parameter to identify which button user clicked to sign in.

Password credential handler endpoint

The password credential handler endpoint processes password credentials that the native credential manager retrieves.

The HTTP POST request contains the following information: