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

Se hai eseguito l'upgrade a Firebase Authentication with Identity Platform, puoi aggiungere all'app l'autenticazione a più fattori (MFA) con password temporanea e monouso (TOTP).

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 generarlo, devono utilizzare un'app di autenticazione in grado di generare codici TOTP validi, come Google Authenticator.

Prima di iniziare

  1. Attiva almeno un provider che supporta l'MFA. Tieni presente che tutti i fornitori tranne i seguenti supportano l'MFA:

    • Autenticazione telefonica
    • Autenticazione anonima
    • Token di autenticazione personalizzati
    • Apple Game Center

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

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

    L'autenticazione a due fattori TOTP è supportata solo nell'SDK web modulare, nelle versioni v9.19.1 e superiori.

Attivare l'autenticazione a due fattori TOTP

Per attivare TOTP come secondo fattore, utilizza Admin SDK o chiama l'endpoint REST della configurazione del progetto.

Per utilizzare Admin SDK:

  1. Se non lo hai già fatto, installa l'SDK Node.js Firebase Admin.

    L'autenticazione a due fattori TOTP è supportata solo nelle versioni dell'SDK Node.js di Firebase Admin 11.6.0 e superiori.

  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 i TOTP, da zero a dieci. Il valore predefinito è 5.

      Le TOTP funzionano assicurando che quando due parti (il provare e lo strumento di convalida) generano OTP nella stessa finestra temporale (in genere di 30 secondi), generino la stessa password. Tuttavia, per tenere conto del sfasamento tra le parti e del tempo di risposta umana, puoi configurare il servizio TOTP in modo che accetti anche i codici TOTP da finestre adiacenti.

Per attivare l'autenticazione a due fattori TOTP utilizzando l'API REST, esegui quanto segue:

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 garantendo che, quando due parti (l'utente che verifica l'identità e l'utente che convalida) generano OTP all'interno della stessa finestra temporale (in genere 30 secondi), generino la stessa password. Tuttavia, per tenere conto del sfasamento tra le parti e del tempo di risposta umana, puoi configurare il servizio TOTP in modo che accetti anche i codici TOTP da finestre adiacenti.

Scegli un modello di registrazione

Puoi scegliere se la tua app richiede l'autenticazione a più fattori, nonché come e quando registrare gli utenti. Ecco alcuni pattern comuni:

  • Registrare il secondo fattore dell'utente nell'ambito 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, potresti utilizzare questo approccio.

  • Consente 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 il processo di registrazione, rendendo comunque disponibile l'autenticazione a più fattori per gli utenti sensibili alla sicurezza.

  • Richiedono l'aggiunta di un secondo fattore in modo incrementale quando l'utente vuole accedere a funzionalità con requisiti di sicurezza aumentati.

Iscrivere utenti a TOTP MFA

Dopo aver attivato 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 nuovamente 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 segreti 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 congenerateQrCodeUrl() e poi codificalo utilizzando la libreria di codici QR di tua scelta. Ad esempio:

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

    Indipendentemente dal fatto che tu mostri 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 proprio secret all'app di autenticazione, questa inizierà a generare TOTP.

  5. Chiedi all'utente di digitare il TOTP visualizzato nell'app di autenticazione e di usarlo 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);

Consentire l'accesso degli utenti con un secondo fattore

Per consentire agli utenti di eseguire l'accesso con TOTP MFA, 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 la verifica in due passaggi. (ad es. signInWithEmailAndPassword()). Se il metodo genera un auth/multi-factor-auth-required errore, avvia il flusso di verifica a due fattori 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 di autenticazione a due fattori della tua app deve prima chiedere all'utente di scegliere il secondo fattore che vuole utilizzare. Puoi ottenere un elenco di 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 il TOTP, chiedigli di digitare il TOTP visualizzato nell'app di autenticazione e di utilizzarlo 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 alla verifica in due passaggi TOTP

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

Se un utente ha eseguito la registrazione per più opzioni MFA e se annulla la registrazione all'opzione abilitata più di recente, riceve un auth/user-token-expired e viene disconnesso. L'utente deve accedere di nuovo e verificare le proprie 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