The newest version of Google Identity Toolkit has been released as Google Cloud's Identity Platform and Firebase Authentication. These products include upgraded client SDKs, open source UI libraries, session management and integrated email sending service for forgotten password flows.

Based on your needs, new projects should use either Identity Platform or Firebase Authentication. To migrate an existing project from Identity Toolkit, see the Identity Platform migration guide or Firebase Authentication migration guide.

Migrate from Google Identity Toolkit to Google Cloud's Identity Platform

The newest version of Google Identity Toolkit has been released as Identity Platform and Firebase Authentication. Going forward, feature work on Identity Toolkit will be frozen; all new feature development will be done on Identity Platform and Firebase Authentication. We encourage Identity Toolkit developers to move to these platforms as soon as it is practical for their applications.

New Features

Identity Platform already has significant feature enhancements over Google Identity Toolkit:

New admin console

Identity Platform has a new developer console which allows you to view, modify and delete your users; this can be helpful debugging your sign-in and sign-up flows. The console also allows you to configure authentication methods and customize email templates.
New methods of Authentication

Identity Platform supports enterprise federation standards, such as SAML and OIDC, enabling you to scale SaaS apps and services. Identity Platform also offers support for providers such as GitHub, Microsoft, Yahoo and more. You can use anonymous sign-in to create a unique user ID without requiring the user to go through any sign-in or sign-up process; this allows you to make authenticated API calls as you would with a regular user. When the user decides to sign up for an account, all activity is preserved with the same user ID. This is valuable for scenarios like server side shopping carts or other applications where you want to engage the user before sending them through a sign-up flow.
Scale with confidence with Service Level Agreements and Cloud Support

Identity Platform is built on trusted Google infrastructure, and provides Service Level Agreements and support from Google Cloud. This means that you can scale your service with confidence, and rely on Google to provide the resiliance, availability and scalability that you need.
Access to all of Firebase

Firebase is a mobile platform that helps you quickly develop high-quality apps, grow your user base, and earn more money. Firebase is made up of complementary features that you can mix-and-match to fit your needs and includes infrastructure for: mobile analytics, cloud messaging, realtime database, file storage, static hosting, remote configuration, mobile crash reporting and Android testing.
Updated UIs

We have completely rebuilt the UI flows based on Google's latest UX research. This includes password recovery, account linking, new/existing account disambiguation flows that often take significant time to code and debug. It integrates Smart Lock for Passwords on Android, which has significantly improved sign-in and sign-up conversion for participating apps. It also supports easy theme modifications to match your application and, for maximum customizability, the Android and iOS versions have been open sourced.
Simplified server setup

With Identity Toolkit, we saw that many developers chose not to implement the email recovery flow which made it impossible for their users to recover their accounts if they forgot their password. Identity Platform can send email verification, password reset, and changed password messages to the user and the text can be easily customized for your users. Additionally, you no longer need to host the UI widgets for hosting redirects and completing password change operations.
New SDKs

All of Identity Toolkit's server APIs are now available natively with each of our client libraries (Android, iOS, web). Developers will be able to sign in and sign up old and new users, access user properties, link, update and delete accounts, reset passwords, and more without being tied to a fixed UI. If you prefer, you can manually build your own entire sign in flow and experience on top of this API.
Session management for mobile apps

With Identity Toolkit, apps created their own session state based on the initial authentication event from Identity Toolkit. Identity Platform uses a backend service that takes a refresh token, minted from the authentication event, and exchanges it for hour-long access tokens for Android, iOS and JavaScript. When a user changes their password, refresh tokens will no longer be able to generate new access tokens, thereby disabling access until the user reauthenticates on that device.

Feature Differences

Some Identity Toolkit features are not currently available in Identity Platform, while other features have been redesigned and work differently. You might choose not to migrate immediately if these features are important to your app. In many cases, these features might not be important for your app or there might be easy fallbacks which will enable you to proceed with migration.

Server side differences

The core Identity Toolkit service with its underlying REST APIs, account validation logic, and master user database have undergone only minor updates. But some features and the manner in which you integrate Identity Platform into your service has changed.

Identity Providers

Paypal and AOL are not supported. Users with accounts from these IDPs can still sign in to your application with the password recovery flow and set up a password for their account.
Server libraries

Currently, there are Admin SDKs available for Java, Node.js, Python, Go and C#.
Account management emails

Password reset, email verification, and email change messages can be performed by Firebase or from the developer's own mail server. Currently, email templates offer only limited customization from the UI, but can be further customized with the Admin SDKs
Email address change confirmation

In Identity Toolkit, when a user decides to change their email address, it sends an email to the new address that has a link to continue the email address change flow.

Firebase confirms the email address change by sending a revocation email to the old email address with a link to revert the change.
IDP rollout

Identity Toolkit had an ability to add identity providers to your sign-in system gradually, so that you could experiment with the impact on your support requests. This feature was removed in Firebase Authentication.

Client side differences

In Identity Platform, the features provided by Google Identity Toolkit are split into two components:

Client and Server SDKs

In Identity Platform, the functionality provided by Identity Toolkit's REST API has been packaged into client SDKs available for Android, iOS, and JavaScript. You can use the SDK to sign in and sign up users; access user profile information; link, update and delete accounts; and reset passwords using the client SDK instead of communicating with the back end service via REST calls.
UI Widget

All of the UI flows that manage sign-in, sign-up, password recovery, and account linking have been rebuilt using the Client SDKs and packaged as a login widget. They are available as open source SDKs for iOS, Android, and Web, and enable you to completely customize the flows in ways not possible with Identity Toolkit.

Additional differences include:

Sessions and migration

Because sessions are managed differently in Identity Toolkit and Identity Platform, your users' existing sessions will be terminated upon upgrading the SDK, and your users will have to sign in again.

Before you begin

Before you can migrate from Identity Toolkit to Identity Platform, you must:

Open the Cloud console and select your Identity Toolkit project.
From the Marketplace, browse to Identity Platform and select 'Enable Identity Platform'
Open the Service accounts page. Here you can see the service account you previously configured for Identity Toolkit.
Next to the service account, click > Create key. Then, in the Create private key dialog, set the Key type to JSON and click Create. A JSON file containing your service account's credentials is downloaded for you. You'll need this to initialize the SDK in the next step.

Important: This file contains sensitive information, including your service account's private encryption key, and is only generated once. If you lose or leak the key, you can use the service account management page to create a new JSON key for the service account.
Go back to the Cloud console. In the Providers section, within the 'Email/Password' sign-in method, open the Email Templates page. You can then customize your app's templates.

In Identity Toolkit, when users reset passwords, changed email addresses, or verified their email addresses, you needed to get an OOB code from the Identity Toolkit server, and then send the code to users through email. Identity Platform sends emails based on the templates you configure with no additional actions required.

Optional: If you need to access Identity Platform services on your server, install the Firebase SDK.

You can install the Node.js Admin SDK with npm:

$ npm init
$ npm install --save firebase-admin

In your code, you can access Firebase using:

var admin = require('firebase-admin');
var app = admin.initializeApp({
  credential: admin.credential.cert('path/to/serviceAccountCredentials.json')
});

Next, complete the migration steps for your app's platform: Android, iOS, web.

Servers and JavaScript

Notable changes

There are a number of additional differences in the web implementation of Identity Platform from Identity Toolkit.

Web session management

Previously, when a user authenticated using the Identity Toolkit widget, a cookie was set for the user which was used to bootstrap the session. This cookie had a two week lifetime and was used to allow the user to use the account management widget to change password and email address. Some sites used this cookie to authenticate all other page requests on the site. Other sites used the cookie to create their own cookies via their framework's cookie management system.

Identity Platform client SDKs now manage Id tokens and work with Identity Platforms's backend to keep the session fresh. The backend expires sessions when important account changes (like user password changes) have occurred. Id tokens are not automatically set as cookies on the web client and have only an hour lifetime. Unless you want sessions of only an hour, Id tokens are not appropriate to be used as the cookie to validate all of your page requests. Instead, you will need to set up a listener for when the user logs in, get the Id token, validate the token, and create your own cookie via your framework's cookie management system.

You will need to set the session lifetime of your cookie based on the security needs of your application.
Web sign-in flow

Previously, users were redirected to accountchooser.com when sign-in was initiated to learn what identifier the user wanted to use. Identity Platform UI's flow now begins with a list of sign-in methods, including an email option which goes to accountchooser.com for web and uses the hintRequest API on Android. In addition, email addresses are no longer required in the UI. This will make it easier to support anonymous users, custom auth users or users from providers where email addresses are not required.
Account management widget

This widget provides a UI for users to change email addresses, change password ors unlink their accounts from identity providers. It is currently under development.
Sign-in button/widget

Widgets like the sign-in button and user card are no longer provided. They can be built very easily using the Firebase Authentication API.
No signOutUrl

You will need to call firebase.auth.signOut() and handle the callback.
No oobActionUrl

Email sending is now handled by Identity Platform and is configured in the Firebase console.
CSS customization

The UI widget uses Material Design Lite styling, which dynamically adds Material Design animations.

Step 1: Change Server Code

If your server relies on the Identity Toolkit token (valid for two weeks) to manage web user sessions, you need to convert the server to use its own session cookie.
1. Implement an endpoint for validating the Id token and setting the session cookie for the user. The client app sends the Firebase ID token to this endpoint.
2. If the incoming request contains your own session cookie, you can consider the user authenticated. Otherwise, treat the request as unauthenticated.
3. If you do not want any of your users to lose their existing logged-in sessions, you should wait for two weeks for all Identity Toolkit tokens to expire, or also do the dual token validation for your web application as described below in step 3.
Next, because the Id tokens are different than Identity Toolkit tokens, you must update your token validation logic. Install the Admin SDK to your server; or, if you use a language not supported by the Admin SDK, download a JWT token validation library for your environment and properly validate the token.
When you first make the above updates, you might still have code paths that rely on Identity Toolkit tokens. If you have iOS or Android applications, users will need to upgrade to the new version of the app in order to have the new code paths work. If you don't want to force your users to update your app, you can add additional server validation logic that examines the token and determines whether it needs to use the Firebase SDK or the Identity Toolkit SDK to validate the token. If you only have a web application, all new authentication requests will be shifted over to Identity Platform and, therefore, you only need to use the Id token verification methods.

See the Web API Reference.

Step 2: Update your HTML

Add the initialization code to your app:
1. Open your project in the Cloud console.
2. On the providers page, click Application Setup Details. A code snippet that initializes Identity Platform is displayed.
3. Copy and paste the initialization snippet into your web page.

Add Authentication Widget to your app:

<script src="https://www.gstatic.com/firebasejs/ui/live/0.4/firebase-ui-auth.js"></script>
<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/firebasejs/ui/live/0.4/firebase-ui-auth.css" />
<!-- *******************************************************************************************
   * TODO(DEVELOPER): Paste the initialization snippet from:
   * Firebase Console > Overview > Add Firebase to your web app. *
   ***************************************************************************************** -->
<script type="text/javascript">
  // FirebaseUI config.
  var uiConfig = {
    'signInSuccessUrl': '<url-to-redirect-to-on-success>',
    'signInOptions': [
      // Leave the lines as is for the providers you want to offer your users.
      firebase.auth.GoogleAuthProvider.PROVIDER_ID,
      firebase.auth.FacebookAuthProvider.PROVIDER_ID,
      firebase.auth.TwitterAuthProvider.PROVIDER_ID,
      firebase.auth.GithubAuthProvider.PROVIDER_ID,
      firebase.auth.EmailAuthProvider.PROVIDER_ID
    ],
    // Terms of service url.
    'tosUrl': '<your-tos-url>',
  };

  // Initialize the FirebaseUI Widget using Firebase.
  var ui = new firebaseui.auth.AuthUI(firebase.auth());
  // The start method will wait until the DOM is loaded.
  ui.start('#firebaseui-auth-container', uiConfig);
</script>

Remove the Identity Toolkit SDK from your app.
If you relied on the Identity Toolkit ID token for session management, you must make the following changes on the client side:
1. After successfully signing in with Identity Platform, get an Id token by calling firebase.auth().currentUser.getToken().
2. Send the Id token to the backend server, validate it, and issue your own session cookie.
  
  Do not rely solely on the session cookie when performing sensitive operations or sending authenticated edit requests to your server. You will need to provide additional cross-site request forgery (CSRF) protection.
  
  If your framework does not provide CSRF protection, one way to prevent an attack would be to get an Id token for the signed-in user with getToken() and include the token with each request (the session cookie will also be sent by default). You would then validate that token using the Admin SDK in addition to the session cookie check, which your backend framework completed. This will make it harder for CSRF attacks to succeed, as the Id token is only stored using web storage and never in a cookie.
3. Identity Toolkit tokens are valid for two weeks. You may want to continue issuing tokens that last two weeks, or you might want to make it longer or shorter based on the security requirements of your app. When a user signs out, clear the session cookie.

Step 3: Update IDP redirect URLs

In the Cloud Console, open the Providers section.
For each federated sign-in provider you support, do the following:
1. Click the name of the sign-in provider.
2. Copy the OAuth redirect URI.
3. In the sign-in provider's developer console, update the OAuth redirect URI.

Android

Step 1: Add Identity Platform to your app with Firebase

Open the Cloud Console, and select your Identity Toolkit project.
On the Providers page, click Application setup details, select the Android tab, and then click Get Started in Firebase. In the Add Firebase dialog, provide your app's package name and signing certificate fingerprint and click Add App. The google-services.json configuration file is then downloaded to your computer.
Copy the configuration file to your Android app module root directory. This configuration file contains project and Google OAuth client information.
In your Project-level build.gradle file (<var>your-project</var>/build.gradle), specify your app's package name in the defaultConfig section:
```
defaultConfig {
   …..
  applicationId "com.your-app"
}
```

Also in your Project-level build.gradle file, add a dependency to include the google-services plugin:

buildscript {
 dependencies {
   // Add this line
   classpath 'com.google.gms:google-services:3.0.0'
 }
}

In your app's App-level build.gradle file (<var>my-project</var>/<var>app-module</var>/build.gradle), add the following line after the Android Gradle plugin to enable the google-services plugin:
```
apply plugin: 'com.android.application'
// Add this line
apply plugin: 'com.google.gms.google-services'
```
The google-services plugin uses the google-services.json file to configure your application to use Firebase.

Also in the App-level build.gradle file, add the Firebase Authentication dependency:

compile 'com.google.firebase:firebase-auth:19.3.0'
compile 'com.google.android.gms:play-services-auth:18.0.0'

Step 2: Remove the Identity Toolkit SDK

Remove the Identity Toolkit configuration from the AndroidManifest.xml file. This information is included in the google-service.json file and loaded by the google-services plugin.
Remove the Identity Toolkit SDK from your app.

Step 3: Add FirebaseUI to your app

Add FirebaseUI Auth to your app.
In your app, replace calls to the Identity Toolkit SDK with calls to FirebaseUI.

iOS

Step 1: Add Firebase to your app

Add the client SDK to your app by running the following commands:
```
$ cd your-project directory
$ pod init
$ pod 'Firebase'
```
Open the Cloud Console, and select your Identity Toolkit project.
On the Providers page, click Application setup details, select the iOS tab, and then click Get Started in Firebase. In the Add Firebase dialog, provide your app's package name and signing certificate fingerprint and click Add App. The google-services.json configuration file is then downloaded to your computer. In the Add Firebase dialog, provide your app's bundle ID and App Store ID, and then click Add App. The GoogleService-Info.plist configuration file is then downloaded to your computer. If you have multiple bundle IDs in your project, each bundle ID must be connected in the Firebase console so it can have its own GoogleService-Info.plist file.
Copy the configuration file to the root of your Xcode project and add it to all targets.

Step 2: Remove the Identity Toolkit SDK

Remove GoogleIdentityToolkit from your app's Podfile.
Run the pod install command.

Step 3: Add FirebaseUI to your app

Add FirebaseUI Auth to your app.
In your app, replace calls to the Identity Toolkit SDK with calls to FirebaseUI.