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 Auth | Equivalente Auris | Note |
|---|---|---|
| Email/Password Login | Hosted Login Pages | Flusso OAuth2 PKCE, UI branded per tenant |
| Social Provider (Google, Facebook, ecc.) | Social Login | 9 provider, stesso flusso OAuth2 |
| Phone Auth (SMS) | SMS OTP | Provider Twilio, 2FA e passwordless |
| Anonymous Auth | Non disponibile | Usa magic link per onboarding a bassa friction |
| Custom Claims | Custom JWT Claims | Per applicazione, 5 tipi di valore, configurabile dall’admin |
| Firebase Admin SDK | Management Client (@auris/js) | Client credentials M2M, CRUD utenti/ruoli/org |
| Security Rules | FGA (Fine-Grained Authorization) + RBAC | ReBAC stile Zanzibar, più potente delle Security Rules |
| Email Link Sign-In | Magic Links | Basato su token, supporto auto-signup |
| Multi-Factor Auth | Multi-Factor Auth | TOTP, SMS, WebAuthn (Firebase supporta solo SMS + TOTP) |
| Firebase UI | Hosted Login Pages | Completamente gestito, branding personalizzabile |
| User Management (Console) | Console Auris | Console admin completa con ruoli, permessi, sessioni |
| ID Token Verification | Verifica JWT (JWKS) | RS256 con endpoint JWKS, verifier @auris/js |
| Blocking Functions | Actions Engine | 6 trigger point, JS sandboxed, editor visuale |
Funzionalità che Auris Aggiunge Oltre Firebase
| Funzionalità | Descrizione |
|---|---|
| Enterprise SSO | Federazione SAML 2.0 + OIDC per IdP aziendali |
| SCIM 2.0 Provisioning | Sync utenti automatizzato con Okta, Azure AD, ecc. |
| Organizations B2B | Multi-org con ruoli membro e inviti |
| Fine-Grained Authorization (FGA) | Controllo accessi relationship-based stile Zanzibar |
| Roles & Permissions | RBAC tri-state con scoping per applicazione |
| Custom Domains | Pagine auth white-label sotto il tuo dominio |
| Log Streaming | Esporta log di audit su Datadog, Splunk, S3 |
| Webhooks | Notifiche eventi in tempo reale firmate HMAC |
| Rate Limiting | Rate limiting a livelli con header standard |
| Attack Protection | Regole 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:
- Importa gli utenti in Auris senza password (verranno creati come account senza password)
- Quando un utente tenta di effettuare il login su Auris e non ha password impostata, restituisce un flusso specifico
- La tua applicazione tenta di verificare la credenziale su Firebase usando l’Admin SDK
- Se la verifica Firebase ha successo, imposta la password dell’utente in Auris tramite l’Admin API
- 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)
- Importa gli utenti senza password
- Dopo l’importazione, attiva email di reset password per tutti gli utenti
- 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
- Apri la Console Auris e vai su Applicazioni poi Crea Applicazione
- Seleziona WEB come tipo di applicazione
- Inserisci il nome dell’applicazione
- Aggiungi i tuoi Callback URL
- Aggiungi le tue Origini Consentite
- 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/nextjsPassaggio 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:
- Vai su Applicazioni poi seleziona la tua app poi tab Custom Claims
- Aggiungi i claim:
rolecon tipo Attributo Utente mappato aroles[0].nameplancon tipo Statico valoreenterpriseorgIdcon tipo Attributo Utente mappato ametadata.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: editorScrivi 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:
| Settimana | Attività |
|---|---|
| 1 | Configura tenant Auris, crea applicazioni, configura provider social, esporta utenti Firebase |
| 2 | Importa utenti in Auris, implementa endpoint migrazione lazy password, configura modello FGA |
| 3 | Sostituisci SDK Firebase con SDK Auris nell’applicazione, testa tutti i flussi auth |
| 4 | Deployment in staging e QA, migra custom claim, configura webhook/log streaming |
| 5 | Deployment in produzione, monitora avanzamento migrazione lazy, inizia disattivazione Firebase |
| 6-8 | Monitora 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
- Login Ospitato (PKCE) — Implementare il flusso di login
- Custom JWT Claims — Sostituire i custom claim Firebase
- Autorizzazione Fine-Grained — Sostituire le Firebase Security Rules
- Social Login — Configurare i provider OAuth2
- Import/Export Utenti — Migrazione utenti in blocco
- Migrazione da Auth0 — Guida di migrazione alternativa