Move Firebase Auth users (including firebase-scrypt passwords) and social providers to Avnology ID.

Migrate from Firebase Auth

Firebase Auth stores passwords using a modified scrypt (firebase-scrypt) that requires the project-level signer key and salt separator to verify. This guide shows how to carry everything across intact.

Prerequisites

avnology CLI installed.
Admin API key in .env.
Firebase project owner or Authentication Admin role.
gcloud CLI + the Firebase CLI (firebase-tools).

Equivalent concepts

Firebase Auth	Avnology ID
Project	Organization
Authentication provider (Email/Password)	Password method
Authentication provider (Google / Apple / …)	Social provider (OIDC)
Anonymous user	Not supported — use a service account pattern instead
Custom claims	Token claim resolver
Blocking function	Webhook Hook
`admin.auth().createUser()`	`POST /v1/users`
`user.uid`	`external_id`
`email_verified`	`email_verified` (same semantics)

Export users from Firebase

firebase auth:export firebase_users.json \
  --format=JSON \
  --project=<your-project-id>

The export includes top-level hashing parameters (salt, saltSeparator, memoryCost, rounds) required to verify passwords later. Keep this file out of version control — it contains everything needed to check credentials.

A record looks like:

{
  "users": [
    {
      "localId": "firebase-user-1",
      "email": "[email protected]",
      "emailVerified": true,
      "displayName": "Margaret Hamilton",
      "photoUrl": "https://…",
      "passwordHash": "base64hash==",
      "salt": "perUserSalt==",

Import with the CLI

avnology migrate firebase-auth --import firebase_users.json --dry-run
avnology migrate firebase-auth --import firebase_users.json

The CLI:

Copies passwordHash + per-user salt into the identity's password record.
Attaches the project-level saltSeparator, memoryCost, rounds, and signer key as hash parameters.
Marks the hash algorithm as firebase-scrypt.
Sets external_id = <localId>.
Copies displayName → traits.name, photoUrl → traits.picture, phoneNumber → traits.phone_number, customAttributes → traits.custom_attributes.

Avnology's firebase-scrypt verifier requires the project signing key. If you rotate the key on Firebase after export, existing users cannot authenticate until you either re-export or ask them to reset their password.

Firebase Auth social IDPs (Google, Apple, Facebook, Twitter, GitHub, Microsoft) map to Avnology's social providers. Users linked via social sign-in on Firebase have a providerUserInfo[] array listing each federated identity — these are preserved as link-later records on Avnology. The next time the user signs in via the same provider, Avnology reconciles the identities by external_id.

OAuth client migration

Firebase Auth has implicit client configuration — you configure providers inside the Firebase console. On Avnology you register explicit OAuth 2.1 clients. For each app that currently uses Firebase Auth:

Register a new OAuth client in the Avnology dashboard under Developer → Applications.
Add the old Firebase Auth domain to Allowed Origins during the cutover window so tokens issued before cutover still validate.

Redirect URL mapping

Firebase URL	Avnology ID URL
`https://<project>.firebaseapp.com/__/auth/handler`	`https://<Domain id="api"/>/oauth2/auth`
`https://securetoken.google.com/<project>` (token issuer)	`https://<Domain id="api"/>`
`https://www.googleapis.com/identitytoolkit/v3/relyingparty/…`	`https://<Domain id="api"/>/v1/…`

Firebase's client SDK hard-codes its endpoints; you cannot keep the Firebase SDK and target Avnology. Swap to @avnology/sdk-typescript or the framework-specific wrapper.

Blocking functions → Hooks

Firebase Auth's beforeCreate / beforeSignIn blocking functions become Avnology webhook hooks subscribed to user.pre_create / session.pre_create. The payload fields map straightforwardly; port the function body into your own HTTP handler and subscribe it.

Cutover plan

Stage the migration in a non-production Firebase project first. Verify a password-backed login and a Google social login after import.
Deploy both Firebase Auth and Avnology side-by-side for 1 week. Your frontend can probe both (Firebase first, fall back to Avnology) to catch any missed users.
Cutover: switch the frontend to Avnology-only. Keep Firebase running for 30 days.
Delete the Firebase Auth user pool once audit logs are exported.

Migrate from Firebase Auth

On this page