← Back to guides

Migrate from Firebase Authentication to Own Auth

To migrate from Firebase Authentication to Own Auth, export users with the Firebase CLI, preserve Firebase UIDs in an application mapping, and move users through a verified magic-link or password-reset claim. Firebase's modified SCRYPT hashes and Firebase-issued tokens are not drop-in Own Auth credentials.

Firebase Authentication migration is an identity cutover. Inventory users, login methods, application foreign keys, active sessions, organisations, and recovery flows.

Export and inventory Firebase Authentication users

  1. Run firebase auth:export against the intended production project and choose JSON for structured migration work.
  2. Store the project's hash parameters separately as secrets if they are needed for audit or a custom transition service.
  3. Inventory providerData, disabled state, email verification, tenant IDs, custom claims, and application records keyed by Firebase UID.
  4. Identify accounts whose exported passwordHash or salt is empty and route them through account recovery.

Account transition

Own Auth creates new passwords with Argon2id and verifies only its documented hash formats. Do not copy an arbitrary provider password digest into Own Auth tables. The portable default is to create a passwordless user, verify control of the email address with a single-use magic link, and let the user set a new password through the password-reset flow.

  • Firebase ID tokens and refresh tokens remain Firebase credentials and cannot create Own Auth sessions.
  • Firebase SCRYPT is a provider-specific variant, not the documented Own Auth legacy scrypt format.
  • Custom claims must become application authorization data or explicit Own Auth roles and permissions.
  • Provider-linked users need to re-link through the application's verified OAuth flow.
scripts/import-users.ts
await auth.createUser({
  email: exportedUser.email,
  name: exportedUser.name ?? undefined,
  metadata: {
    migrationSource: "firebase-auth",
    legacyUserId: exportedUser.id,
  },
});

Run imports through a server-only script with an idempotent legacy-ID mapping. Do not call this from a public route. Reconcile source and destination counts, duplicate emails, disabled accounts, and failures before sending any claim links.

Move application ownership safely

Keep the old provider ID in an application-owned mapping table until every foreign key and background job uses the Own Auth user ID. A matching email string is not enough to attach billing records, private content, or organisation membership. Require a verified claim before transferring access.

  1. Create Own Auth tables in the staging and production databases with the official migration command.
  2. Import disabled or deleted status separately so blocked accounts do not regain access.
  3. Create an explicit legacy-provider-ID to Own-Auth-user-ID mapping.
  4. Send claim links in controlled batches and rate-limit the claim endpoint.
  5. Transfer application records only after the claim succeeds.
  6. Keep an audit record of imported, claimed, skipped, and failed accounts without logging tokens or passwords.

Session replacement

Firebase clients exchange refresh tokens for Firebase ID tokens, while Own Auth uses an opaque token backed by a database session. Do not bridge the formats. During cutover, verify Firebase tokens only in the legacy path, complete the account claim, then issue a new Own Auth session and retire the Firebase refresh token.

Use different cookie names during a short parallel window. Validate each cookie only with the system that issued it. Never accept an old provider token as an Own Auth session token, and remove the legacy validation path after the announced migration window.

Cutover and rollback

  1. Freeze authentication configuration changes while taking the final export.
  2. Run the idempotent import and reconcile counts.
  3. Enable Own Auth sign-in and recovery for a small internal cohort.
  4. Monitor sign-in failures, claim completion, email delivery, and support requests.
  5. Switch new sign-ins to Own Auth while retaining a time-limited rollback path.
  6. Revoke old provider sessions and credentials only after the cutover is stable.
  7. Delete encrypted working exports according to the migration retention plan.

The successful end state is not two permanent auth systems. Firebase Authentication becomes read-only during the transition, Own Auth becomes the only issuer of new sessions, and the legacy path is removed after account recovery and data reconciliation are complete.