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.
Users browse your web pages where One Tap, Automatic Sign-in or Sign in with Google button are embedded.
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.
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.
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.
- 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.
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_uriattribute, 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.
You can write your own callback handler, then set the function name to the
data-callbackattribute. 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.
- 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'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.
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.
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
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
POSTmethod to submit the credential to your web server, whereas OAuth redirect normally uses the
- 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.
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.
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
<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.
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.
One Tap considerations
Cancelable automatic sign-in provides the following benefits.
- It may improve the sign-in rate by saving one user action.
- 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
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:
- 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.
- 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.
|"Sign in with Google"
|"Sign up with Google"
|"Use with Google"
Listen on One Tap UI status
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.
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.
The actual UX you get is described as below.
For the Sign in with Google button redirect UX mode:
- 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
POSTis submitted to the login URI you specified.
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
POSTsubmission 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.
To prevent Cross-Site Request Forgery attacks,
- 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.
- 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.
What if my website only enables One Tap but not Sign in with Google button?
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?
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.