The newest version of Google Identity Toolkit has been released as
[Identity Platform](https://cloud.google.com/identity-platform/) and
[Firebase Authentication](https://firebase.google.com/docs/auth/?utm_campaign=Firebase_announcement_awareness_general_en_05-18-16_&utm_source=gdev&utm_medium=site).
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](https://console.cloud.google.com/customer-identity)
  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](https://cloud.google.com/identity-platform/sla)
  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](https://firebase.google.com/docs/analytics/),
  [cloud messaging](https://firebase.google.com/docs/cloud-messaging/),
  [realtime database](https://firebase.google.com/docs/database/),
  [file storage](https://firebase.google.com/docs/storage/),
  [static hosting](https://firebase.google.com/docs/hosting/),
  [remote configuration](https://firebase.google.com/docs/remote-config/),
  mobile [crash reporting](https://firebase.google.com/docs/crash/) and
  Android [testing](https://firebase.google.com/docs/test-lab/).
- **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](https://developers.google.com/identity/smartlock-passwords/android)
  on Android, which has significantly improved sign-in and sign-up conversion
  for participating [apps](https://developers.google.com/identity/smartlock-passwords/android/case-studies.md.txt).
  It also supports easy theme modifications to match your application and, for
  maximum customizability, the [Android](https://github.com/firebase/FirebaseUI-Android)
  and [iOS](https://github.com/firebase/FirebaseUI-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](https://support.google.com/firebase/answer/7000714)
  for your users. Additionally, you no longer need to host the
  [UI widgets](https://developers.google.com/identity/toolkit/web/setup-frontend) 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 primary 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](https://firebase.google.com/docs/admin/setup)
  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](https://firebase.google.com/docs/auth/admin/email-action-links)
- **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](https://github.com/firebase/firebaseui-ios),
  [Android](https://github.com/firebase/firebaseui-android), and
  [Web](https://github.com/firebase/firebaseui-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:

1. Open the [Cloud console](https://console.cloud.google.com/) and select your
   Identity Toolkit project.

2. From the Marketplace, browse to
   [Identity Platform](https://console.cloud.google.com/marketplace/details/google-cloud-platform/customer-identity)
   and select 'Enable Identity Platform'

3. Open the **Service accounts** page. Here you can see the service account you
   previously configured for Identity Toolkit.

4. 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]
   > **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](https://console.firebase.google.com/iam-admin/serviceaccounts/project) to create a new JSON key for the service account.

5. Go back to the [Cloud console](https://console.cloud.google.com/customer-identity).
   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.
6. **Optional**: If you need to access Identity Platform services on your
   server, install the Firebase SDK.

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

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

   2. 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](https://developers.google.com/identity/toolkit/migrate-identityplatform.md.txt#android),
[iOS](https://developers.google.com/identity/toolkit/migrate-identityplatform.md.txt#ios), [web](https://developers.google.com/identity/toolkit/migrate-identityplatform.md.txt#servers_and_javascript).

## 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](https://developers.google.com/identity/toolkit/web/setup-frontend#page_with_sign_in_widget),
  a cookie was set for the user which was used to
  [bootstrap the session](https://developers.google.com/identity/toolkit/web/required-endpoints).
  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](https://cloud.google.com/identity-platform/docs/concepts-manage-users#auth_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](https://firebase.google.com/docs/auth/web/manage-users#get_the_currently_signed-in_user)
  for when the user logs in,
  [get the Id token](https://firebase.google.com/docs/auth/admin/verify-id-tokens#retrieve_id_tokens_on_clients),
  [validate the token](https://cloud.google.com/identity-platform/docs/concepts-admin-auth-api#id_token_verification), 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](https://developers.google.com/identity/smartlock-passwords/android/retrieve-hints.md.txt) 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](https://getmdl.io/) styling, which
  dynamically adds Material Design animations.

### Step 1: Change Server Code

1. 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](https://cloud.google.com/identity-platform/docs/concepts-admin-auth-api#id_token_verification) 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.
2. Next, because the Id tokens are different than Identity Toolkit
   tokens, you must update your token validation logic. Install the
   [Admin SDK](https://firebase.google.com/docs/server/setup)
   to your server; or, if you use a language not supported by the Admin SDK,
   download a [JWT token validation library](https://jwt.io/)
   for your environment and properly
   [validate the token](https://firebase.google.com/docs/auth/server/verify-id-tokens#verify_id_tokens_using_the_firebase_sdk).

3. 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](https://firebase.google.com/docs/reference/js/).

### Step 2: Update your HTML

> [!WARNING]
> **Warning:** If you use Facebook Login or Twitter Login, you will be updating their redirect URLs. After you deploy your updated web UI, you will need to update the redirect URLs with those providers immediately. Users will be unable to sign in with either of these providers on the web while the two are out of sync. It is therefore important to have Step 2 and Step 3 happen in as quick succession as possible.

1. Add the initialization code to your app:

   1. Open your project in the [Cloud console](https://console.cloud.google.com/customer-identity).
   2. On the [providers](https://console.cloud.google.com/customer-identity/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.
2. Add [Authentication Widget](https://github.com/firebase/FirebaseUI-Web/)
   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>

3. Remove the Identity Toolkit SDK from your app.

4. 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

1. In the [Cloud Console](https://console.cloud.google.com/customer-identity),
   open the [Providers](https://console.cloud.google.com/customer-identity/providers)
   section.

2. 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

1. Open the
   [Cloud Console](https://console.cloud.google.com/customer-identity), and
   select your Identity Toolkit project.

2. 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.

3. Copy the configuration file to your Android app module root directory. This
   configuration file contains project and Google OAuth client information.

4. 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"
       }

5. 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'
        }
       }

6. 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.
7. Also in the App-level `build.gradle` file, add the Firebase Authentication
   dependency:

       compile 'com.google.firebase:firebase-auth:25.0.0'
       compile 'com.google.android.gms:play-services-auth:22.0.0'

### Step 2: Remove the Identity Toolkit SDK

1. 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.
2. Remove the Identity Toolkit SDK from your app.

### Step 3: Add FirebaseUI to your app

1. Add [FirebaseUI Auth](https://github.com/firebase/FirebaseUI-Android/tree/master/auth)
   to your app.

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

## iOS

### Step 1: Add Firebase to your app

1. Add the client SDK to your app by running the following commands:

       $ cd your-project directory
       $ pod init
       $ pod 'Firebase'

2. Open the
   [Cloud Console](https://console.cloud.google.com/customer-identity), and
   select your Identity Toolkit project.

3. 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.

4. Copy the configuration file to the root of your Xcode project and add it to
   all targets.

### Step 2: Remove the Identity Toolkit SDK

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

### Step 3: Add FirebaseUI to your app

1. Add [FirebaseUI Auth](https://github.com/firebase/FirebaseUI-iOS/tree/master/Auth)
   to your app.

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