Migrate from Google Sign-In (original) (raw)

This guide helps you to understand the necessary changes and steps to successfully migrate JavaScript libraries from the earlier Google Sign-In platform library to the newer Google Identity Services library for_authentication_.

If your client is using the Google API Client Library for JavaScript or other earlier libraries for authorization, see Migrate to Google Identity Services for more information.

Authentication establishes who someone is, and is commonly referred to as user sign-up or sign-in. Authorization is the process of granting or rejecting access to data or resources. For example, your app requests your user's consent to access the user's Google Drive.

Like the earlier Google Sign-In platform library, the new Google Identity Services library is built to support both authentication and authorization processes.

However, the newer library separates the two processes to reduce the complexity for developers to integrate Google Accounts with your app.

If your use case only concerns authentication, continue reading this page.

If your use case includes authorization, read How user authorization worksand Migrate to Google Identity Services to make sure your application is using the new and improved APIs.

What's changed

For users, the new Google Identity Services library offers numerous usability improvements. Highlights include:

For developers, our focus has been to reduce complexity, improve security, and make your integration as quick as possible. Some of these improvements include:

A sign-in migration example

If you are migrating from the existing Google Sign-In button and are only interested in signing users into your site, the most straightforward change is to update to the new personalized button. This can be accomplished by swapping JavaScript libraries and updating your codebase to use a new sign-in object.

Libraries and configuration

The earlier Google Sign-In platform library: apis.google.com/js/platform.js, and Google APIs client library for JavaScript: gapi.client, are no longer required for user authentication and authorization. They have been replaced by a single new Google Identity Services JavaScript library:accounts.google.com/gsi/client.

The earlier three JavaScript modules: api, client, and platform used for sign-in are all loaded from apis.google.com. To help you identify locations where the earlier library might be included in your site, typically:

In most cases you can continue to use your existing web application Client ID credentials. As part of your migration we recommend that you review ourOAuth 2.0 Policies and use the Google API Consoleto confirm, and if necessary, update the following client settings:

Identify affected code and test

A debug cookie can help to locate affected code and to test post-deprecation behavior.

In large or complex apps, it may be difficult to find all code affected by the deprecation of the gapi.auth2 module. To log existing use of soon to be deprecated capabilities to the console, set the value of the G_AUTH2_MIGRATIONcookie to informational. Optionally, add a colon followed by a key value to also log to session storage. After sign-in and receipt of credentials review or send collected logs to a backend for later analysis. For example, informational:showauth2use saves origin and URL to a session storage key named showauth2use.

To verify app behavior when the gapi.auth2 module is no longer loaded, set the value of the G_AUTH2_MIGRATION cookie to enforced. This enables testing of post-deprecation behavior in advance of the enforcement date.

Possible G_AUTH2_MIGRATION cookie values:

To minimize user impact it is recommended that you first set this cookie locally during development and test, before using it in production environments.

HTML and JavaScript

In this authentication-only sign-in scenario, example code and renderings of the existing Google Sign-In button are shown. Select from either popup or redirect mode to see differences in how the authentication response is handled either by a JavaScript callback or by secure redirect to your backend server login endpoint.

The earlier way

Render the Google Sign-In button and use a callback to handle sign-in directly from the user's browser.

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

Redirect mode

Render the Google Sign-In button, ending with an AJAX call from the user's browser to your backend servers login endpoint.

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Rendered

New visual-attributes simplify the earlier method of creating a customized button, eliminates calls to gapi.signin2.render(), and the need for you to host and maintain images and visual assets on your site.

Google Sign-In

Google Signed-In

User sign-in status updates button text.

The new way

To use the new library in an authentication-only sign-in scenario select from either the popup or redirect mode and use the code sample to replace your existing implementation on your login page.

Use a callback to handle sign-in directly from the user's browser.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

Redirect mode

Google invokes your login endpoint as specified by the data-login_urlattribute. Previously, you were responsible for the POST operation and parameter name. The new library posts the ID token to your endpoint in thecredential parameter. Lastly, verify the ID token on your backend server.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

Rendered

Use visual-attributes to customize the Sign In With Google button size, shape, color. Display the One Tap popup along with the personalized button to improve sign-in rate.

Sign In With Google
button One Tap
popup

User sign-in state does not update the button text from "Sign in" to "Signed in". After providing consent, or on return visits, the personalized button includes the user's name, email, and profile picture.

In this authentication-only example, the new accounts.google.com/gsi/clientlibrary, g_id_signin class, and g_id_onload object replace the earlierapis.google.com/js/platform.js library and g-signin2 object.

In addition to rendering the new personalized button the example code also displays the new One Tap popup. Wherever you display the personalized button we highly recommend that you also display the One Tap popup to minimize user friction during sign-up and sign-in.

Although it is not recommended due to increased sign-in friction, the new personalized button can be shown alone, without simultaneously displaying the One Tap dialog. To do this, set the data-auto_prompt attribute to false.

HTML and JavaScript APIs

The previous example shows how to use the new HTML API to add sign-in to your website. Alternatively, you can use the functionally equivalentJavaScript API, or mix and match HTML and JavaScript APIs across your site.

To interactively view button customization options such as, callback type and attributes such as: color, size, shape, text and theme, checkout our Code generator. It can be used to quickly compare different options and generate HTML snippets for use on your site.

Sign-in from any page with One Tap

One Tap is a new low-friction way for users to sign-up or sign-in to your site. It lets you enable user sign-in directly from any page on your site and eliminates the need for users to visit a dedicated login page. Put another way, this reduces sign-up and sign-in friction by giving users the flexibility to sign-up and sign-in from pages other than your login page.

To enable sign-in from any page we recommended that you include g_id_onload in a shared header, footer or other object included across your entire site.

We also recommend adding g_id_signin, which displays the personalized sign-in button, only on your login or user account management pages. Give users choices for sign-up or sign-in by displaying the button alongside other federated identity provider buttons and username and password entry fields.

Token response

User sign-in no longer requires you to understand or work with OAuth 2.0 authorization codes, access tokens, or refresh tokens. Instead a JSON Web Token (JWT) ID Token is used to share sign-in status and the user profile. As a further simplification, you are no longer required to use "getter" style accessor methods to work with user profile data.

A secure Google-signed JWT ID token credential is returned either:

In both cases, update your existing callback handlers by removing:

Instead, use direct references to credential sub-fields in the new JWTCredentialResponse object to work with user profile data.

Additionally, and for Redirect mode only, be sure to prevent Cross-Site Request Forgery (CSRF) and Verify the Google ID token on your backend server.

To better understand how users are interacting with your site theselect_by field in the CredentialResponse can be used to determine user consent outcome and the specific sign-in flow used.

When a user first signs-in to your website, Google prompts the user for consent to share their account profile with your app. Only after providing consent is the user's profile shared to your app in an ID token credential payload. Revoking access to this profile is equivalent to revoking an access token in the earlier sign-in library.

Users may revoke permissions and disconnect your app from their Google Account by visiting https://myaccount.google.com/permissions. Alternatively, they may disconnect directly from your app by triggering an API call which you implement; the earlier disconnect method has been replaced by the newer revoke method.

When a user deletes their account on your platform it is best practice to userevoke to disconnect your app from their Google Account.

Previously, auth2.signOut() could be used to help manage user sign-outfrom your app. Any usage of auth2.signOut() should be removed, and your app should directly manage per user session state and sign-in status.

Session state and Listeners

The new library does not maintain signed-in status or session state for your web app.

The signed-in status of a Google Account, and your app's session state and signed-in status are distinct, separate concepts.

User sign-in status to their Google Account 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.

When Sign In With Google, One Tap, or Automatic sign-in are included on your site users must first sign-in to their Google Account to:

Users may remain signed-in, sign-out, or switch to a different Google Account while maintaining an active, signed-in session on your website.

You are now responsible for directly managing the signed-in status for users of your web app. Previously, Google Sign-In helped with Monitoring the user's session state.

Remove any references to auth2.attachClickHandler() and its registered callback handlers.

Previously, Listeners were used to share changes in signed-in status for a user's Google Account. Listeners are no longer supported.

Remove any references to listen(), auth2.currentUser, andauth2.isSignedIn.

Cookies

Sign In With Google makes limited use of cookies, a description of these cookies follows. See How Google uses cookiesfor more information on the other types of cookies used by Google.

The G_ENABLED_IDPS cookie set by the earlier Google Sign-in Platform Library is no longer used.

The new Google Identity Services library may optionally set these cross-domain cookies based upon your configuration options:

If you have a service which manages cookies, be sure to add the two new cookies and remove the earlier cookie when migration is complete.

If you manage multiple domains or subdomains, see Display One Tap across Subdomains for further instructions on working with the g_state cookie.

Object migration reference for user sign-in

Old New Notes
JavaScript libraries
apis.google.com/js/platform.js accounts.google.com/gsi/client Replace old with new.
apis.google.com/js/api.js accounts.google.com/gsi/client Replace old with new.
GoogleAuth object and associated methods:
GoogleAuth.attachClickHandler() IdConfiguration.callback for JS and HTML data-callback Replace old with new.
GoogleAuth.currentUser.get() CredentialResponse Use CredentialResponse instead, no longer necessary.
GoogleAuth.currentUser.listen() Remove. A user's current sign-in status on Google is unavailable. Users must be signed-in to Google for consent and sign-in moments. Theselect_by field in CredentialResponse can be used to determine the outcome of user consent along with the sign-in method used.
GoogleAuth.disconnect() google.accounts.id.revoke Replace old with new. Revocation may also occur from https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
GoogleAuth.isSignedIn.get() Remove. A user's current sign-in status on Google is unavailable. Users must be signed-in to Google for consent and sign-in moments.
GoogleAuth.isSignedIn.listen() Remove. A user's current sign-in status on Google is unavailable. Users must be signed-in to Google for consent and sign-in moments.
GoogleAuth.signIn() Remove. HTML DOM loading of theg_id_signin element or JS call togoogle.accounts.id.renderButton triggers user sign-in to a Google Account.
GoogleAuth.signOut() Remove. User sign-in status for your app and a Google Account are independent. Google does not manage session state for your app.
GoogleAuth.then() Remove. GoogleAuth is deprecated.
GoogleUser object and associated methods:
GoogleUser.disconnect() google.accounts.id.revoke Replace old with new. Revocation may also occur from https://myaccount.google.com/permissions
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() CredentialResponse Directly use credential and sub-fields instead of BasicProfile methods.
GoogleUser.getGrantedScopes() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
GoogleUser.getHostedDomain() CredentialResponse Instead, directly use credential.hd.
GoogleUser.getId() CredentialResponse Instead, directly use credential.sub.
GoogleUser.grantOfflineAccess() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
GoogleUser.grant() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
GoogleUser.hasGrantedScopes() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
GoogleUser.isSignedIn() Remove. A user's current sign-in status on Google is unavailable. Users must be signed-in to Google for consent and sign-in moments.
GoogleUser.reloadAuthResponse() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2 object and associated methods:
gapi.auth2.AuthorizeConfig object Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.AuthorizeResponse object Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.AuthResponse object Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.authorize() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.ClientConfig() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.getAuthInstance() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.init() Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.OfflineAccessOptions object Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.auth2.SignInOptions object Remove. An ID token has replaced OAuth 2.0 access tokens and scopes.
gapi.signin2 object and associated methods:
gapi.signin2.render() Remove. HTML DOM loading of theg_id_signin element or JS call togoogle.accounts.id.renderButton triggers user sign-in to a Google Account.