Aggiungi l'autenticazione a più fattori TOTP alla tua app per Android

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 la 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 la MFA. Tieni presente che tutti i provider tranne i seguenti supportano la 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. La 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 già fatto, installa l' SDK Firebase per Android.

    La MFA con TOTP è supportata solo nella versione 22.1.0 e successive dell'SDK Android.

Abilitare la MFA con 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 già fatto, installa l' SDK Firebase Admin Node.js.

    La MFA con 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 dimostratore e il validatore) generano OTP nella stessa finestra temporale (in genere di 30 secondi long), 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 la MFA con 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 dimostratore e il validatore) generano OTP nella stessa finestra temporale (in genere di 30 secondi long), 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, nonché 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.

  • Offri la possibilità 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 alla MFA con TOTP

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

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

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

    // Generate a TOTP secret.
Firebase.auth.currentUser.multiFactor.session
    .addOnSuccessListener { multiFactorSession ->
        TotpMultiFactorGenerator.generateSecret(multiFactorSession)
            .addOnSuccessListener { totpSecret ->
                // Display the secret to the user and prompt them to
                // enter it into their authenticator app. (See the next
                // step.)
            }
    }

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

    // Display this key:
val secret = totpSecret.sharedSecretKey

    Oltre a visualizzare la chiave secret, puoi provare ad aggiungerla automaticamente all'app di autenticazione predefinita del dispositivo. Per farlo, genera un URI della chiave compatibile con Google Authenticator, e passalo a openInOtpApp():

    val qrCodeUri = totpSecret.generateQrCodeUrl(
    currentUser.email ?: "default account",
    "Your App Name")
totpSecret.openInOtpApp(qrCodeUri)

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

  4. Chiedi all'utente di digitare la TOTP visualizzata dall'app di autenticazione e di utilizzarla per completare la registrazione alla MFA:

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

// Finalize the enrollment.
val multiFactorAssertion = TotpMultiFactorGenerator
    .getAssertionForEnrollment(totpSecret, verificationCode)
Firebase.auth.currentUser.multiFactor.enroll(multiFactorAssertion, "TOTP")
    .addOnSuccessListener {
        // Enrollment complete.
    }

Accedere degli utenti con un secondo fattore

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

  1. Chiama uno dei metodi signInWith- come faresti se non utilizzassi la MFA. (Ad esempio, signInWithEmailAndPassword().) Se il metodo genera un'eccezione FirebaseAuthMultiFactorException, avvia il flusso MFA della tua app.

    Firebase.auth.signInWithEmailAndPassword(email, password)
    .addOnSuccessListener { result ->
        // 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.)

        // ...
    }
    .addOnFailureListener { exception ->
        when (exception) {
            is FirebaseAuthMultiFactorException -> {
                // Initiate your second factor sign-in flow. (See next step.)
                // ...
            }
        }
    }

  2. 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:

    val enrolledFactors = exception.resolver.hints.map { it.displayName }

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

    when (exception.resolver.hints[selectedIndex].factorId) {
    TotpMultiFactorGenerator.FACTOR_ID -> {
        val otpFromAuthenticator = // OTP typed by the user.
        val assertion = TotpMultiFactorGenerator.getAssertionForSignIn(
            exception.resolver.hints[selectedIndex].uid,
            otpFromAuthenticator
        )
        exception.resolver.resolveSignIn(assertion)
            .addOnSuccessListener { result ->
                // Successfully signed in!
            }
            .addOnFailureListener { resolveError ->
                // Invalid or expired OTP.
            }
    }
    PhoneMultiFactorGenerator.FACTOR_ID -> {
        // Handle SMS second factor.
    }
}

Annullare la registrazione alla MFA con TOTP

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

Se un utente ha eseguito la registrazione a più opzioni MFA e 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 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:

Firebase.auth.currentUser.multiFactor.unenroll(mfaEnrollmentId)
    .addOnSuccessListener {
        // Second factor unenrolled.
    }
    .addOnFailureListener { exception ->
        when (exception) {
            is FirebaseAuthInvalidUserException -> {
                // Second factor unenrolled. 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.
                val credential = EmailAuthProvider.getCredential(email, password)
                currentUser.reauthenticate(credential)
                    .addOnSuccessListener { 
                        // Success!
                    }
                    .addOnFailureListener { 
                        // Bad email address and password combination.
                    }
            }
        }
    }

Passaggi successivi