The newest version of Google Identity Toolkit has been released as
[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 and all new
feature development will be done on Firebase Authentication. We encourage
Identity Toolkit developers to move to Firebase Authentication as soon as is
practical for their applications; however, Identity Toolkit continues to work
and will not be deprecated without a further announcement.

## New Features

Firebase Authentication already has some significant feature enhancements over
Google Identity Toolkit:

- **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**

  We have made it easier for developers to use Firebase Authentication. 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. Firebase Authentication 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 admin console**

  Firebase has a [new developer console](https://console.firebase.google.com/)
  and the Authentication section allows you to view, modify and delete your
  users. This can be a great help in debugging your sign-in and sign-up flows.
  The console also allows you to configure authentication methods and
  customize email templates.
- **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. Firebase Auth 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.
- **Anonymous and GitHub authentication**

  Firebase Authentication supports two new authentication types: GitHub and
  anonymous. Anonymous sign-in can be used to create a unique user ID without
  requiring the user to go through any sign-in or sign-up process. With an
  anonymous user, you can now make authenticated API calls, like 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 great for situations
  like a server side shopping cart or any application where you want to engage
  the user before sending them through a sign-up flow.

## Feature Differences

Some Identity Toolkit features are not currently available in Firebase
Authentication, 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 Firebase Authentication
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 [Firebase 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, Firebase email templates offer only limited
  customization.
- **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 Firebase, the features provided by Google Identity Toolkit are split into two
components:

- **Firebase Authentication SDKs**

  In Firebase Authentication, the functionality provided by Identity Toolkit's
  REST API has been packaged in 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.
- **FirebaseUI Auth**

  All of the UI flows that manage sign-in, sign-up, password recovery, and
  account linking have been rebuilt using the Frebase Authentication SDKs.
  They are available as open source SDKs for iOS and Android to 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 Firebase
  Authentication, 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 Firebase Authentication, you
must

1. Open the [Firebase console](https://console.firebase.google.com/), click
   **Import Google Project**, and select your Identity Toolkit project.

2. Click **\> Permissions** to open the
   IAM \& Admin page.

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 [Firebase console](https://console.firebase.google.com/).
   In the Auth section, open the **Email Templates** page. On this page,
   customize your app's email templates.

   In Identity Toolkit, when users reset passwords, changed email addresses and
   verified email their email addresses, you needed to get an OOB code from the
   Identity Toolkit server, and then send the code to users through email.
   Firebase sends emails based on the templates you configure with no
   additional actions required.
6. **Optional**: If you need to access Firebase services on your server,
   install the Firebase SDK.

   1. You can install the Firebase Node.js module 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-firebase.md.txt#android),
[iOS](https://developers.google.com/identity/toolkit/migrate-firebase.md.txt#ios), [web](https://developers.google.com/identity/toolkit/migrate-firebase.md.txt#servers_and_javascript).

## Servers and JavaScript

### Notable changes

There are a number of additional differences in the web implementation of
Firebase 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.

  Firebase client SDKs now manage [Firebase ID tokens](https://firebase.google.com/docs/auth/users#auth_tokens)
  and work with Firebase Authentication's backend to keep the session fresh.
  The backend expires sessions when important account changes (like user
  password changes) have occurred. Firebase 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, Firebase 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 Firebase ID token](https://firebase.google.com/docs/auth/server/verify-id-tokens#retrieve_id_tokens_on_clients),
  [validate the token](https://firebase.google.com/docs/auth/server/verify-id-tokens#verify_id_tokens_using_the_firebase_sdk), 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. Firebase Auth
  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 Firebase
  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 Firebase and is configured in the Firebase
  console.
- **CSS customization**

  FirebaseUI 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 Firebase ID token](https://firebase.google.com/docs/auth/server/verify-id-tokens#verify_id_tokens_using_the_firebase_sdk) 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 Firebase tokens are different than Identity Toolkit
   tokens, you must update your token validation logic. Install the [Firebase Server SDK](https://firebase.google.com/docs/server/setup) to your server; or, if you use a
   language not supported by the Firebase Server 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
   Firebase and, therefore, you only need to use the Firebase token
   verification methods.

See the [Firebase 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 Firebase initialization code to your app:

   1. Open your project in the [Firebase console](https://console.firebase.google.com/).
   2. On the Overview page, click **Add App** , then click **Add Firebase to your
      web app**. A code snippet that initializes Firebase is displayed.
   3. Copy and paste the initialization snippet into your web page.
2. Add [FirebaseUI Auth](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 Firebase, get a Firebase ID token by
      calling `firebase.auth().currentUser.getToken()`.

   2. Send the Firebase 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 a Firebase 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 Firebase server 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 Firebase 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 Firebase console, open the Authentication section and click the
   **Sign-in Method** tab.

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 Firebase to your app

1. Open the [Firebase console](https://console.firebase.google.com/), and
   select your Identity Toolkit project, which you already imported.

2. On the Overview page, click **Add App** , and then click **Add Firebase to
   your Android app** . 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 to the bottom to enable the google-services plugin:

       // Add to the bottom of the file
       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 Firebase SDK to your app by running the following commands:

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

2. Open the [Firebase console](https://console.firebase.google.com/), and
   select your Identity Toolkit project, which you already imported.

3. On the Overview page, click **Add App** , and then click **Add Firebase to
   your iOS app** . 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.