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](/migrate-from-firebase) overview.

## Prerequisites

- An Authdog [tenant, project, and environment](/docs/concepts/multi-tenancy) 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

1. **Export** — dump users, providers, claims, and hash parameters from Firebase.
2. **Map** — translate Firebase fields into Authdog users, metadata, roles, and organizations.
3. **Import** — load users into an isolated Authdog environment and validate.
4. **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](/docs/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](/docs/integrations) |
| Security Rules / Admin checks | `request.auth.token` claim reads | Backend session validation + [authorization](/docs/permissions) |

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`, `photoURL`
- `disabled`
- `providerData[]` (`providerId`, provider `uid`, 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](/docs/permissions) assignment |
| `premium` / plan flags | User metadata or billing entitlements |
| `tenantId` / org id | [Organization](/docs/concepts/organizations) membership |
| Fine-grained resource ACLs | Revisit [authorization models](/docs/concepts/authorization) (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:

1. Enable password, social, MFA, and any enterprise SSO you need. See [Sign up & sign in](/docs/authentication).
2. Recreate Google, Apple, Microsoft, and other providers with Authdog redirect URIs. Keep Firebase OAuth clients active until cutover.
3. 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).
4. Configure the hosted [Account portal](/docs/account-portal) or [components](/docs/components) for the clients you will move first.

## 5. Import users

Load users via console bulk import or the REST [Directory API](/docs/api):

1. Upsert each user with email, profile, and verification state.
2. Set Firebase `uid` as the external identifier.
3. Link provider identities from `providerData`.
4. Apply role / organization mappings derived from custom claims.
5. Suspend users that were disabled in Firebase.
6. 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 `uid` still resolve via the external identifier

## 6. Update clients and backends

Firebase ID tokens and Authdog sessions are not interchangeable. For each client:

1. Replace Firebase Auth SDK sign-in with Authdog ([quickstarts](/docs/quickstarts)).
2. Configure the Authdog environment **public key** (`pk_...`).
3. Validate Authdog sessions on APIs instead of `verifyIdToken`. See [Backend requests](/docs/backend).
4. Rewrite Security Rules or Cloud Functions that read `request.auth.token.*` custom claims to use Authdog-validated identity plus your authorization model.
5. 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

1. Rehearse full export → import → sign-in in staging.
2. Move internal apps and a small production cohort.
3. Shift web clients, then mobile, then long-lived backend jobs.
4. Monitor auth failure rates, support volume, and data-join mismatches on `uid`.
5. Disable new Firebase sign-ups when Authdog is authoritative for a cohort.
6. After soak, disable Firebase providers, revoke old OAuth secrets, and decommission Firebase Authentication when no clients remain.

## Acceptance checklist

- [ ] Every production `uid` retained 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 `verifyIdToken` for 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.

## Related

- [Migrate from Auth0](/docs/guides/migrate-from-auth0)
- [Migrate from WorkOS](/docs/guides/migrate-from-workos)
- [Migrate from Supabase](/docs/guides/migrate-from-supabase)
- [Users](/docs/users)
- [Permissions](/docs/permissions)
- [Deployments](/docs/deployments)
- [Migrate from Firebase (overview)](/migrate-from-firebase)