Move Firebase Authentication users to Authdog while keeping sign-in continuity and the downstream data joins keyed on Firebase uid values. This guide covers export, password hashes, custom claims, provider remapping, and staged cutover. For product positioning, see the Migrate from Firebase overview.
Prerequisites
- An Authdog tenant, project, and environment for rehearsal (staging first).
- Firebase project owner or Admin SDK access to Authentication.
- Inventory of every client that verifies Firebase ID tokens (web, mobile, Cloud Functions, Security Rules, and third-party backends).
- List of sign-in providers enabled in Firebase (email/password, Google, Apple, phone, anonymous, custom tokens, and so on).
Migration shape
- Export — dump users, providers, claims, and hash parameters from Firebase.
- Map — translate Firebase fields into Authdog users, metadata, roles, and organizations.
- Import — load users into an isolated Authdog environment and validate.
- Cut over — move clients in cohorts, then stop writing to Firebase Authentication.
Keep Firebase serving production until Authdog acceptance checks pass.
1. Inventory Firebase Authentication
Capture configuration your apps depend on:
| Firebase concept | What to capture | Authdog target |
|---|---|---|
| Users | uid, email, phone, display name, photo, disabled, emailVerified |
Users |
| Provider data | providerId, uid, email per linked provider |
Linked identities / connections |
| Custom claims | Role flags, tenant IDs, entitlements | Roles, permissions, org membership, or metadata |
| Password hashes | Algorithm, base64 hash, salt, rounds / memory params | Password import or progressive migration |
| Authorized domains / OAuth clients | Google, Apple, and other provider credentials | Integrations |
| Security Rules / Admin checks | request.auth.token claim reads |
Backend session validation + authorization |
Anonymous users and custom-token-only users need an explicit product decision: import as normal users, convert on next signed-in session, or drop.
2. Export users with the Admin SDK
Use the Firebase Admin Auth API (listUsers / bulk export) so each record includes provider data and metadata. For each user retain:
- Firebase
uid(required external identifier for data joins) - Email,
emailVerified, phone number displayName,photoURLdisabledproviderData[](providerId, provideruid, email)- Custom claims
tokensValidAfterTime/ revocation signals if you use them- Password hash and algorithm parameters when available
Firebase password hash export requires the hash parameters from the Firebase console (or support) — capture algorithm, base64 signer key, salt separator, rounds, and memory cost before you rely on hash import. Without those parameters, plan progressive migration or password reset instead.
Store the Firebase uid as the Authdog external identifier so Firestore, Realtime Database, and your own tables that key on uid keep resolving.
Password strategy
- Hash import — when you have Firebase scrypt (or other supported) hashes plus parameters, import them so existing passwords keep working.
- Progressive migration — verify the password against Firebase on next login, then set the credential in Authdog and stop calling Firebase for that user.
- Reset / passwordless — move cohorts to magic link or forced reset when hashes cannot be exported (common for some provider-only accounts).
Never ship raw credentials through logs or client apps. Encrypt export artifacts and delete them after cutover.
3. Translate custom claims and tenancy
Firebase custom claims often encode authorization. Map them deliberately:
| Typical Firebase claim | Suggested Authdog mapping |
|---|---|
admin: true / role string |
RBAC role assignment |
premium / plan flags |
User metadata or billing entitlements |
tenantId / org id |
Organization membership |
| Fine-grained resource ACLs | Revisit authorization models (RBAC, ABAC, or FGA) |
Do not blindly copy claim JSON into tokens. Prefer first-class roles and organization membership so Authdog can enforce access server-side.
If you used Firebase multi-tenancy (Identity Platform tenants), map each Firebase tenant to the right Authdog project/environment or organization model before import — user stores are isolated per Authdog environment.
4. Recreate providers in Authdog
In the target Authdog environment:
- Enable password, social, MFA, and any enterprise SSO you need. See Sign up & sign in.
- Recreate Google, Apple, Microsoft, and other providers with Authdog redirect URIs. Keep Firebase OAuth clients active until cutover.
- Decide how phone-auth and anonymous users will sign in after migration (Authdog passwordless email, social-only, or a supported phone path if available in your plan).
- Configure the hosted Account portal or components for the clients you will move first.
5. Import users
Load users via console bulk import or the REST Directory API:
- Upsert each user with email, profile, and verification state.
- Set Firebase
uidas the external identifier. - Link provider identities from
providerData. - Apply role / organization mappings derived from custom claims.
- Suspend users that were disabled in Firebase.
- Import password hashes when parameters are compatible; otherwise mark users for progressive migration.
Validate on staging:
- Spot-check social login for linked providers
- Spot-check password login for hash-imported users
- Confirm downstream reads that join on Firebase
uidstill resolve via the external identifier
6. Update clients and backends
Firebase ID tokens and Authdog sessions are not interchangeable. For each client:
- Replace Firebase Auth SDK sign-in with Authdog (quickstarts).
- Configure the Authdog environment public key (
pk_...). - Validate Authdog sessions on APIs instead of
verifyIdToken. See Backend requests. - Rewrite Security Rules or Cloud Functions that read
request.auth.token.*custom claims to use Authdog-validated identity plus your authorization model. - Update mobile apps in staged releases — store reviews and install lag mean mobile cohorts often trail web.
During transition, a temporary backend adapter may accept Firebase ID tokens or Authdog sessions. Instrument both paths and remove the Firebase path per cohort.
7. Cut over in stages
- Rehearse full export → import → sign-in in staging.
- Move internal apps and a small production cohort.
- Shift web clients, then mobile, then long-lived backend jobs.
- Monitor auth failure rates, support volume, and data-join mismatches on
uid. - Disable new Firebase sign-ups when Authdog is authoritative for a cohort.
- After soak, disable Firebase providers, revoke old OAuth secrets, and decommission Firebase Authentication when no clients remain.
Acceptance checklist
- Every production
uidretained as an Authdog external identifier. - Password hash parameters captured before export (or progressive migration tested).
- Custom claims translated to roles, permissions, org membership, or metadata.
- Google / Apple / other providers succeed against Authdog redirect URIs.
- Backends no longer require Firebase
verifyIdTokenfor migrated clients. - Security Rules or equivalent checks updated for the new session model.
- Disabled Firebase users remain suspended in Authdog.
- Firebase credentials revoked after the soak period.