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.

Frequently Asked Questions

I don't have a website. Do I need to set up the webserver for my iOS/Android apps?

You don't need to have a website in the traditional sense, but you do need a webserver of some sort to expose endpoints for a few of the key flows such as email sending, post-login OAuth redirects, and account management. If you only want to support identity providers with native Android and iOS SDKs and don't need any sort of account management, you will not need these endpoints, but will still need to register in Google Developer Console.

This looks great, but I'm looking for something I can plugin to my web application framework (opencart, wordpress, etc). Do those exist?

As of July 2014, we do not have plugins available, but we hope that members of the community will engage with the per-language libraries and build plugins to support their favorite frameworks.

Can I customize the look and feel of the pages?

Yes!

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>

For more information about customizing mobile apps, please see either the iOS or Android sections.

I'm nervous about adding federated login to my site. How do I test this?

Once your app is relying on Identity Toolkit for authenticating passwords, it is possible to slowly roll out support for federated login with email providers.

One of the advantages of the Identity Toolkit UX flow is that it is designed to capture the user’s email address either via text field or via an account chooser and then funnel them through the appropriate sign-in flow based on their email provider. As a result, you can configure Identity Toolkit to route only a fraction of users to their email provider for federated login and progressively increase the percentage until you have full support.

Go to the Identity Toolkit Admin Console and next to each identity provider (IDP), there is an entry box to specify the IDP % Rollout. By default, these percentages start at 0% (password only) when you first enable Identity Toolkit. Specifying 1% by the Google IDP would tell Identity Toolkit that 1% of all users with @gmail.com or Google Apps hosted mailboxes should get routed to Google for authentication instead of challenging for password. Additionally, the percentage rollout will apply to new users going through the registration flow.

The percentage roll-out feature is applied randomly to all users of the IDP. The values are stable such that if you were to roll back your experiment from 10% to 5% and then roll forward again to 10%, the same users would be re-enabled with IDP login. You can also run experiments on test users that you specify. To do this, use the setAccountInfo API and mark the upgrade_to_federated_login value to true.

We recommend that you first roll out IDP login for Google before trying other providers. Google’s login flow works seamlessly with Identity Toolkit such that a user authenticating to Google will not see any consent screens or be forced to choose an account if they are multi-logged in. When you begin rolling out support for other IDPs, users will be asked to consent to provide basic account information to your site.

I'm an Identity Toolkit v1/v2 developer. How do I migrate to v3?

Identity Toolkit v3 is a significant restructuring, including a service that performs the authentication step and returns a Identity Toolkit ID Token to your app. Many of the user flows are similar to v2, so logical changes to the structure of your site will not change but you will need to replace your existing interfaces with Identity Toolkit. We are hoping to provide a smoother upgrade path soon.

To migrate, please follow the "Migrate an existing site" guidelines. These will work for v1/v2 sites as well as password-only. Please contact us if you have any questions.

How can I be extra sure that when a user changes their password on one device, they are signed out on the remainder of the devices?

By doing a little extra work, you can protect your users from this type of vulnerability. You’ll need to make the following changes:

  1. Add a per-user datum to your app’s storage: The timestamp of the last password change.
  2. Maintain this timestamp by noticing changes in the Identity Toolkit cookie (no analysis is required, just remember the last cookie value for this user and on each request, check whether it has changed). If it has, retrieve the latest password change time via getAccountInfo API, and persist it for that user. Also, to help with the next step, remember the timestamp of the cookie itself.
  3. On each request, compare your Identity Toolkit cookie’s timestamp to this per-user last-password-change timestamp. If the cookie’s timestamp is older, this means your user, in one session or another on some device or another, changed their password. In this case, you should end your current session and delete the Identity Toolkit cookie, forcing re-authentication.

Pseudocode

if session-is-alive
    // Check if password was just changed on this device
    if identity-toolkit-cookie-updated
        retrieve user_id from session
        retrieve user info from Identity Toolkit
        update local user database
        proceed to app
    // Check if password changed on another device
    else if identity-toolkit-cookie-time older than password-change-time
        redirect to signout
    else
        retrieve user_id from session
        proceed to app
else if identity-toolkit-cookie-valid
    retrieve user_id from session
    retrieve user info from Identity Toolkit
    if new-user
        collect additional registration info
        create new entry in local user database
    else
        update local user database
    create local session cookie
    proceed to app
else
    offer login flow to user

My CSRF protection requires me to send POST requests in a certain format. How do I do that?

In a few cases, Identity Toolkit widgets need make POST requests to your backend for things like recovering the user’s password. In this case, you may need for the POST request to contain a CSRF token or something similar to ensure this was a user-initiated action. This is built into many frameworks.

This can be achieved by writing a custom function for sending a POST request and passing it to the Identity Toolkit widget as a parameter. Here is a snippet from the standard sign in page HTML, but with an extra parameter which will cause a CSRF header to be included in POST requests to satisfy a Django-specific CSRF requirement. You will need to modify the code to satisfy the requirements of your framework:

...
<script type="text/javascript">
  var config = {
      apiKey: 'AIza...',
      signInSuccessUrl: '/',
      idps: ["google"],
      oobActionUrl: '/',
      siteName: 'this site',
      ajaxSender: function(url, data, cb) {
        // get CSRF token/code as csrfCode

        // pass CSRF code with request
        var result = jQuery.ajax({
          url: url,
          data: data,
          type: 'POST',
          async: false,
          cache: false,
          headers: {'X-CSRFToken': csrfCode}
        }).responseText;
        cb(jQuery.parseJSON(result) || {});
      }
  };
  google.identitytoolkit.handleGatOp('#gitkitWidgetDiv', config, decodeURIComponent('JAVASCRIPT_ESCAPED_POST_BODY'));
</script>
...

Can I download my user data?

Yes. As the developer, the data is yours to download and/or delete whenever needed. There are both downloadAccount and deleteAccount REST APIs (see the reference for details). Each of the per-language libraries included with the quick-start apps

How does Identity Toolkit relate to the Google Analytics User ID Policy?

At this time, using Identity Toolkit IDs with the Google Analytics User ID feature violates the policy. We are working on privacy-preserving way for Identity Toolkit developers to leverage the User ID feature.