The newest version of Google Identity Toolkit has been released as Firebase Authentication. It includes upgraded client SDKs, open source UI libraries, session management and integrated email sending service for forgotten password flows.

New projects should use Firebase Authentication. To migrate an existing project from Identity Toolkit to Firebase Authentication, see the migration guide.

Set up UI widgets

Overview

There are two main widgets provided by Identity Toolkit. The first is a "Sign In" button to begin the authentication flow, and the second is a widget for actually performing the sign in operation

Page with sign in button

On whichever page you wish to show the "Sign In" button or immediately begin the authentication flow, you will need to include a bit of html in the <head>. The only HTML element is a <div id=”navbar”></div> which becomes a “Sign In” button that you can customize with CSS.

If you choose to show this <div id=”navbar”></div> after the user has signed in, it will become a user info box.

The code to put in the <head> can be downloaded from Developer Console as gitkit-signin-button.html. Then you can copy and paste this into your page and end up with something like this:

<html>
  <head>
    <!-- Begin custom code copied from Developer Console -->
    <!-- Note: this is just an example. The html you download from Developer Console will be tailored for your site -->
    <script type="text/javascript" src="//www.gstatic.com/authtoolkit/js/gitkit.js"></script>
    <link type=text/css rel=stylesheet href="//www.gstatic.com/authtoolkit/css/gitkit.css" />
    <script type=text/javascript>
      window.google.identitytoolkit.signInButton(
        '#navbar', // accepts any CSS selector
        {
          widgetUrl: "https://localhost:8000/callback",
          signOutUrl: "/",
          // Optional - Begin the sign-in flow in a popup window
          //popupMode: true,

          // Optional - Cookie name (default: gtoken)
          //            NOTE: Also needs to be added to config of ‘widget
          //                  page’. See below
          //cookieName: ‘example_cookie’,
        }
      );
    </script>
    <!-- End custom code copied from Developer Console -->
  </head>
  <body>
    <!-- Begin sign in button widget -->
    <div id="navbar"></div>
    <!-- End sign in button widget -->
  </body>
</html>

Page with sign in widget

The sign in widget is the core of the Identity Toolkit implementation. The page handles the multiple functions of displaying your sign in page, invisibly handling responses from identity providers, as well as displaying drop-in account management widgets you may want to use on your site (for forgot password, manage account, etc.) You will want to keep these multi-use scenarios in mind when designing your page.

If you use the Identity Toolkit sign-in button described above, all you need to do is configure the button's widgetUrl to point to your widget page. Otherwise, if you do not use the provided button, you must add the query parameter mode=select to begin the sign-in process, or mode=manageAccount to invoke the account management page. Note that the account management page will only function if the gtoken cookie is present—if your site uses its own session cookie, you might need to ask the user to re-authenticate before they can view the management page.

Additionally, append the query parameter signInSuccessUrl when loading the widget page for sign-in to configure where the user will be redirected to after sign-in completes. This query parameter can be useful when you would like to return the user to their current page after signing in.

Here again, you can download the <head> code from Developer Console, but will need to add the <div id="gitkitWidgetDiv"></div> yourself. (Note that if you want to support Yahoo login, you will need additional logic to appropriately replace JAVASCRIPT_ESCAPED_POST_BODY depending on GET or POST requests. That is described in the per-language quick-start guides.)

You should then end up with something like this:

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

    <!-- Copy and paste here the "Widget javascript" you downloaded from Developer Console as gitkit-widget.html -->

    <script type="text/javascript" src="//www.gstatic.com/authtoolkit/js/gitkit.js"></script>
    <link type="text/css" rel="stylesheet" href="//www.gstatic.com/authtoolkit/css/gitkit.css" />
    <script type="text/javascript">
      var config = {
          apiKey: 'AIza...',
          signInSuccessUrl: '/',
          signInOptions: ["google", "password"],
          oobActionUrl: '/',
          siteName: 'this site',

          // Optional - function called after sign in completes and before
          // redirecting to signInSuccessUrl. Return false to disable
          // redirect.
          // callbacks: {
          //  signInSuccess: function(tokenString, accountInfo,
          //    opt_signInSuccessUrl) {
          //      return true;
          //    }
          // },

          // Optional - key for query parameter that overrides
          // signInSuccessUrl value (default: 'signInSuccessUrl')
          // queryParameterForSignInSuccessUrl: 'url'

          // Optional - URL of site ToS (linked and req. consent for signup)
          // tosUrl: 'http://example.com/terms_of_service',

          // Optional - Cookie name (default: gtoken)
          //            NOTE: Also needs to be added to config of the ‘page with
          //                  sign in button’. See above
          // cookieName: ‘example_cookie’,

          // Optional - Flag for disabling/enabling accountchooser.com.
          // Whether accountchooser.com is to be presented on sign in/up (default: true)
          // Disabling Account Chooser from the sign in flow is not recommended.
          // It can result in a non-optimal user experience, as it may add additional
          // steps and increase sign in friction due to the need to type in emails for
          // returning registered users who previously signed in or have saved accounts
          // in Account Chooser.
          // accountChooserEnabled: true,

           // Optional - UI configuration for accountchooser.com
           /*acUiConfig: {
               title: 'Sign in to example.com',
               favicon: 'http://example.com/favicon.ico',
               branding: 'http://example.com/account_choooser_branding'
           },
           */

           // Optional - Function to send ajax POST requests to your Recover URL
           //            Intended for CSRF protection, see Advanced Topics
           //      url - URL to send the POST request to
           //     data - Raw data to include as the body of the request
           //completed - Function to call with the object that you parse from
           //            the JSON response text. {} if no response
           /*ajaxSender: function(url, data, completed) {
                         },
           */
      };
      // The HTTP POST body should be escaped by the server to prevent XSS
      window.google.identitytoolkit.start(
          '#gitkitWidgetDiv', // accepts any CSS selector
          config,
          'JAVASCRIPT_ESCAPED_POST_BODY');
    </script>

    <!-- End modification -->

  </head>
  <body>

    <!-- Include the sign in page widget with the matching 'gitkitWidgetDiv' id -->
    <div id="gitkitWidgetDiv"></div>
    <!-- End identity toolkit widget -->

  </body>
</html>

Email first vs provider first modes

The Identity Toolkit sign in widget supports two different flows: Email First and Provider First.

Email first mode

In this flow, which is enabled by default, the widget will first ask the user for their email address, and it will intelligently decide whether to try to sign that user in, or prompt that user to create a new account.

If Account Chooser is enabled (accountChooserEnabled: true,), the user may be prompted at the beginning of the flow with a credential picker so they can quickly input an email address they previously used, with one tap. Else, or if the user had no credentials stored in accountchooser.com, the user will have to type their email address in full.

This flow is enabled by default, but you can also manually enable it by including the following entry in your sign in widget config: displayMode: 'emailFirst'

Provider first mode

In this flow, the user will always be prompted first with a screen outlining the different sign in options supported, like the screen below:

This mode is similar to our native flows in Android and iOS, and we recommend it for websites targeted at mobile devices, because it can save the user some typing.

In this mode, if Account Chooser is enabled (accountChooserEnabled: true,), the user may be prompted with a credential picker after they click on “Sign in with email”, so they can quickly input an email address they previously used, with one tap.

In order to enable this flow, include the following entry in your sign in widget config: displayMode: 'providerFirst'

Customizing the UI

The user interface of the Identity Toolkit widgets is designed to be simple and look good on most sites, but customization is easy. The main pieces that you may want to customize include:

  1. CSS: It is possible to significantly modify the look of the different widgets by editing the css of the widgets
  2. Sign in page: The sign in page widget is designed to be compatible for desktop and mobile web and can be embedded in your own page with custom header, footer, etc. If you wish to launch the sign in page without using our button, then please append ?mode=select to the widget URL.
  3. Account Chooser: The Account Chooser is a separate web site that is owned and operated by the Open ID Foundation. Identity Toolkit manages the interface between your app and Account Chooser but you should also specify the branding and text that you want displayed on the Account Chooser UI. To customize the look of Account Chooser, set the optional acUiConfig values as documented in the example javascript configuration show above.
    • title: the string that should be displayed as the title.
    • favicon: full path to the favicon that should be displayed.
    • branding: full path to the branding resource that should be displayed. The resource will be sanitized to remove any Javascript-related vulnerabilities. For example:
  <!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  </head>
  <body>
    <div style="width:256px;margin:auto">
      <img src="/r/images/logo_160px.png" style="display:block;height:160px;width:160px;margin:auto">
      <p style="font-size:14px;opacity:.54;margin-top:20px;text-align:center">
        Welcome to our Demo.
      </p>
    </div>
  </body>
</html>

Notes

  1. Widgets should work well on mobile devices by default as long as the viewport header is included. This can be customized by you, but an example is:

    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    
  2. Wherever a URL is needed, both absolute and relative are okay.