Menambahkan autentikasi multi-faktor ke aplikasi web

Jika telah mengupgrade ke Firebase Authentication dengan Identity Platform, Anda dapat menambahkan autentikasi multi-faktor SMS ke aplikasi web.

Autentikasi multi-faktor meningkatkan keamanan aplikasi Anda. Meskipun penyerang sering membobol sandi dan akun media sosial, menyadap pesan teks lebih sulit dilakukan.

Sebelum memulai

  1. Aktifkan minimal satu penyedia yang mendukung autentikasi multi-faktor. Setiap penyedia mendukung MFA, kecuali autentikasi dengan ponsel, autentikasi anonim, dan Apple Game Center.

  2. Pastikan aplikasi Anda memverifikasi email pengguna. MFA memerlukan verifikasi email. Tindakan ini mencegah pelaku kejahatan mendaftar ke layanan dengan email yang bukan miliknya, lalu mengunci pemilik sebenarnya dari akunnya dengan menambahkan faktor kedua.

Menggunakan multi-tenancy

Jika Anda mengaktifkan autentikasi multi-faktor untuk digunakan di lingkungan multi-tenant, pastikan untuk menyelesaikan langkah-langkah berikut (selain petunjuk lainnya dalam dokumen ini):

  1. Di GCP Console, pilih tenant yang ingin Anda ajak bekerja sama.

  2. Dalam kode Anda, tetapkan kolom tenantId pada instance Auth ke ID tenant Anda. Contoh:

    API modular web 

    import { getAuth } from "firebase/auth";

const auth = getAuth(app);
auth.tenantId = "myTenantId1";

    API dengan namespace web 

    firebase.auth().tenantId = 'myTenantId1';

Mengaktifkan autentikasi multi-faktor

  1. Buka halaman Authentication > Sign-in method di Firebase console.

  2. Di bagian Advanced, aktifkan SMS Multi-factor Authentication.

    Anda juga harus memasukkan nomor telepon yang akan digunakan untuk menguji aplikasi. Meskipun opsional, mendaftarkan nomor telepon pengujian sangat direkomendasikan untuk menghindari throttling selama tahap pengembangan.

  3. Jika Anda belum memberikan otorisasi pada domain aplikasi, tambahkan domain tersebut ke daftar yang diizinkan di halaman Authentication > Settings di Firebase console.

Memilih pola pendaftaran

Anda dapat memilih apakah aplikasi memerlukan autentikasi multi-faktor atau tidak, serta cara dan waktu untuk mendaftarkan pengguna. Beberapa pola yang umum antara lain:

  • Mendaftarkan faktor kedua pengguna sebagai bagian dari pendaftaran. Gunakan metode ini jika aplikasi Anda memerlukan autentikasi multi-faktor untuk semua pengguna.

  • Menawarkan opsi yang dapat dilewati untuk mendaftarkan faktor kedua selama pendaftaran. Aplikasi yang ingin mendukung, tetapi tidak memerlukan, autentikasi multi-faktor dapat memilih pendekatan ini.

  • Memungkinkan untuk menambahkan faktor kedua dari halaman pengelolaan akun atau profil pengguna, bukan dari layar pendaftaran. Hal ini akan meminimalkan hambatan selama proses pendaftaran, sekaligus tetap menyediakan autentikasi multi-faktor untuk pengguna yang rentan terhadap ancaman keamanan.

  • Memerlukan penambahan faktor kedua secara inkremental saat pengguna ingin mengakses fitur dengan persyaratan keamanan yang ditingkatkan.

Menyiapkan pemverifikasi reCAPTCHA

Sebelum dapat mengirim kode SMS, Anda harus mengonfigurasi pemverifikasi reCAPTCHA. Firebase menggunakan reCAPTCHA untuk mencegah penyalahgunaan dengan memastikan bahwa permintaan verifikasi nomor telepon berasal dari salah satu domain yang diizinkan oleh aplikasi Anda.

Anda tidak perlu menyiapkan klien reCAPTCHA secara manual. Objek RecaptchaVerifier pada SDK klien secara otomatis membuat dan melakukan inisialisasi kunci dan rahasia klien yang diperlukan.

Menggunakan reCAPTCHA tidak terlihat

Objek RecaptchaVerifier mendukung reCAPTCHA tidak terlihat, yang sering kali dapat memverifikasi pengguna tanpa memerlukan interaksi. Untuk menggunakan reCAPTCHA tidak terlihat, buat RecaptchaVerifier dengan menetapkan parameter size ke invisible, dan tentukan ID elemen UI yang memulai pendaftaran multi-faktor:

API modular web 

import { RecaptchaVerifier } from "firebase/auth";

const recaptchaVerifier = new RecaptchaVerifier("sign-in-button", {
    "size": "invisible",
    "callback": function(response) {
        // reCAPTCHA solved, you can proceed with
        // phoneAuthProvider.verifyPhoneNumber(...).
        onSolvedRecaptcha();
    }
}, auth);

API dengan namespace web 

var recaptchaVerifier = new firebase.auth.RecaptchaVerifier('sign-in-button', {
'size': 'invisible',
'callback': function(response) {
  // reCAPTCHA solved, you can proceed with phoneAuthProvider.verifyPhoneNumber(...).
  onSolvedRecaptcha();
}
});

Menggunakan widget reCAPTCHA

Untuk menggunakan widget reCAPTCHA yang terlihat, buat elemen HTML untuk menampung widget tersebut, lalu buat objek RecaptchaVerifier dengan ID container UI. Secara opsional, Anda juga dapat menetapkan callback yang dipanggil saat reCAPTCHA diselesaikan atau habis masa berlakunya:

API modular web 

import { RecaptchaVerifier } from "firebase/auth";

const recaptchaVerifier = new RecaptchaVerifier(
    "recaptcha-container",

    // Optional reCAPTCHA parameters.
    {
      "size": "normal",
      "callback": function(response) {
        // reCAPTCHA solved, you can proceed with
        // phoneAuthProvider.verifyPhoneNumber(...).
        onSolvedRecaptcha();
      },
      "expired-callback": function() {
        // Response expired. Ask user to solve reCAPTCHA again.
        // ...
      }
    }, auth
);

API dengan namespace web 

var recaptchaVerifier = new firebase.auth.RecaptchaVerifier(
  'recaptcha-container',
  // Optional reCAPTCHA parameters.
  {
    'size': 'normal',
    'callback': function(response) {
      // reCAPTCHA solved, you can proceed with phoneAuthProvider.verifyPhoneNumber(...).
      // ...
      onSolvedRecaptcha();
    },
    'expired-callback': function() {
      // Response expired. Ask user to solve reCAPTCHA again.
      // ...
    }
  });

Merender reCAPTCHA di awal

Secara opsional, Anda dapat merender reCAPTCHA di awal sebelum memulai pendaftaran dua faktor:

API modular web 

recaptchaVerifier.render()
    .then(function (widgetId) {
        window.recaptchaWidgetId = widgetId;
    });

API dengan namespace web 

recaptchaVerifier.render()
  .then(function(widgetId) {
    window.recaptchaWidgetId = widgetId;
  });

Setelah render() berhasil, Anda akan memperoleh ID widget reCAPTCHA yang dapat digunakan untuk melakukan panggilan ke reCAPTCHA API:

var recaptchaResponse = grecaptcha.getResponse(window.recaptchaWidgetId);

RecaptchaVerifier memisahkan logika ini dengan metode verifikasi, sehingga Anda tidak perlu menangani variabel grecaptcha secara langsung.

Mendaftarkan faktor kedua

Untuk mendaftarkan faktor sekunder baru untuk pengguna:

  1. Autentikasi ulang pengguna.

  2. Minta pengguna untuk memasukkan nomor teleponnya.

  3. Lakukan inisialisasi pemverifikasi reCAPTCHA seperti yang dijelaskan di bagian sebelumnya. Lewati langkah ini jika instance RecaptchaVerifier sudah dikonfigurasi:

    API modular web 

    import { RecaptchaVerifier } from "firebase/auth";

const recaptchaVerifier = new RecaptchaVerifier('recaptcha-container-id', undefined, auth);

    API dengan namespace web 

    var recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container-id');

  4. Dapatkan sesi multi-faktor untuk pengguna:

    API modular web 

    import { multiFactor } from "firebase/auth";

multiFactor(user).getSession().then(function (multiFactorSession) {
    // ...
});

    API dengan namespace web 

    user.multiFactor.getSession().then(function(multiFactorSession) {
  // ...
})

  5. Lakukan inisialisasi objek PhoneInfoOptions dengan nomor telepon pengguna dan sesi multi-faktor:

    API modular web 

    // Specify the phone number and pass the MFA session.
const phoneInfoOptions = {
  phoneNumber: phoneNumber,
  session: multiFactorSession
};

    API dengan namespace web 

    // Specify the phone number and pass the MFA session.
var phoneInfoOptions = {
  phoneNumber: phoneNumber,
  session: multiFactorSession
};

  6. Kirim pesan verifikasi ke ponsel pengguna:

    API modular web 

    import { PhoneAuthProvider } from "firebase/auth";

const phoneAuthProvider = new PhoneAuthProvider(auth);
phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, recaptchaVerifier)
    .then(function (verificationId) {
        // verificationId will be needed to complete enrollment.
    });

    API dengan namespace web 

    var phoneAuthProvider = new firebase.auth.PhoneAuthProvider();
// Send SMS verification code.
return phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, recaptchaVerifier)
  .then(function(verificationId) {
    // verificationId will be needed for enrollment completion.
  })

    Meskipun tidak diwajibkan, sebaiknya beri tahu pengguna terlebih dahulu bahwa mereka akan menerima pesan SMS, dan dikenakan tarif standar.

  7. Jika permintaan gagal, reset reCAPTCHA, lalu ulangi langkah sebelumnya agar pengguna dapat mencoba lagi. Perlu diperhatikan bahwa verifyPhoneNumber() akan otomatis mereset reCAPTCHA saat terjadi error, karena token reCAPTCHA hanya dapat digunakan satu kali.

    API modular web 

    recaptchaVerifier.clear();

    API dengan namespace web 

    recaptchaVerifier.clear();

  8. Setelah kode SMS dikirim, minta pengguna untuk memverifikasi kode tersebut:

    API modular web 

    // Ask user for the verification code. Then:
const cred = PhoneAuthProvider.credential(verificationId, verificationCode);

    API dengan namespace web 

    // Ask user for the verification code. Then:
var cred = firebase.auth.PhoneAuthProvider.credential(verificationId, verificationCode);

  9. Lakukan inisialisasi objek MultiFactorAssertion dengan PhoneAuthCredential:

    API modular web 

    import { PhoneMultiFactorGenerator } from "firebase/auth";

const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(cred);

    API dengan namespace web 

    var multiFactorAssertion = firebase.auth.PhoneMultiFactorGenerator.assertion(cred);

  10. Selesaikan pendaftaran. Secara opsional, Anda dapat menentukan nama tampilan untuk faktor kedua. Hal ini berguna bagi pengguna dengan beberapa faktor kedua, karena nomor telepon disamarkan selama alur autentikasi (misalnya, +1******1234).

    API modular web 

    // Complete enrollment. This will update the underlying tokens
// and trigger ID token change listener.
multiFactor(user).enroll(multiFactorAssertion, "My personal phone number");

    API dengan namespace web 

    // Complete enrollment. This will update the underlying tokens
// and trigger ID token change listener.
user.multiFactor.enroll(multiFactorAssertion, 'My personal phone number');

Kode di bawah menunjukkan contoh lengkap proses pendaftaran faktor kedua:

API modular web 

import {
    multiFactor, PhoneAuthProvider, PhoneMultiFactorGenerator,
    RecaptchaVerifier
} from "firebase/auth";

const recaptchaVerifier = new RecaptchaVerifier('recaptcha-container-id', undefined, auth);
multiFactor(user).getSession()
    .then(function (multiFactorSession) {
        // Specify the phone number and pass the MFA session.
        const phoneInfoOptions = {
            phoneNumber: phoneNumber,
            session: multiFactorSession
        };

        const phoneAuthProvider = new PhoneAuthProvider(auth);

        // Send SMS verification code.
        return phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, recaptchaVerifier);
    }).then(function (verificationId) {
        // Ask user for the verification code. Then:
        const cred = PhoneAuthProvider.credential(verificationId, verificationCode);
        const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(cred);

        // Complete enrollment.
        return multiFactor(user).enroll(multiFactorAssertion, mfaDisplayName);
    });

API dengan namespace web 

var recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container-id');
user.multiFactor.getSession().then(function(multiFactorSession) {
  // Specify the phone number and pass the MFA session.
  var phoneInfoOptions = {
    phoneNumber: phoneNumber,
    session: multiFactorSession
  };
  var phoneAuthProvider = new firebase.auth.PhoneAuthProvider();
  // Send SMS verification code.
  return phoneAuthProvider.verifyPhoneNumber(
      phoneInfoOptions, recaptchaVerifier);
})
.then(function(verificationId) {
  // Ask user for the verification code.
  var cred = firebase.auth.PhoneAuthProvider.credential(verificationId, verificationCode);
  var multiFactorAssertion = firebase.auth.PhoneMultiFactorGenerator.assertion(cred);
  // Complete enrollment.
  return user.multiFactor.enroll(multiFactorAssertion, mfaDisplayName);
});

Selamat! Anda berhasil mendaftarkan faktor autentikasi kedua untuk pengguna.

Memproses login pengguna dengan faktor kedua

Untuk memproses login pengguna dengan verifikasi SMS dua faktor:

  1. Proses login pengguna dengan faktor pertamanya, lalu tangkap error auth/multi-factor-auth-required. Error ini berisi resolver, petunjuk tentang faktor kedua yang didaftarkan, dan sesi yang mendasarinya yang membuktikan bahwa pengguna berhasil diautentikasi dengan faktor pertama.

    Misalnya, jika faktor pertama pengguna adalah email dan sandi:

    API modular web 

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

const auth = getAuth();
signInWithEmailAndPassword(auth, email, password)
    .then(function (userCredential) {
        // User successfully signed in and is not enrolled with a second factor.
    })
    .catch(function (error) {
        if (error.code == 'auth/multi-factor-auth-required') {
            // The user is a multi-factor user. Second factor challenge is required.
            resolver = getMultiFactorResolver(auth, error);
            // ...
        } else if (error.code == 'auth/wrong-password') {
            // Handle other errors such as wrong password.
        }
});

    API dengan namespace web 

    firebase.auth().signInWithEmailAndPassword(email, password)
  .then(function(userCredential) {
    // User successfully signed in and is not enrolled with a second factor.
  })
  .catch(function(error) {
    if (error.code == 'auth/multi-factor-auth-required') {
      // The user is a multi-factor user. Second factor challenge is required.
      resolver = error.resolver;
      // ...
    } else if (error.code == 'auth/wrong-password') {
      // Handle other errors such as wrong password.
    } ...
  });

    Jika faktor pertama pengguna adalah penyedia gabungan, seperti OAuth, SAML, atau OIDC, tangkap error setelah memanggil signInWithPopup() atau signInWithRedirect().

  2. Jika pengguna mendaftarkan beberapa faktor sekunder, tanyakan kepada mereka faktor mana yang ingin digunakan:

    API modular web 

    // Ask user which second factor to use.
// You can get the masked phone number via resolver.hints[selectedIndex].phoneNumber
// You can get the display name via resolver.hints[selectedIndex].displayName

if (resolver.hints[selectedIndex].factorId ===
    PhoneMultiFactorGenerator.FACTOR_ID) {
    // User selected a phone second factor.
    // ...
} else if (resolver.hints[selectedIndex].factorId ===
           TotpMultiFactorGenerator.FACTOR_ID) {
    // User selected a TOTP second factor.
    // ...
} else {
    // Unsupported second factor.
}

    API dengan namespace web 

    // Ask user which second factor to use.
// You can get the masked phone number via resolver.hints[selectedIndex].phoneNumber
// You can get the display name via resolver.hints[selectedIndex].displayName
if (resolver.hints[selectedIndex].factorId === firebase.auth.PhoneMultiFactorGenerator.FACTOR_ID) {
  // User selected a phone second factor.
  // ...
} else if (resolver.hints[selectedIndex].factorId === firebase.auth.TotpMultiFactorGenerator.FACTOR_ID) {
  // User selected a TOTP second factor.
  // ...
} else {
  // Unsupported second factor.
}

  3. Lakukan inisialisasi pemverifikasi reCAPTCHA seperti yang dijelaskan di bagian sebelumnya. Lewati langkah ini jika instance RecaptchaVerifier sudah dikonfigurasi:

    API modular web 

    import { RecaptchaVerifier } from "firebase/auth";

recaptchaVerifier = new RecaptchaVerifier('recaptcha-container-id', undefined, auth);

    API dengan namespace web 

    var recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container-id');

  4. Lakukan inisialisasi objek PhoneInfoOptions dengan nomor telepon pengguna dan sesi multi-faktor. Nilai ini terdapat dalam objek resolver yang diteruskan ke error auth/multi-factor-auth-required:

    API modular web 

    const phoneInfoOptions = {
    multiFactorHint: resolver.hints[selectedIndex],
    session: resolver.session
};

    API dengan namespace web 

    var phoneInfoOptions = {
  multiFactorHint: resolver.hints[selectedIndex],
  session: resolver.session
};

  5. Kirim pesan verifikasi ke ponsel pengguna:

    API modular web 

    // Send SMS verification code.
const phoneAuthProvider = new PhoneAuthProvider(auth);
phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, recaptchaVerifier)
    .then(function (verificationId) {
        // verificationId will be needed for sign-in completion.
    });

    API dengan namespace web 

    var phoneAuthProvider = new firebase.auth.PhoneAuthProvider();
// Send SMS verification code.
return phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, recaptchaVerifier)
  .then(function(verificationId) {
    // verificationId will be needed for sign-in completion.
  })

  6. Jika permintaan gagal, reset reCAPTCHA, lalu ulangi langkah sebelumnya agar pengguna dapat mencoba lagi:

    API modular web 

    recaptchaVerifier.clear();

    API dengan namespace web 

    recaptchaVerifier.clear();

  7. Setelah kode SMS dikirim, minta pengguna untuk memverifikasi kode tersebut:

    API modular web 

    const cred = PhoneAuthProvider.credential(verificationId, verificationCode);

    API dengan namespace web 

    // Ask user for the verification code. Then:
var cred = firebase.auth.PhoneAuthProvider.credential(verificationId, verificationCode);

  8. Lakukan inisialisasi objek MultiFactorAssertion dengan PhoneAuthCredential:

    API modular web 

    const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(cred);

    API dengan namespace web 

    var multiFactorAssertion = firebase.auth.PhoneMultiFactorGenerator.assertion(cred);

  9. Panggil resolver.resolveSignIn() untuk menyelesaikan autentikasi sekunder. Selanjutnya, Anda dapat mengakses hasil login asli, yang mencakup kredensial autentikasi dan data khusus penyedia standar:

    API modular web 

    // Complete sign-in. This will also trigger the Auth state listeners.
resolver.resolveSignIn(multiFactorAssertion)
    .then(function (userCredential) {
        // userCredential will also contain the user, additionalUserInfo, optional
        // credential (null for email/password) associated with the first factor sign-in.

        // For example, if the user signed in with Google as a first factor,
        // userCredential.additionalUserInfo will contain data related to Google
        // provider that the user signed in with.
        // - user.credential contains the Google OAuth credential.
        // - user.credential.accessToken contains the Google OAuth access token.
        // - user.credential.idToken contains the Google OAuth ID token.
    });

    API dengan namespace web 

    // Complete sign-in. This will also trigger the Auth state listeners.
resolver.resolveSignIn(multiFactorAssertion)
  .then(function(userCredential) {
    // userCredential will also contain the user, additionalUserInfo, optional
    // credential (null for email/password) associated with the first factor sign-in.
    // For example, if the user signed in with Google as a first factor,
    // userCredential.additionalUserInfo will contain data related to Google provider that
    // the user signed in with.
    // user.credential contains the Google OAuth credential.
    // user.credential.accessToken contains the Google OAuth access token.
    // user.credential.idToken contains the Google OAuth ID token.
  });

Kode di bawah menunjukkan contoh lengkap proses login pengguna multi-faktor:

API modular web 

import {
    getAuth,
    getMultiFactorResolver,
    PhoneAuthProvider,
    PhoneMultiFactorGenerator,
    RecaptchaVerifier,
    signInWithEmailAndPassword
} from "firebase/auth";

const recaptchaVerifier = new RecaptchaVerifier('recaptcha-container-id', undefined, auth);

const auth = getAuth();
signInWithEmailAndPassword(auth, email, password)
    .then(function (userCredential) {
        // User is not enrolled with a second factor and is successfully
        // signed in.
        // ...
    })
    .catch(function (error) {
        if (error.code == 'auth/multi-factor-auth-required') {
            const resolver = getMultiFactorResolver(auth, error);
            // Ask user which second factor to use.
            if (resolver.hints[selectedIndex].factorId ===
                PhoneMultiFactorGenerator.FACTOR_ID) {
                const phoneInfoOptions = {
                    multiFactorHint: resolver.hints[selectedIndex],
                    session: resolver.session
                };
                const phoneAuthProvider = new PhoneAuthProvider(auth);
                // Send SMS verification code
                return phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, recaptchaVerifier)
                    .then(function (verificationId) {
                        // Ask user for the SMS verification code. Then:
                        const cred = PhoneAuthProvider.credential(
                            verificationId, verificationCode);
                        const multiFactorAssertion =
                            PhoneMultiFactorGenerator.assertion(cred);
                        // Complete sign-in.
                        return resolver.resolveSignIn(multiFactorAssertion)
                    })
                    .then(function (userCredential) {
                        // User successfully signed in with the second factor phone number.
                    });
            } else if (resolver.hints[selectedIndex].factorId ===
                       TotpMultiFactorGenerator.FACTOR_ID) {
                // Handle TOTP MFA.
                // ...
            } else {
                // Unsupported second factor.
            }
        } else if (error.code == 'auth/wrong-password') {
            // Handle other errors such as wrong password.
        }
    });

API dengan namespace web 

var resolver;
firebase.auth().signInWithEmailAndPassword(email, password)
  .then(function(userCredential) {
    // User is not enrolled with a second factor and is successfully signed in.
    // ...
  })
  .catch(function(error) {
    if (error.code == 'auth/multi-factor-auth-required') {
      resolver = error.resolver;
      // Ask user which second factor to use.
      if (resolver.hints[selectedIndex].factorId ===
          firebase.auth.PhoneMultiFactorGenerator.FACTOR_ID) {
        var phoneInfoOptions = {
          multiFactorHint: resolver.hints[selectedIndex],
          session: resolver.session
        };
        var phoneAuthProvider = new firebase.auth.PhoneAuthProvider();
        // Send SMS verification code
        return phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, recaptchaVerifier)
          .then(function(verificationId) {
            // Ask user for the SMS verification code.
            var cred = firebase.auth.PhoneAuthProvider.credential(
                verificationId, verificationCode);
            var multiFactorAssertion =
                firebase.auth.PhoneMultiFactorGenerator.assertion(cred);
            // Complete sign-in.
            return resolver.resolveSignIn(multiFactorAssertion)
          })
          .then(function(userCredential) {
            // User successfully signed in with the second factor phone number.
          });
      } else if (resolver.hints[selectedIndex].factorId ===
        firebase.auth.TotpMultiFactorGenerator.FACTOR_ID) {
        // Handle TOTP MFA.
        // ...
      } else {
        // Unsupported second factor.
      }
    } else if (error.code == 'auth/wrong-password') {
      // Handle other errors such as wrong password.
    } ...
  });

Selamat! Anda berhasil memproses login pengguna menggunakan autentikasi multi-faktor.

Langkah berikutnya