Menambahkan autentikasi multi-faktor ke aplikasi web Anda

Dokumen ini menunjukkan cara menambahkan autentikasi multi-faktor SMS ke aplikasi web Anda.

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

Sebelum memulai

Aktifkan minimal satu penyedia yang mendukung autentikasi multi-faktor. Setiap penyedia mendukung MFA, kecuali autentikasi dengan ponsel, autentikasi anonim, dan Apple Game Center.
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):

Di konsol Google Cloud, pilih tenant yang ingin Anda gunakan.

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

Web versi 9

import { getAuth } from "firebase/auth";

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

Web versi 8

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

Mengaktifkan autentikasi multi-faktor

Buka halaman Identity Platform MFA di Konsol Google Cloud.
Buka halaman MFA
Pada kotak berjudul SMS-Based Multi-Factor Authentication, klik Enable.
Masukkan nomor telepon yang akan digunakan untuk menguji aplikasi. Meskipun opsional, mendaftarkan nomor telepon pengujian sangat direkomendasikan untuk menghindari throttling selama pengembangan.
Jika Anda belum memberikan otorisasi pada domain aplikasi, tambahkan domain tersebut ke daftar yang diizinkan dengan mengklik Tambahkan domain di sebelah kanan.
Klik Simpan.

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. Identity Platform 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:

Web versi 9

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);

Web versi 8

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:

Web versi 9

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
);

Web versi 8

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:

Web versi 9

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

Web versi 8

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:

Autentikasi ulang pengguna.
Minta pengguna untuk memasukkan nomor teleponnya.

Catatan: Google menyimpan dan menggunakan nomor telepon untuk meningkatkan kualitas pencegahan spam dan penyalahgunaan di seluruh layanan Google. Pastikan Anda mendapatkan izin yang sesuai dari pengguna Anda sebelum mengirim nomor telepon mereka ke Identity Platform.

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

Web versi 9

import { RecaptchaVerifier } from "firebase/auth";

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

Web versi 8

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

Dapatkan sesi multi-faktor untuk pengguna:

Web versi 9

import { multiFactor } from "firebase/auth";

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

Web versi 8

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

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

Web versi 9

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

Web versi 8

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

Kirim pesan verifikasi ke ponsel pengguna:

Web versi 9

import { PhoneAuthProvider } from "firebase/auth";

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

Web versi 8

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.

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.
Web versi 9
```
recaptchaVerifier.clear();
```
Web versi 8
```
recaptchaVerifier.clear();
```

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

Web versi 9

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

Web versi 8

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

Lakukan inisialisasi objek MultiFactorAssertion dengan PhoneAuthCredential:

Web versi 9

import { PhoneMultiFactorGenerator } from "firebase/auth";

const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(cred);

Web versi 8

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

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).

Web versi 9

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

Web versi 8

// 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:

Web versi 9

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);
    });

Web versi 8

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:

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:

Web versi 9

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.
        }
});

Web versi 8

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().

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

Web versi 9

// 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.
}

Web versi 8

// 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.
}

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

Web versi 9

import { RecaptchaVerifier } from "firebase/auth";

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

Web versi 8

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

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:

Web versi 9

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

Web versi 8

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

Kirim pesan verifikasi ke ponsel pengguna:

Web versi 9

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

Web versi 8

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.
  })

Jika permintaan gagal, reset reCAPTCHA, lalu ulangi langkah sebelumnya agar pengguna dapat mencoba lagi:
Web versi 9
```
recaptchaVerifier.clear();
```
Web versi 8
```
recaptchaVerifier.clear();
```

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

Web versi 9

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

Web versi 8

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

Lakukan inisialisasi objek MultiFactorAssertion dengan PhoneAuthCredential:

Web versi 9

const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(cred);

Web versi 8

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

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

Web versi 9

// 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.
    });

Web versi 8

// 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:

Web versi 9

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.
        }
    });

Web versi 8

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 selanjutnya

Mengelola pengguna multi-faktor secara terprogram dengan Admin SDK.