Skip to Content

Migrazione da Firebase Auth

Firebase Authentication è una scelta popolare per iniziare rapidamente, ma man mano che le applicazioni crescono, i team spesso hanno bisogno di funzionalità enterprise che Firebase non offre: SSO enterprise (SAML/OIDC), provisioning SCIM, autorizzazione fine-grained, organizzazioni con multi-tenancy B2B, certificazioni di conformità e opzioni di deployment self-hosted. Auris fornisce tutto questo mantenendo la developer experience di Firebase Auth.

Questa guida illustra come esportare gli utenti da Firebase, gestire la transizione degli hash delle password, sostituire l’SDK Firebase con l’SDK Auris e migrare i custom claim e le security rules.

Mappatura delle Funzionalità

Funzionalità Firebase AuthEquivalente AurisNote
Email/Password LoginHosted Login PagesFlusso OAuth2 PKCE, UI branded per tenant
Social Provider (Google, Facebook, ecc.)Social Login9 provider, stesso flusso OAuth2
Phone Auth (SMS)SMS OTPProvider Twilio, 2FA e passwordless
Anonymous AuthNon disponibileUsa magic link per onboarding a bassa friction
Custom ClaimsCustom JWT ClaimsPer applicazione, 5 tipi di valore, configurabile dall’admin
Firebase Admin SDKManagement Client (@auris/js)Client credentials M2M, CRUD utenti/ruoli/org
Security RulesFGA (Fine-Grained Authorization) + RBACReBAC stile Zanzibar, più potente delle Security Rules
Email Link Sign-InMagic LinksBasato su token, supporto auto-signup
Multi-Factor AuthMulti-Factor AuthTOTP, SMS, WebAuthn (Firebase supporta solo SMS + TOTP)
Firebase UIHosted Login PagesCompletamente gestito, branding personalizzabile
User Management (Console)Console AurisConsole admin completa con ruoli, permessi, sessioni
ID Token VerificationVerifica JWT (JWKS)RS256 con endpoint JWKS, verifier @auris/js
Blocking FunctionsActions Engine6 trigger point, JS sandboxed, editor visuale

Funzionalità che Auris Aggiunge Oltre Firebase

FunzionalitàDescrizione
Enterprise SSOFederazione SAML 2.0 + OIDC per IdP aziendali
SCIM 2.0 ProvisioningSync utenti automatizzato con Okta, Azure AD, ecc.
Organizations B2BMulti-org con ruoli membro e inviti
Fine-Grained Authorization (FGA)Controllo accessi relationship-based stile Zanzibar
Roles & PermissionsRBAC tri-state con scoping per applicazione
Custom DomainsPagine auth white-label sotto il tuo dominio
Log StreamingEsporta log di audit su Datadog, Splunk, S3
WebhooksNotifiche eventi in tempo reale firmate HMAC
Rate LimitingRate limiting a livelli con header standard
Attack ProtectionRegole IP, lockout brute-force, CAPTCHA, rilevamento login sospetti

Passaggi della Migrazione

Passaggio 1: Esportare gli Utenti da Firebase

Usa Firebase Admin SDK per esportare tutti gli utenti:

// export-firebase-users.ts import admin from 'firebase-admin' import fs from 'fs' admin.initializeApp({ credential: admin.credential.cert('./service-account-key.json'), }) async function exportAllUsers() { const users = [] let nextPageToken do { const result = await admin.auth().listUsers(1000, nextPageToken) for (const user of result.users) { users.push({ uid: user.uid, email: user.email || '', emailVerified: user.emailVerified, displayName: user.displayName || '', phoneNumber: user.phoneNumber, disabled: user.disabled, customClaims: user.customClaims, passwordHash: user.passwordHash, passwordSalt: user.passwordSalt, providerData: user.providerData.map((p) => ({ providerId: p.providerId, uid: p.uid, })), createdAt: user.metadata.creationTime, }) } nextPageToken = result.pageToken console.log(`Esportati ${users.length} utenti...`) } while (nextPageToken) return users } exportAllUsers().then((users) => { fs.writeFileSync('firebase-users-export.json', JSON.stringify(users, null, 2)) console.log(`Totale: ${users.length} utenti esportati`) })

Firebase esporta gli hash delle password usando un algoritmo scrypt modificato (Firebase scrypt). Questi hash non possono essere verificati direttamente da Auris poiché Auris usa bcrypt. Dovrai gestire la migrazione delle password usando il pattern di migrazione lazy descritto di seguito.

Passaggio 2: Gestire la Migrazione degli Hash delle Password

Firebase usa una variante scrypt personalizzata per l’hashing delle password che non è compatibile con bcrypt usato da Auris. Ci sono due approcci:

Opzione A: Migrazione Lazy (Consigliata)

Il pattern di migrazione lazy rehash le password in modo trasparente man mano che gli utenti effettuano il login. Questo fornisce zero friction per gli utenti finali.

Come funziona:

  1. Importa gli utenti in Auris senza password (verranno creati come account senza password)
  2. Quando un utente tenta di effettuare il login su Auris e non ha password impostata, restituisce un flusso specifico
  3. La tua applicazione tenta di verificare la credenziale su Firebase usando l’Admin SDK
  4. Se la verifica Firebase ha successo, imposta la password dell’utente in Auris tramite l’Admin API
  5. Tutti i login successivi vanno direttamente tramite Auris
// Middleware per la migrazione lazy delle password async function lazyMigratePassword( email: string, password: string, aurisManagementToken: string ): Promise<boolean> { try { // Passaggio 1: Prova a fare login con Firebase const firebaseResponse = await fetch( `https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=${process.env.FIREBASE_API_KEY}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password, returnSecureToken: false }), } ) if (!firebaseResponse.ok) { return false // Credenziali non valide anche in Firebase } // Passaggio 2: Firebase ha verificato la password — impostala in Auris const userResponse = await fetch( `https://auth.tuazienda.com/api/users?email=${encodeURIComponent(email)}`, { headers: { Authorization: `Bearer ${aurisManagementToken}`, 'x-tenant': 'tuo-tenant-id', }, } ) const userData = await userResponse.json() const userId = userData.data?.[0]?.id if (!userId) return false // Passaggio 3: Imposta la password in Auris await fetch( `https://auth.tuazienda.com/api/users/${userId}/set-password`, { method: 'POST', headers: { Authorization: `Bearer ${aurisManagementToken}`, 'x-tenant': 'tuo-tenant-id', 'Content-Type': 'application/json', }, body: JSON.stringify({ password }), } ) console.log(`Password migrata per l'utente: ${email}`) return true } catch (error) { console.error(`Migrazione password fallita per ${email}:`, error) return false } }

Opzione B: Forza il Reset della Password (Più Semplice)

  1. Importa gli utenti senza password
  2. Dopo l’importazione, attiva email di reset password per tutti gli utenti
  3. Gli utenti impostano una nuova password al primo login

Passaggio 3: Importare gli Utenti in Auris

Trasforma l’esportazione Firebase nel formato di importazione Auris:

// transform-firebase-users.ts import fs from 'fs' const firebaseUsers = JSON.parse( fs.readFileSync('firebase-users-export.json', 'utf-8') ) const aurisUsers = firebaseUsers .filter((u) => u.email && !u.disabled) .map((user) => { const nameParts = (user.displayName || '').split(' ') return { email: user.email, firstName: nameParts[0] || '', lastName: nameParts.slice(1).join(' ') || '', emailVerified: user.emailVerified, } }) fs.writeFileSync('auris-import.json', JSON.stringify(aurisUsers, null, 2)) console.log(`Trasformati ${aurisUsers.length} utenti per l'importazione`)

Carica su Auris:

curl -X POST https://auth.tuazienda.com/api/users/import \ -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \ -H "x-tenant: tuo-tenant-id" \ -F "[email protected]" \ -F "format=json"

Passaggio 4: Creare un’Applicazione nella Console Auris

  1. Apri la Console Auris e vai su Applicazioni poi Crea Applicazione
  2. Seleziona WEB come tipo di applicazione
  3. Inserisci il nome dell’applicazione
  4. Aggiungi i tuoi Callback URL
  5. Aggiungi le tue Origini Consentite
  6. Salva e annota il Client ID

Passaggio 5: Sostituire l’SDK Firebase con l’SDK Auris

# Rimuovi Firebase npm uninstall firebase firebase-admin # Installa Auris npm install @auris/js @auris/react # Per Next.js: npm install @auris/nextjs

Passaggio 6: Aggiornare il Codice dell’Applicazione

Inizializzazione:

// PRIMA (Firebase) import { initializeApp } from 'firebase/app' import { getAuth } from 'firebase/auth' const app = initializeApp({ apiKey: 'AIza...', authDomain: 'myapp.firebaseapp.com' }) const auth = getAuth(app) // DOPO (Auris) import { AurisClient } from '@auris/js' const auris = new AurisClient({ domain: 'auth.tuazienda.com', clientId: 'tuo-client-id', redirectUri: 'http://localhost:3000/callback', autoRefresh: true, })

Autenticazione (React):

// PRIMA (Firebase) import { useAuthState } from 'react-firebase-hooks/auth' const [user, loading] = useAuthState(auth) // DOPO (Auris) import { useAuris } from '@auris/react' const { user, isLoading, isAuthenticated, loginWithRedirect, logout } = useAuris()

Ottenere il Token per le Chiamate API:

// PRIMA (Firebase) const token = await auth.currentUser?.getIdToken() // DOPO (Auris) const token = await auris.getAccessToken() // Il resto del codice rimane invariato const response = await fetch('/api/protected', { headers: { Authorization: `Bearer ${token}` }, })

Verifica Token lato Server:

// PRIMA (Firebase Admin SDK) import admin from 'firebase-admin' async function verifyToken(token: string) { const decoded = await admin.auth().verifyIdToken(token) return decoded } // DOPO (Auris — usando JWKS) import { verifyJwt } from '@auris/js/jwt-verify' async function verifyToken(token: string) { const decoded = await verifyJwt(token, { jwksUrl: 'https://auth.tuazienda.com/.well-known/jwks.json', }) return decoded } // Oppure usando l'helper Next.js: import { getSession } from '@auris/nextjs/server' export async function GET(req: Request) { const session = await getSession() if (!session) { return Response.json({ error: 'Non autorizzato' }, { status: 401 }) } return Response.json({ userId: session.user.id }) }

Social Login (Google):

// PRIMA (Firebase) import { signInWithPopup, GoogleAuthProvider } from 'firebase/auth' const provider = new GoogleAuthProvider() const result = await signInWithPopup(auth, provider) // DOPO (Auris) // Il social login è gestito dalla Hosted Login page — nessuna modifica al codice. // Configura Google come provider social in Console → Autenticazione → Social Login. // Gli utenti vedono automaticamente il pulsante Google sulla pagina di login ospitata. // Per andare direttamente a Google: await auris.loginWithRedirect({ connection: 'google' })

Passaggio 7: Migrare i Custom Claim

I custom claim di Firebase vengono tipicamente impostati tramite l’Admin SDK:

// PRIMA (Firebase) await admin.auth().setCustomUserClaims(uid, { role: 'admin', plan: 'enterprise', orgId: 'org_123', })

In Auris, i custom claim sono configurati per applicazione nella Console:

  1. Vai su Applicazioni poi seleziona la tua app poi tab Custom Claims
  2. Aggiungi i claim:
    • role con tipo Attributo Utente mappato a roles[0].name
    • plan con tipo Statico valore enterprise
    • orgId con tipo Attributo Utente mappato a metadata.orgId

Vedi la guida Custom JWT Claims per il riferimento completo.

Passaggio 8: Migrare le Security Rules verso FGA

Le Firebase Security Rules sono regole di controllo degli accessi dichiarative legate ai percorsi Firestore o Realtime Database. Auris usa Fine-Grained Authorization (FGA) basato sul modello Zanzibar, che è più potente e disaccoppiato dal layer dati.

Firebase Security Rules di esempio:

rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /documents/{docId} { allow read: if request.auth != null && (resource.data.ownerId == request.auth.uid || request.auth.uid in resource.data.viewers); allow write: if request.auth != null && resource.data.ownerId == request.auth.uid; } } }

Modello FGA Auris equivalente:

model schema 1.1 type user type document relations define owner: [user] define viewer: [user] or owner define editor: [user] or owner define can_read: viewer define can_write: editor

Scrivi tuple di relazione per rappresentare i dati:

# Concedi la proprietà curl -X POST https://auth.tuazienda.com/api/fga/tuples \ -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \ -H "x-tenant: tuo-tenant-id" \ -H "Content-Type: application/json" \ -d '{ "objectType": "document", "objectId": "doc_123", "relation": "owner", "subjectType": "user", "subjectId": "usr_abc" }'

Controlla l’accesso nella tua applicazione:

import { AurisClient } from '@auris/js' const result = await auris.fga.check({ objectType: 'document', objectId: 'doc_123', relation: 'can_read', subjectType: 'user', subjectId: 'usr_abc', }) if (result.allowed) { // L'utente può leggere il documento }

Vedi la guida Autorizzazione Fine-Grained per il riferimento FGA completo.

Timeline di Migrazione

Una migrazione tipica da Firebase ad Auris segue questa timeline:

SettimanaAttività
1Configura tenant Auris, crea applicazioni, configura provider social, esporta utenti Firebase
2Importa utenti in Auris, implementa endpoint migrazione lazy password, configura modello FGA
3Sostituisci SDK Firebase con SDK Auris nell’applicazione, testa tutti i flussi auth
4Deployment in staging e QA, migra custom claim, configura webhook/log streaming
5Deployment in produzione, monitora avanzamento migrazione lazy, inizia disattivazione Firebase
6-8Monitora tasso di completamento migrazione, invia reset password agli utenti non migrati
8+Disattiva progetto Firebase

Checklist Post-Migrazione

  • Tutti gli utenti riescono ad accedere (email/password, social, telefono)
  • La migrazione lazy delle password funziona (controlla i log di audit Auris)
  • I custom claim appaiono negli access token
  • I controlli di autorizzazione FGA restituiscono risultati corretti
  • La verifica token lato server usa JWKS Auris
  • I provider di login social (Google, Facebook, ecc.) sono configurati
  • Gli eventi webhook vengono consegnati
  • L’SDK Firebase è completamente rimosso dal codebase
  • I riferimenti all’emulatore Firebase Auth sono rimossi dai test
  • La fatturazione del progetto Firebase è ridotta o annullata

Mantieni il progetto Firebase attivo durante il periodo di migrazione lazy. Monitora la percentuale di utenti che hanno migrato le loro password controllando i log di audit Auris per gli eventi user.password_changed. Una volta che la migrazione raggiunge il 95%+ degli utenti attivi, invia un’email di reset password agli utenti rimanenti e pianifica la disattivazione di Firebase.

Guide Correlate