Migrate from Firebase

The WorkOS User Management API allows you to migrate your existing user data from a variety of existing sources. In this guide, we’ll walk through the steps to export your users from Firebase, and then import them into WorkOS.

Firebase customers can export their user data using either the Firebase CLI or the Firebase API. In this guide we’ll be using the Firebase CLI, use the following command to retrieve a dump of all users in JSON or CSV format.

firebase auth:export --project=<your_firebase_project_id> --format=json users.json

After obtaining your user data from Firebase, it’s time to import it into WorkOS, mapping attributes from the Firebase User format to WorkOS API parameters.

Using the WorkOS Create User API, you can create a corresponding record in WorkOS for each exported user. Use the following mapping from the Firebase format to parameters in your WorkOS Create User API calls:

If your users sign in to your Firebase application using passwords, you can choose to also import those password hashes. Firebase uses a forked version of scrypt which can be directly imported during the user creation process into WorkOS, or later using the Update User API.

First, retrieve your Firebase project's password hash parameters from the Firebase console following the export documentation. These parameters are the base64_signer_key, base64_salt_separator, rounds, and mem_cost.

Next, retrieve the password salts and hashes for each of your individual Firebase users by running the the Firebase CLI auth:export command. Your Firebase users that have a password set will have a passwordHash and salt field present which will be imported into WorkOS.

Finally, you will need to format these parameters into a PHC-compatible password hash following this Firebase to PHC hash parameter mapping:

The hash, salt, along with sk and ss parameters, should be B64 encoded, which means trimming the = characters that represent base64 padding. Using a PHC-formatting library, like @phc/format for Node, should handle this for you.

import * as phc from '@phc/format';
import { WorkOS } from '@workos-inc/node';

// Found in the Firebase console.
const firebaseHashParameters = {
  algorithm: 'SCRYPT',
  base64_signer_key:
    'jxspr8Ki0RYycVU8zykbdLGjFQ3McFUH0uiiTvC8pVMXAn210wjLNmdZJzxUECKbm0QsEmYUSDzZvpjeJ9WmXA==',
  base64_salt_separator: 'Bw==',
  rounds: 8,
  mem_cost: 14,
};

// Exported by the `auth:export` Firebase CLI command.
const firebaseUser = {
  localId: '3f9uMhgD7PS3Kmu2gFHEfcIxDIn2',
  passwordHash:
    'lSrfV15cpx95/sZS2W9c9Kp6i/LVgQNDNC/qzrCnh1SAyZvqmZqAjTdn3aoItz+VHjoZilo78198JAdRuid5lQ==',
  salt: '42xEC+ixf3L2lw==',
};

const passwordHash = phc.serialize({
  id: 'firebase-scrypt',
  version: 1,
  hash: Buffer.from(firebaseUser.passwordHash, 'base64'),
  salt: Buffer.from(firebaseUser.salt, 'base64'),
  params: {
    r: firebaseHashParameters.rounds,
    m: firebaseHashParameters.mem_cost,
    ss: Buffer.from(firebaseHashParameters.base64_salt_separator, 'base64'),
    sk: Buffer.from(firebaseHashParameters.base64_signer_key, 'base64'),
  },
});

const workOS = new WorkOS(process.env.WORKOS_API_KEY);

workOS.userManagement.updateUser({
  userId: 'user_012345678910abcd',
  passwordHashType: 'firebase-scrypt',
  passwordHash,
});

Firebase authentication methods vary depending on your specific usage, and corresponding connections can be easily configured in WorkOS. This allows users to continue signing in with the same authentication methods, matching the previous sign in experience.

If your users “Sign in with Google” or similar, you can configure WorkOS to continue using those sign in methods. Migrating these connections involves providing the same client credentials (i.e. Client ID and Client Secret) to WorkOS as configured in Firebase.

For more details on supported connections, see the provider-specific integration guides, such as for Microsoft and Google.

Reach out to support@workos.com if there are additional Social Auth providers you would like to see supported.

If your users sign in using Email Link, sometimes called “passwordless”, you can achieve the same experience by adding WorkOS Magic Auth to your application.

Enterprise authentication often uses standard protocols such as OpenID Connect (OIDC) or SAML between your service and identity provider.

The same identity providers can be configured in WorkOS, preserving the sign in process familiar to your users. For specific instructions, see the guides on setting up OIDC and SAML connections with WorkOS.