Firebase Migration Guide

Migrating your Firebase users to Descope can be a smooth process with the right guidance. This guide provides detailed steps for a seamless transition.

There are two ways you migrate to Descope from Firebase. You can either do a Full Migration or a Hybrid Migration.

• Full Migration - You completely move off of Firebase Authentication to Descope, no longer using Firebase authentication in any way. (Most Common)
• Hybrid Migration - You still use Firebase Authentication but you will authenticate your users with Descope (as a federated IdP).

This documentation will cover both of these migration options. If you want to continue with the Hybrid Migration, complete the first step under Full Migration first, and then skip to Hybrid Migration.

Full Migration

If you desire to completely move away from Firebase Authentication, the Full Migration option is the one for you. Otherwise, complete Step 1 under the Full Migration guide and then skip to the Hybrid Migration section.

Prerequisites

Ensure you have the following before starting:

• Access to your Firebase account with permissions to manage Authentication.
• Familiarity with your current Firebase Authentication setup.

1. Importing Users from Firebase

Configure Local Environment

Follow these detailed steps to set up your environment for migration:

1. Clone the Repo:

git clone git@github.com:descope/descope-migration.git

2. Create a Virtual Environment:

python3 -m venv venv
source venv/bin/activate

3. Install Python Libraries:

pip3 install -r requirements.txt

4. Download Firebase Credential: This is created by following the instructions in the Firebase docs. You'll then need to copy over the JSON file, rename it to firebase-certs.json and put it in the /creds folder. For more details, refer below
5. Get Password Hash Parameters: You'll need to provide the password hash parameters that are specific to your Firebase project. This is mandatory if you're migrating passwords over to Descope. For more details, refer below.
6. Set up Environment Variables: Adjust the .env.example file and rename it to .env. For more details, refer below.
7. Custom Attributes: The tool depends on a few custom user attributes that will be automatically created within Descope to assist you with the migration. The below outlines the machine names of the attributes that will be created.
   • freshlyMigrated (type: Boolean): This custom attribute will be set to true during the migration. This allows for you to later check this via a conditional during Descope flow execution, see Post-Migration.
   • UUID (type: String): This is the UUID value of the user in firebase.
   • All other custom attributes defined in either Firestore or the Realtime Database Schema.

Firebase Credentials:

You'll need to download your Firebase Credential and put it in the /creds folder in order to give the Firebase Admin SDK access to your user table.

1. First, you'll need to open Settings > Service Accounts, in the Firebase Console.

2. Click Generate New Private Key, then confirm by clicking Generate Key.

3. Securely store the JSON file containing the key, in the /creds folder, in the root of this repository. Rename it to firebase-certs.json.

Password Hash Parameters:

In order to successfully copy over the passwords over your users, you'll need to provide the password hash parameters that are specific to your Firebase project. You can find these in the Firebase Console, under Authentication -> Users.

Under the three dots in the top right corner, you'll find the option for Password hash parameters. Once you've opened these up, copy these over to a password-hash.txt file and place it in the /creds folder.

After that, the migration tool will automatically recognize your password hash parameters and extract the necessary claims from the parameters JSON.

Environment Variables:

The environment variables that are mandatory, no matter what, are the following:

1. DESCOPE_PROJECT_ID - You can get this from Project Settings in the Console
2. DESCOPE_MANAGEMENT_KEY - You can get this from Company Settings -> Management Keys in the Console

There is one optional environment variable, which you will need to provide if you're custom user attributes are stored using Firebase Realtime Database. This is the Database URL that you can find in your Realtime Database Dashboard.

1. FIREBASE_DB_URL - You'll need this so that the tool knows what database to request information from.

Running the Migration Script

You can use the -v or --verbose flags to enable more detailed output. This works for both live and dry runs, providing you with additional information.

Dry Run:

Before executing the live migration, you can perform a dry run to estimate the scope of the migration:

python3 src/main.py firebase --dry-run

This will output the number of users and other entities to be migrated.

Live Migration:

To start the actual migration, run:

python3 src/main.py firebase

Follow the instructions provided by the tool, including whether to migrate custom attributes and from which Firebase database.

The tool will first ask if you want to migrate custom attributes over. If you type y, then you'll need to provide the tool with the source of the attributes (either Firestore or Realtime Database). After that, the tool will begin migrating your users. The output will include the responses of the created usersas well as the mapping between the various objects within Descope.

A log file will also be generated in the format of migration_log_firebase_%d_%m_%Y_%H:%M:%S.log. Any items which failed to be migrated will also be listed with the error that occurred during the migration.

Starting migration of 112 users found via Firebase Admin SDK
Still working, migrated 10 users.
...
Still working, migrated 110 users.
=================== User Migration =============================
Firebase Users found via Admin SDK 112
Successfully migrated 112 users
Successfully merged 0 users
Created users within Descope 112

2. Additional Migration Steps

You can also migrate your Firebase configurations manually in the Descope console, such as Authorized Domains and Self-Registration Allowance.

• Authorized Domains - you can move these over to the Approved Domains section in the Descope Console

Firebase Console	Descope Console

• Enable Create (Sign Up) - you can block self-registration under Project Settings in the Descope Console

Firebase Console	Descope Console

3. Testing and Finalizing Migration

Once all of these have been completed, it's a good idea to perform comprehensive testing to ensure all functionalities are working as expected, and your user migration went smoothly.

Congratulations, you've fully migrated to Descope! If you're doing the Hybrid Migration approach, you can read on to the next section of this documentation.

Hybrid Migration

Hybrid Migration is less common with Firebase Authentication because you can fully use Descope while continuing to use other Firebase services. However, if you have a specific use case, Descope can be used as your authentication service within Firebase Authentication.

1. Integrating Descope as an Identity Provider

Assuming you've already followed the Step 1 under Full Migration above, you should already have all of your users in Descope. After successfully importing the user data from Firebase, you can proceed with configuring Descope as an external identity provider.

To do this, follow the guide on configuring it as an external identity provider for Firebase.

2. Testing and Finalizing Migration

Once you configured Descope as an external identity provider, you should be able to now login using Descope Flows. Once all of these steps have been completed, it's a good idea to perform comprehensive testing to ensure all functionalities are working as expected, and your user migration went smoothly.

Post Migration Verification

Once you have migrated your users to Descope, you can define your user's login experience. Utilizing the freshlyMigrated custom user attribute, you can define a path for your user.

You can then go down different paths from this conditional within the flow. If you'd like to verify the user's email or phone, you can, and then proceed with adding passwords (or forcing update of password if you migrated passwords) and passkeys.

Then after defining the user's experience, you will need to update the user's properties setting the freshlyMigrated attribute to false.