Migrating Firebase Users Between Projects (With Tenants & Custom Claims)

Firebase Authentication is a developer-friendly way to manage user accounts, but sometimes real-world projects require more than just plug-and-play solutions. This article outlines a strategy for migrating Firebase users between projects, especially when dealing with tenants and custom claims.

The Challenge

Many projects start with a single Firebase account, but as they grow, the need to separate users into different tenants becomes crucial. Furthermore, the reliance on custom claims for roles and business logic adds complexity. Migrating users between environments (dev, staging, prod) without built-in Firebase features requires a custom solution.

Solution Approach

The proposed solution involves a two-step process: export and import. This approach ensures reusability and simplifies the migration process. It requires initializing two Firebase projects, one for the source and one for the target.

• Initialize two Firebase projects
  • One for the source project (with its service account and tenant ID)
  • One for the target project (with its service account and tenant ID)
• Export users from a tenant
  • Use the source tenant’s authForTenant(SOURCE_TENANT_ID)
  • List users in batches with listUsers()
  • Extract only the essential fields: uid, email, and customClaims
  • Store them in a users.json file for portability
• Import users into a tenant
  • Read the exported users.json
  • Use the target tenant’s authForTenant(TARGET_TENANT_ID)
  • For each user:
    • Create the user with the same UID and email
    • Reapply their customClaims to preserve roles/permissions
  • Log successes and errors (e.g., auth/email-already-exists).

Benefits of this approach

This method offers several advantages:

• Tenant-aware: Migration respects tenant isolation.
• Reusable: You can run export and import separately.
• Custom claims preserved: Ensures user roles and logic remain intact.
• Portable: users.json can be versioned and reviewed.

Things to Watch Out For

Keep these points in mind when implementing the migration:

• Passwords are not included.
• Tenant IDs must match your setup.
• Handle duplicate accounts.
• Reapply custom claims.
• Consider retry logic for large migrations.

Conclusion

Migrating Firebase users with tenants and custom claims is complex. This two-step process provides a repeatable workflow that respects tenant boundaries, preserves custom claims, and can be reused across environments.