Migrate from Firebase

Migrate your existing user data from Firebase into WorkOS using the AuthKit API. Follow these steps to export your users from Firebase and import them into WorkOS.

Export user data using either the Firebase CLI or the Firebase API. This guide uses the Firebase CLI. Run the following command to retrieve all users in JSON or CSV format.

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

Import your user data into WorkOS by mapping attributes from the Firebase User format to WorkOS API parameters.

Call the WorkOS Create User API to create a corresponding record for each exported user. Use the following mapping from the Firebase format to WorkOS Create User API parameters:

Import password hashes for users who sign in to your Firebase application using passwords. Firebase uses a forked version of scrypt which can be directly imported during the user creation process, 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 individual Firebase user by running the Firebase CLI auth:export command. Firebase users with a password set have passwordHash and salt fields that you will import into WorkOS.

Finally, format these parameters into a PHC-compatible password hash using 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.