Google Identity Services is migrating to FedCM APIs. Follow the migration guide to review potential changes and avoid negative impacts for user sign-in to your website.

Integration considerations

This step-by-step guide helps you to make decisions on all major integration issues.

Sign in with Google in the abstract

Below are the general steps for users to sign-in / sign-up on your website.

Users sign into a Google website.

For Sign in with Google to work, there should be an active Google session in the browser. One Tap and Automatic Sign-in are triggered only when users have signed in to Google before loading your web pages. This step is optional for the Sign in with Google button flow, since users are prompted to sign in to Google when the button is pressed.

Key Point: Due to security reasons, it's not allowed to add new Google sessions in an iframe.
Users browse your web pages where One Tap, Automatic Sign-in or Sign in with Google button are embedded.

Key Point: You can use the code generator to easily generate code to embed One Tap, Automatic Sign-in and Sign in with Google button into your web pages.
Users interact with One Tap, the Sign in with Google button and subsequent UX flows so as to:
- Select an active Google session to continue.
- Get consent from end users for sharing profile information with your website, if haven't consented yet.
Key Point: Automatic Sign-in happens when only one Google active session has previously granted the permission, and the feature is enabled by your website.
Note: Automatic Sign-in can only happen with One Tap UX, not with the Sign in with Google button UX.

When there is only one active Google session in the browser,
- One Tap selects the only session automatically, and thus skips the account chooser page.
- The Sign in with Google button stays on the account chooser page, which allows users to add new a Google session when needed.
If the selected Google account hasn't been used before with your website, or the permission has been revoked, a consent page will display.

Once approved, Google will record the decision, so as to skip the consent page for the next time.
A JSON Web Token (also referred to as ID token) credential containing the user's name, email and profile picture is shared using either a JavaScript callback handler or a post submission to your backend service.

The purpose of returning ID tokens to the JavaScript callback handler on the client side, is not for you to decode it in the JavaScript code, but for you to submit it to your server in your own way. One good example is to use an XmlHttpRequest to avoid the page reload caused by the post submission.

Key Point: To authenticate without reloading your web page, a common practice is to receive the JWT credential via a JavaScript callback handler, then to submit it to your server via an XmlHttpRequest.
On your server side, the Google-issued JWT credential is validated and consumed to create a new account or establish an authenticated session on your website.

You'll manage the user sign-in status on your own website.

The user's Google account sign-in status and your app are independent of each other, except during the sign-in moment itself when you know that the user has successfully authenticated and is signed into their Google account. Users may remain signed in, they may sign out, or switch to a different Google account while maintaining an active, signed-in session on your website.

In summary, like the password-based login, Sign in with Google provides another way to authenticate users on the web. Sign in with Google doesn't provide any features for the session management on your website after authentication.

Access Google APIs and services

While you have integrated the authentication API, as described above, you may also need to integrate the authorization API, if your site needs to access Google APIs and services on behalf of authenticated users. While authentication provides your site with ID tokens to authenticate users, authorization provides your site with (separate) access tokens and permissions to use Google APIs and services. See Authorizing for web for more information.

UX separation for authentication and authorization

If your website needs to call both authentication and authorization APIs, you must call them separately at different moments. See Separating the authentication and authorization moments.

If your website has requested authentication and authorization tokens together in the past, when using the Google Identity Services JavaScript library, you need to adjust your UX to separate the authentication moment from the authorization moment.

At the authentication moment, your website can integrate with One Tap, Automatic Sign-in, or Sign in with Google button to let users to sign in or sign up to your website.
At the authorization moment, your website can invoke the authorization API to obtain the permissions and tokens to access Google APIs or services.

For a smooth UX transition and complexity reduction, a common practice is to divide the process into two separated steps.

Refactor the UX to separate the authentication and authorization moments.
Migrate to the Google Identity Services JavaScript library.

Key Point: We'll focus on the authentication moment API and features hereinafter. Refer to the Authorization API doc for the authorization moment API and features.

HTML API versus JavaScript API

You can use either the HTML API or the JavaScript API to integrate One Tap, Automatic Sign-in, or Sign In With Google button into your web pages.

With the HTML API, you have more built-in features. For example,

Rendering One Tap or the Sign in With Google button on page load.
Submit the returned credential to your server side endpoint, which is specified by the data-login_uri attribute, after One Tap, Automatic Sign-in or button pop-up/redirect UX is done.
Prevent CSRF attacks by double-submit-cookie.
Use the code generator to generate the HTML code, then just copy it into your HTML pages.

With the HTML API, you can also write some JavaScript to customize the behavior.

You can write your own callback handler, then set the function name to the data-callback attribute. One good example is to use an XmlHttpRequest to submit the returned credential to your server, to avoid the page reload caused by the default post submission.

Key Point: To authenticate without reloading the web page, a common practice is receiving the JWT credential by a JavaScript callback handler, then submitting it to your server via an XmlHttpRequest.

With the JavaScript API, you have more flexibility on some scenarios as below.

Rendering One Tap and the Sign in with Google button at a later moment. For example, after users select Login from the menu.
Calling the API multiple times. For example, the Sign in with Google button needs to be rendered each time the login dialog is rendered.
Generating your HTML pages dynamically, making it hard to embed API-calling code within them.
You load the Google Identity Services JavaScript library at a much later time.

HTML API code can only be invoked once either on the page onload event or the Google Identity Services JavaScript library onload event, whichever comes later. You should use the JavaScript API if the HTML API behavior doesn't meet your expectation.

Don't use the HTML API with the JavaScript API in the same web page for initializing the page or for One Tap and button rendering. Check your code, both HTML and JavaScript, for places where they may overlap. Note the following:

You're using HTML API if one or more of the elements in <div id='g_id_onload' ... ><id> or <div class='g_id_signin' ...></div> exist in your HTML code.
You're using JavaScript API if one or more of the methods in initialize(), prompt(), or render() are invoked in your JavaScript code, no matter whether they are inlined or loaded from a separated JavaScript file.

The following JavaScript APIs may be used independently of initializing or One Tap and button rendering; these don't have corresponding HTML APIs:

Sign in with Google button considerations

Pop-up versus redirect

The OAuth 2.0 specification considers HTTP redirection, but lacks guidance on rendering pop-up dialogs. The pop-up UX, especially on desktop web, may provide a better UX for end users. This is because users are not redirected away from third-party pages, and a dialog-like pop-up window provides an in-context experience for permission granting.

With the pop-up UX, the identity provider needs to build on client-side cross-origin communication channels to pass OAuth responses from the pop-up window, where the identity provider's consent page is displaying, to the main window, where the third-party page is displaying. Normally JavaScript codes is required on both sides to send and receive the OAuth response across windows.

Both the pop-up and redirect UX are supported by the Sign in with Google button. By default, the pop-up UX is used. You can change the UX by setting the data-ux_mode attribute.

There are some differences between the Sign in with Google button redirect flow and the OAuth redirect flow.

The Sign in with Google button redirect flow always uses the POST method to submit the credential to your web server, whereas OAuth redirect normally uses the GET method.
The parameters submitted by the Sign in with Google button redirect flow are different from those of the OAuth redirect flow.

For developers using the HTML API, no matter which UX is used, the credentials are always submitted to the data-login_uri with the POST method and the same parameters. This lets you switch the UX mode without other code changes. For the redirect UX, the data-login_uri must be added to the Authorized redirect URIs for your client in the Google APIs console.

Button customization

Using your own button is not supported. There is no API to programmatically initiate a button flow.

To enable Sign in with Google button flow, all you need to do is to render one or more Sign in with Google buttons on your web pages. The button flow is initiated and handled transparently when users click these buttons.

The button rendering API lets you customize the look and feel of the Sign in with Google button. You're recommended to use the code generator to interactively design your buttons. Even if you use the JavaScript API, you can generate the HTML code first, then copy the code into corresponding fields in the JavaScript API.

There is no API to allow websites to control whether the personalized information should be used to render the buttons. The personalized buttons is displayed if all conditions are met. More details at Understand Personalized button.

You can put multiple buttons in the same web page. The code generator can only create one button each time. You can run it several times, and copy the generated <div class='g_id_signin' ...></div> code into the web page.

Button rendering best practices

Due to privacy reasons, the personalized button is shown in an iframe from the accounts.google.com domain. Loading an iframe may be time-consuming on a slow network. To mitigate this latency issue, the buttons are rendered in 2 steps, as follows:

An inline button version is rendered in your website's DOM tree. It's just a text button, no personalized info can be used. The purpose is to allow users to see the button as soon as possible.
An iframe request is sent to Google to load the button iframe, which may have personalized information. Once the button iframe is loaded, the inline version button is removed.

Some best practices to minimize the latency of displaying the Sign in with Google button flow button are listed below.

Load the Google Identity Services JavaScript library as early as possible. Consider loading the JavaScript library before some other big libraries, especially on mobile web.
If the Sign in with Google button is rendered only after the user selects Login from the menu. You can render the Sign in with Google button in a hidden element first, then make it visible after the user selects Login from the menu.

Key Point: Load the Google Identity Services JavaScript library as early as possible to minimize the latency of displaying the Sign in with Google button.

One Tap considerations

Automatic sign-in

Cancelable automatic sign-in provides the following benefits.

It may improve the sign-in rate by saving one user action.
Unlike the silent sign-in provided by earlier, deprecated Google Sign-In JavaScript library, users always see some UI when automatic sign-in happens, which gives them the context of why and how they are signed into your website. Users also have the ability to cancel if they want.
It automatically selects the account the user used before, which may prevent the user from creating duplicate accounts on your website.

Whether to enable automatic sign-in is a decision you need to make based on the UX and business requirements of your website. Especially if most logouts from your website are caused by session timeout instead of explicit user choices, automatic sign-in may be a good way for your users to recover the session status.

When to display the One Tap UI

With the HTML API, One Tap always displays on page load. With the JavaScript API, you have the ability to control when the One Tap UI displays. Note the One Tap UI may not always display after the API is invoked, due to some reasons as described below.

No active Google session in the browser.
All active Google session are opted out.
Cooldown is in progress.

Don't try to display only the One Tap UI on a button click event. The One Tap UI may not display due to above reasons, and users may have a broken UX, since nothing displays after the user action. On a button click event:

Recommended

Show your login dialog with password login and the Sign in with Google button and call One Tap API at the same time. This ensures that users are always offered some method of sign-in for your website.

Not Recommended

Offering only One Tap, users may experience a broken sign-in experience if One Tap is not displayed.
Using a UI status callback to show another UI if One Tap doesn't display. This is not recommended as the UI status callback may not work well with federated credential management in a future release.

One Tap on ITP browsers

Due to Intelligent Tracking Prevention (ITP), the normal One Tap UX doesn't work on ITP browsers, such as Chrome on iOS, Safari and Firefox. A different UX starting with a welcome page is provided on these browsers instead.

The One Tap UX on ITP browsers can be disabled if you want. Refer to One Tap support on ITP browsers for more details.

There is no way to enable this UX on non-ITP browsers, such as Chrome on Android/macOS/Linux and Edge.

Cancel the prompt if the user clicks away

By default, the One Tap prompt closes automatically if the user clicks outside of the prompt. This behavior can be changed if you want.

You are recommended to keep the One Tap prompt open on desktop web, since the screen size is big enough.

Change the position of the One Tap UX

On desktop web, you can change the position of the One Tap prompt. However, this feature is not recommended since this feature are not supported by federated credential management in a future release.

Change the sign-in context

One Tap should be part of a bigger UX flow on your website. By default, the One Tap UI is used within a sign-in context. The language in the UI contains particular wording, such as "sign in." You can change the context attribute to create a different set of wording. You can select one of the One Tap headers that best suits your UX flow.

Context
`signin`	"Sign in with Google"
`signup`	"Sign up with Google"
`use`	"Use with Google"

Listen on One Tap UI status

To seamlessly integrate into your bigger UX flow, One Tap can notify you when UI status changes. However, this feature is not supported in future federated credential management releases.

One Tap across subdomains

By default, One Tap cooldown and other statuses are tracked per-origin. If your website display One Tap across multiple subdomains, you need to indicate so in your API code.

One Tap in static HTML pages

By default, the GIS library assumes your web pages are dynamically generated. Your HTTP server checks for user login status when generating the HTML code.

If no user is logged in, One Tap HTML code should be included in the resulting page, so as to trigger One Tap to allow users to sign in to your website.
If users are already logged in, One Tap HTML code shouldn't be included in the resulting page.

In this case, it's your web server's responsibility to add or remove One Tap HTML API code.

One Tap HTML API code can work in another way, which is designed for websites that host a lot of static HTML content. You can always include the One Tap HTML API code in your static HTML pages, and specify the session cookie name used in your website.

If the session cookie doesn't exist, the One Tap flow is triggered.
If the session cookie exists, the One Tap flow is skipped.

In this case, whether to trigger the One Tap flow is controlled by your session cookie status, instead of the existence of the One Tap HTML API code in your web page.

Server side integration

After One Tap, automatic sign-in or the Sign in with Google button UX flow is done, an ID token is issued and shared with your website. To authenticate the user, some server side changes are required to receive and validate the ID token.

UX considerations

Normally you need to add an HTTP endpoint in your own origin to handle the responses on your server side. The following factors may have an impact on the resulting UX.

Whether One Tap or Sign in with Google is triggered.
Whether the HTML API or the JavaScript API is used.
Whether the login URI or the JavaScript callback function is used to handle the response.

The actual UX you get is described as below.

For the Sign in with Google button redirect UX mode:
- Whether the HTML API or the JavaScript API is used, you need to set the login URI. It's impossible to use a JavaScript callback function to handle the response, since users have already been redirected away from your web page.
- UX summary: after clicking the Sign in with Google button, users see a full-page redirect to a Google UI for session selection and approval. Once done, a full-page POST is submitted to the login URI you specified.
For One Tap or the Sign in with Google button pop-up UX mode, if the JavaScript API is used, or the HTML API is used and a JavaScript callback function is provided:
- The auth responses are passed back to the JavaScript callback function.
- UX summary: The One Tap prompt or a pop-up window is shown above your web page. After users finish the UX in the prompt or pop-up window for session selection and approval, the JavaScript callback function receives the responses. The subsequent UX is decided by how your callback function submits the responses to your server.
Key Point: To authenticate without reloading your web page, a common practice is to receive the auth response by the JavaScript callback function, then submit it to your server via an XmlHttpRequest.
Key Point: To enforce your own security measures, you can receive auth responses by the JavaScript callback function, then submit them with other parameters required by your website.
Otherwise (the HTML API with the login URI case):
- The auth responses are submitted to the login URI.
- UX summary: the One Tap prompt or a pop-up window is shown above your web page. After users finish the UX in the prompt or pop-up window for session selection and approval, the auth responses is submitted using a full-page POST submission to the login URL you specified.

You are recommended to use a consistent way to submit the One Tap responses and the Sign in with Google button responses.

Security considerations

To prevent Cross-Site Request Forgery attacks,

For post submission triggered by the Google Identity Service client JavaScript library, you can use the built-in double-submit-cookie pattern. Refer to Verify the Google ID token on your server side for more details.
For submission to your own origin using an XmlHttpRequest, you can use the custom HTTP header, or other security measures approved by your security team.

To verify the ID tokens in the auth responses, you are strongly recommended to use a Google API client library for your platform, or a general-purpose JWT library.

Frequently asked questions (FAQ)

Is One Tap and Sign in with Google button available in webviews?

No. Due to security concerns, users should not add Google sessions into webviews. Thus, GIS are disabled in webviews, since no Google sessions are supposed to be there.
Can I use my own Sign in with Google button? No. With OAuth server side flow or the earlier version Google Sign In JavaScript library, relying parties were able to use the Sign-In Branding Guidelines to build their own versions of Google Sign In buttons.

However, Sign in with Google has removed this feature. All Sign in with Google buttons must be generated by the Google Identity Services JavaScript library. There are two reasons for this change.
- Some relying parties failed to follow the guidelines, which leads to inconsistent Sign in with Google buttons across websites.
- By generating by the library, you don't need to make any changes when the Sign-In Branding Guidelines itself change.
To enforce this rule, the JavaScript library only exposes an API to render a button, but not the API to start the sign in flow.
What if my website only enables One Tap but not Sign in with Google button?

You are recommended to use both One Tap and the Sign in with Google button on your website. Due to exponential cool-down, One Tap may not be displayed every time. When users really want to sign in to your website with their Google accounts, they can go to your main login dialog and sign in with the Sign in with Google button there. A successful sign in using the Sign In with Google button will clear the One Tap cool-down status so that One Tap can display for the next login. Other button flows from Google cannot clear the One Tap cool-down statuses, since they are in different JavaScript binaries.

If your website only enables One Tap but not the Sign in with Google button, you may see performance drop for your One Tap flow, since the exponential cool-down statuses is not cleared in time.
When my HTML API code are parsed? Can I change my HTML API code later?

The Google Identity Services JavaScript library parses and executes your HTML API code either on the JavaScript library load event or the DomContentLoaded event, whichever is later.
- If the DomContentLoaded event is triggered when the JavaScript library is loaded, your HTML API code is parsed and executed immediately.
- Otherwise, the JavaScript library adds a listener for the DomContentLoaded event. When triggered, the listener parses and executes your HTML API code.
Also note that the parsing and execution of your HTML API code is one off.
- After the parsing and execution, any subsequent changes to your HTML API code are ignored.
- There is no API for developers to trigger the parsing or execution process.
Tip: Use the JavaScript API if the above-mentioned behaviors don't meet your requirements.