Aggiungi l'autenticazione a più fattori TOTP alla tua applicazione web

Se hai eseguito l'upgrade a Firebase Authentication with Identity Platform, puoi aggiungere l'autenticazione a più fattori (MFA) con password uniche basate sul tempo (TOTP) alla tua app.

Firebase Authentication with Identity Platform ti consente di utilizzare una TOTP come fattore aggiuntivo per l'MFA. Quando abiliti questa funzionalità, gli utenti che tentano di accedere alla tua app vedono una richiesta di una TOTP. Per generarla, devono utilizzare un'app di autenticazione in grado di generare codici TOTP validi, come Google Authenticator.

Prima di iniziare

  1. Abilita almeno un provider che supporti l'MFA. Tieni presente che tutti i provider tranne i seguenti supportano l'MFA:

    • Autenticazione tramite telefono
    • Autenticazione anonima
    • Token di autenticazione personalizzati
    • Game Center di Apple

  2. Assicurati che la tua app verifichi gli indirizzi email degli utenti. L'MFA richiede la verifica dell'indirizzo email. In questo modo, gli utenti malintenzionati non possono registrarsi a un servizio con un indirizzo email di cui non sono proprietari e poi bloccare il proprietario effettivo dell'indirizzo email aggiungendo un secondo fattore.

  3. Se non l'hai ancora fatto, installa l' SDK Firebase JavaScript.

    L'MFA TOTP è supportata solo nell'SDK web modulare, versioni v9.19.1 e successive.

Abilitare l'MFA TOTP

Per abilitare la TOTP come secondo fattore, utilizza il Admin SDK o chiama l'endpoint REST di configurazione del progetto.

Per utilizzare Admin SDK:

  1. Se non l'hai ancora fatto, installa l' SDK Firebase Admin Node.js.

    L'MFA TOTP è supportata solo nelle versioni 11.6.0 e successive dell'SDK Firebase Admin Node.js.

  2. Esegui questo comando:

    import { getAuth } from 'firebase-admin/auth';

getAuth().projectConfigManager().updateProjectConfig(
{
      multiFactorConfig: {
          providerConfigs: [{
              state: "ENABLED",
              totpProviderConfig: {
                  adjacentIntervals: NUM_ADJ_INTERVALS
              }
          }]
      }
})

    Sostituisci quanto segue:

    • NUM_ADJ_INTERVALS: il numero di intervalli di finestre temporali adiacenti da cui accettare le TOTP, da zero a dieci. Il valore predefinito è cinque.

      Le TOTP funzionano assicurandosi che quando due parti (il prover e il validator) generano OTP nella stessa finestra temporale (in genere di 30 secondi), generino la stessa password. Tuttavia, per tenere conto della deriva dell'orologio tra le parti e del tempo di risposta umano, puoi configurare il servizio TOTP in modo che accetti anche le TOTP dalle finestre adiacenti.

Per abilitare l'MFA TOTP utilizzando l'API REST, esegui questo comando:

curl -X PATCH "https://identitytoolkit.googleapis.com/admin/v2/projects/PROJECT_ID/config?updateMask=mfa" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -d \
    '{
        "mfa": {
          "providerConfigs": [{
            "state": "ENABLED",
            "totpProviderConfig": {
              "adjacentIntervals": NUM_ADJ_INTERVALS
            }
          }]
       }
    }'

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.

  • NUM_ADJ_INTERVALS: il numero di intervalli di finestre temporali, da zero a dieci. Il valore predefinito è cinque.

    Le TOTP funzionano assicurandosi che quando due parti (il prover e il validator) generano OTP nella stessa finestra temporale (in genere di 30 secondi), generino la stessa password. Tuttavia, per tenere conto della deriva dell'orologio tra le parti e del tempo di risposta umano, puoi configurare il servizio TOTP in modo che accetti anche le TOTP dalle finestre adiacenti.

Scegliere un pattern di registrazione

Puoi scegliere se la tua app richiede l'autenticazione a più fattori e come e quando registrare gli utenti. Alcuni pattern comuni includono:

  • Registra il secondo fattore dell'utente come parte della registrazione. Utilizza questo metodo se la tua app richiede l'autenticazione a più fattori per tutti gli utenti.

  • Offri un'opzione ignorabile per registrare un secondo fattore durante la registrazione. Se vuoi incoraggiare, ma non richiedere, l'autenticazione a più fattori nella tua app, puoi utilizzare questo approccio.

  • Consenti di aggiungere un secondo fattore dalla pagina di gestione dell'account o del profilo dell'utente, anziché dalla schermata di registrazione. In questo modo si riduce al minimo l'attrito durante la procedura di registrazione, pur rendendo disponibile l'autenticazione a più fattori per gli utenti sensibili alla sicurezza.

  • Richiedi l'aggiunta di un secondo fattore in modo incrementale quando l'utente vuole accedere a funzionalità con requisiti di sicurezza più elevati.

Registrare gli utenti all'MFA TOTP

Dopo aver abilitato l'MFA TOTP come secondo fattore per la tua app, implementa la logica lato client per registrare gli utenti all'MFA TOTP:

  1. Importa le classi e le funzioni MFA richieste:

    import {
  multiFactor,
  TotpMultiFactorGenerator,
  TotpSecret,
  getAuth,
} from "firebase/auth";

  2. Esegui di nuovo l'autenticazione dell'utente.

  3. Genera un secret TOTP per l'utente autenticato:

    // Generate a TOTP secret.
const multiFactorSession = await multiFactor(currentUser).getSession();
const totpSecret = await TotpMultiFactorGenerator.generateSecret(
  multiFactorSession
);

  4. Mostra il secret all'utente e chiedigli di inserirlo nell'app di autenticazione.

    Con molte app di autenticazione, gli utenti possono aggiungere rapidamente nuovi secret TOTP scansionando un codice QR che rappresenta un URI chiave compatibile con Google Authenticator. Per generare un codice QR a questo scopo, genera l'URI con generateQrCodeUrl() e poi codificalo utilizzando la libreria di codici QR che preferisci. Ad esempio:

    const totpUri = totpSecret.generateQrCodeUrl(
    currentUser.email,
    "Your App's Name"
);
await QRExampleLib.toCanvas(totpUri, qrElement);

    Indipendentemente dal fatto che tu mostri o meno un codice QR, mostra sempre la chiave segreta per supportare le app di autenticazione che non possono leggere i codici QR:

    // Also display this key:
const secret = totpSecret.secretKey;

    Dopo che l'utente ha aggiunto il secret all'app di autenticazione, questa inizierà a generare TOTP.

  5. Chiedi all'utente di digitare la TOTP visualizzata nell'app di autenticazione e di utilizzarla per completare la registrazione all'MFA:

    // Ask the user for a verification code from the authenticator app.
const verificationCode = // Code from user input.

// Finalize the enrollment.
const multiFactorAssertion = TotpMultiFactorGenerator.assertionForEnrollment(
  totpSecret,
  verificationCode
);
await multiFactor(currentUser).enroll(multiFactorAssertion, mfaDisplayName);

Accedere con un secondo fattore

Per consentire agli utenti di accedere con l'MFA TOTP, utilizza il seguente codice:

  1. Importa le classi e le funzioni MFA richieste:

    import {
    getAuth,
    getMultiFactorResolver,
    TotpMultiFactorGenerator,
} from "firebase/auth";

  2. Chiama uno dei metodi signInWith- come faresti se non utilizzassi l'MFA. (Ad esempio, signInWithEmailAndPassword().) Se il metodo genera un errore auth/multi-factor-auth-required, avvia il flusso MFA della tua app.

    try {
    const userCredential = await signInWithEmailAndPassword(
        getAuth(),
        email,
        password
    );
    // If the user is not enrolled with a second factor and provided valid
    // credentials, sign-in succeeds.

    // (If your app requires MFA, this could be considered an error
    // condition, which you would resolve by forcing the user to enroll a
    // second factor.)

    // ...
} catch (error) {
    switch (error.code) {
        case "auth/multi-factor-auth-required":
            // Initiate your second factor sign-in flow. (See next step.)
            // ...
            break;
        case ...:  // Handle other errors, such as wrong passwords.
            break;
    }
}

  3. Il flusso MFA della tua app deve innanzitutto chiedere all'utente di scegliere il secondo fattore che vuole utilizzare. Puoi ottenere un elenco dei secondi fattori supportati esaminando la proprietà hints di un'istanza MultiFactorResolver:

    const mfaResolver = getMultiFactorResolver(getAuth(), error);
const enrolledFactors = mfaResolver.hints.map(info => info.displayName);

  4. Se l'utente sceglie di utilizzare la TOTP, chiedigli di digitare la TOTP visualizzata nell'app di autenticazione e di utilizzarla per accedere:

    switch (mfaResolver.hints[selectedIndex].factorId) {
    case TotpMultiFactorGenerator.FACTOR_ID:
        const otpFromAuthenticator = // OTP typed by the user.
        const multiFactorAssertion =
            TotpMultiFactorGenerator.assertionForSignIn(
                mfaResolver.hints[selectedIndex].uid,
                otpFromAuthenticator
            );
        try {
            const userCredential = await mfaResolver.resolveSignIn(
                multiFactorAssertion
            );
            // Successfully signed in!
        } catch (error) {
            // Invalid or expired OTP.
        }
        break;
    case PhoneMultiFactorGenerator.FACTOR_ID:
        // Handle SMS second factor.
        break;
    default:
        // Unsupported second factor?
        break;
}

Annullare la registrazione all'MFA TOTP

Questa sezione descrive come gestire l'annullamento della registrazione di un utente all'MFA TOTP.

Se un utente ha eseguito la registrazione a più opzioni MFA e annulla la registrazione all'opzione abilitata più di recente, riceve un errore auth/user-token-expired e viene disconnesso. L'utente deve accedere di nuovo e verificare le credenziali esistenti, ad esempio un indirizzo email e una password.

Per annullare la registrazione dell'utente, gestire l'errore e attivare la riautenticazione, utilizza il seguente codice:

import {
    EmailAuthProvider,
    TotpMultiFactorGenerator,
    getAuth,
    multiFactor,
    reauthenticateWithCredential,
} from "firebase/auth";

try {
    // Unenroll from TOTP MFA.
    await multiFactor(currentUser).unenroll(mfaEnrollmentId);
} catch  (error) {
    if (error.code === 'auth/user-token-expired') {
        // If the user was signed out, re-authenticate them.

        // For example, if they signed in with a password, prompt them to
        // provide it again, then call `reauthenticateWithCredential()` as shown
        // below.

        const credential = EmailAuthProvider.credential(email, password);
        await reauthenticateWithCredential(
            currentUser,
            credential
        );
    }
}

Passaggi successivi