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.

Migrate from Google Identity Toolkit to Firebase Authentication

The newest version of Google Identity Toolkit has been released as Firebase Authentication. 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, 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

    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 for your users. Additionally, you no longer need to host the UI widgets for hosting redirects and completing password change operations.

  • New admin console

    Firebase has a new developer console 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 master 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

    Microsoft, Paypal, AOL, and Yahoo are not supported yet. 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 server SDKs available for only Java and Node.js.

    However, the main purpose of the server SDKs in Firebase is to do token validation and make server-to-server API calls to the Firebase back end for account management. Because Firebase tokens conform to JWT standards, token validation can be done with open source libraries available for many languages. In addition, many account management tasks can now be performed in the Firebase Console.

  • Account management emails

    Password reset, email verification, and email change messages will be performed by Firebase and eventually won't be supported from the developer's own mail server (account management emails are now only client based and handled by Firebase). 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:

  • Internationalized UI

    FirebaseUI is currently only in English and translation of templates is not currently supported.

  • 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, click Import Google Project, and select your Identity Toolkit project.

  2. Click settings > 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 more_vert > 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.

  5. Go back to the Firebase console. 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
      
    2. In your code, you can access Firebase using:

      var firebase = require('firebase');
      var app = firebase.initializeApp({
        serviceAccount: "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 Firebase 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.

    Firebase client SDKs now manage Firebase ID 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 for when the user logs in, get the Firebase 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. 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 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 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 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 to your server; or, if you use a language not supported by the Firebase Server SDK, download a JWT token validation library for your environment and properly validate the token.

  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.

Step 2: Update your HTML

  1. Add the Firebase initialization code to your app:

    1. Open your project in the Firebase console.
    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 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, 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:11.0.4'
    compile 'com.google.android.gms:play-services-auth:11.0.4'
    

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 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, 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 to your app.

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