Mengaktifkan reCAPTCHA SMS defense untuk autentikasi berbasis SMS

Dokumen ini menjelaskan cara menggunakan reCAPTCHA untuk melindungi alur berbasis SMS Identity Platform Anda, seperti autentikasi multi-faktor dan telepon, dari penipuan pulsa SMS (juga dikenal sebagai serangan pumping SMS).

Ringkasan

Jika aplikasi Anda mengandalkan alur berbasis SMS untuk autentikasi, Anda dapat mengaktifkan integrasi Firebase Authentication atau Identity Platform dengan reCAPTCHA. Jika diaktifkan, Firebase Authentication dan Identity Platform akan memanggil fitur pertahanan SMS reCAPTCHA saat pengguna meminta SMS verifikasi dari aplikasi atau situs Anda menggunakan operasi phoneProvider berikut:

Operasi Metode
Daftar atau login dengan nomor telepon sendVerificationCode
Pendaftaran nomor telepon MFA mfaSmsEnrollment
Login dengan nomor telepon MFA mfaSmsSignIn

reCAPTCHA kemudian memberikan skor risiko kepada Firebase Authentication atau Identity Platform yang menunjukkan kemungkinan nomor telepon pengguna akan melakukan penipuan pulsa SMS. Firebase Authentication dan Identity Platform membandingkan skor ini dengan nilai minimum yang Anda tetapkan dalam konfigurasi pertahanan SMS reCAPTCHA, lalu menangani permintaan berdasarkan tindakan yang telah Anda tetapkan dalam konfigurasi.

Untuk mengetahui informasi selengkapnya tentang fitur pertahanan SMS reCAPTCHA, lihat Mendeteksi dan mencegah penipuan SMS.

Sebelum memulai

Sebelum mengaktifkan reCAPTCHA SMS defense untuk Identity Platform, selesaikan tugas berikut:

  • Konfigurasikan hal berikut untuk aplikasi atau situs Anda sebagaimana berlaku:

  • Jika Anda belum melakukannya, buat akun layanan untuk setiap project yang akan menggunakan reCAPTCHA. Untuk mengetahui petunjuknya, lihat Membuat akun layanan.

Mode penerapan autentikasi ponsel reCAPTCHA

reCAPTCHA SMS defense mengharuskan Anda menyiapkan penerapan reCAPTCHA autentikasi telepon, yang memiliki dua mode: audit dan enforce.

Mode audit

Saat Anda menetapkan penerapan autentikasi telepon ke mode audit, Identity Platform akan menggunakan pertahanan SMS reCAPTCHA untuk verifikasi aplikasi. Jika permintaan pengguna lulus penilaian penipuan tol, Identity Platform akan mengirimkan pesan SMS yang berisi kode verifikasi ke ponsel pengguna. Jika permintaan gagal dalam penilaian penipuan tol dan Anda menggunakan SDK klien, metode verifikasi penggantian akan dipicu untuk menyelesaikan alur autentikasi telepon. Metode penggantian yang diterima bergantung pada platform aplikasi Anda.

SDK klien memicu metode verifikasi penggantian dalam skenario berikut:

  • Token reCAPTCHA tidak ada.
  • Token reCAPTCHA tidak valid atau sudah tidak berlaku.
  • Token reCAPTCHA tidak lulus nilai minimum.
  • reCAPTCHA tidak dikonfigurasi dengan benar.

Pastikan metode verifikasi penggantian untuk platform aplikasi Anda disiapkan dan siap dipicu oleh SDK klien jika diperlukan.

Web

Jika penilaian penipuan tol awal gagal, mode audit mengandalkan reCAPTCHA v2 untuk verifikasi. Oleh karena itu, Anda harus menyiapkan pemverifikasi reCAPTCHA (RecaptchaVerifier) dan meneruskannya ke operasi autentikasi ponsel berikut:

  • verifyPhoneNumber
  • signInWithPhoneNumber
  • linkWithPhoneNumber
  • reauthenticateWithPhoneNumber
Tanpa pemverifikasi reCAPTCHA, Identity Platform tidak dapat memulai reCAPTCHA v2 dan akan menampilkan auth/argument-error. Untuk mengetahui informasi selengkapnya tentang cara menyiapkan pemverifikasi reCAPTCHA, lihat Menyiapkan pemverifikasi reCAPTCHA dalam dokumentasi Firebase.

Android

Jika penilaian penipuan tol awal gagal, mode audit akan memverifikasi aplikasi Anda terhadap Play Integrity API. Jika verifikasi ini gagal, reCAPTCHA v2 akan dipicu. reCAPTCHA v2 mungkin dipicu dalam skenario berikut:

  • Jika perangkat pengguna akhir tidak menginstal layanan Google Play.
  • Jika aplikasi tidak didistribusikan melalui Google Play Store (di Authentication SDK v21.2.0 dan yang lebih baru).
  • Jika token SafetyNet yang diperoleh tidak valid (di Authentication SDK versi sebelum v21.2.0).
Untuk mengetahui informasi selengkapnya tentang cara menyiapkan verifikasi aplikasi Android, lihat Mengaktifkan verifikasi aplikasi dalam dokumentasi Firebase.

iOS

Jika penilaian penipuan tol awal gagal, mode audit mengandalkan notifikasi push senyap untuk verifikasi. Metode verifikasi ini melibatkan pengiriman token ke aplikasi Anda di perangkat yang meminta dengan notifikasi push senyap. Jika aplikasi Anda berhasil menerima notifikasi, alur autentikasi telepon akan dilanjutkan. Jika aplikasi Anda tidak menerima notifikasi push, reCAPTCHA v2 akan dipicu. reCAPTCHA v2 mungkin dipicu jika notifikasi push senyap tidak dikonfigurasi dengan benar.

Untuk mengetahui informasi selengkapnya tentang cara menyiapkan verifikasi aplikasi iOS, lihat Mengaktifkan verifikasi aplikasi dalam dokumentasi Firebase.

Mode terapkan

Saat Anda menetapkan penerapan autentikasi telepon ke mode penerapan, Identity Platform akan menggunakan pertahanan SMS reCAPTCHA untuk verifikasi aplikasi. Jika permintaan pengguna lulus penilaian penipuan tol, Identity Platform akan mengirimkan pesan SMS yang berisi kode verifikasi ke ponsel pengguna. Jika permintaan gagal dalam penilaian penipuan tol, Identity Platform akan memblokir permintaan dan tidak mengirim pesan SMS yang berisi kode verifikasi.

Tidak ada verifikasi penggantian yang diperlukan dalam mode penerapan, Anda tidak perlu menyiapkan metode verifikasi tambahan untuk aplikasi. Namun, sebaiknya siapkan verifikasi reCAPTCHA untuk aplikasi web guna memastikan reCAPTCHA v2 diaktifkan jika Anda memutuskan untuk mengubah mode reCAPTCHA aplikasi menjadi AUDIT atau OFF.

Mengaktifkan reCAPTCHA SMS defense

Untuk mengaktifkan reCAPTCHA SMS defense, lakukan hal berikut:

  1. Jika Anda belum melakukannya, aktifkan reCAPTCHA Enterprise API di project Anda.

  2. Aktifkan reCAPTCHA SMS defense dengan reCAPTCHA. Untuk mengetahui petunjuknya, lihat bagian Sebelum memulai di halaman Deteksi dan cegah penipuan SMS dalam dokumentasi reCAPTCHA.

  3. Untuk mengaktifkan reCAPTCHA SMS defense untuk project, gunakan Admin SDK untuk memanggil updateConfig sebagai berikut:

      // Update the reCAPTCHA config to enable toll fraud protection
  const updateProjectConfigRequest = {
    recaptchaConfig: {
      phoneEnforcementState: 'ENFORCE_MODE',
      useSmsTollFraudProtection: 'true',
      tollFraudManagedRules: [{ startScore: START_SCORE,
        action: 'BLOCK' }],
    }
  }
  let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);

    Ganti kode berikut:

    • ENFORCE_MODE: mode yang ingin Anda tetapkan untuk penerapan autentikasi telepon reCAPTCHA. Nilai yang valid adalah OFF, AUDIT, dan ENFORCE. Untuk mengaktifkan pertahanan SMS reCAPTCHA, parameter ini harus ditetapkan ke AUDIT atau ENFORCE dan useSmsTollFraudProtection harus ditetapkan ke true.

      Saat mengaktifkan pertahanan SMS reCAPTCHA untuk pertama kalinya, sebaiknya tetapkan status penerapan ke AUDIT dan pastikan alur autentikasi Anda dilindungi sebelum menetapkannya ke ENFORCE. Untuk mengetahui informasi selengkapnya tentang cara kerja mode ini, lihat Mode penerapan autentikasi ponsel reCAPTCHA.

    • START_SCORE: skor penilaian penipuan tol tertinggi yang dapat dimiliki permintaan sebelum gagal. Anda dapat menetapkan skor ini menjadi antara 0.0 dan 1.0. Setiap skor di atas nilai minimum yang Anda tetapkan akan dianggap sebagai penipuan SMS tol. Misalnya, jika Anda menetapkan nilai minimum 0.3, reCAPTCHA akan menolak permintaan apa pun dengan 0.4 atau yang lebih tinggi. Oleh karena itu, semakin rendah skor yang Anda tetapkan, semakin ketat aturannya.

  4. Jika Anda menggunakan Identity Platform di web atau Android, daftarkan aplikasi Anda dari Firebase console:

    Penyediaan kunci reCAPTCHA dapat memerlukan waktu beberapa menit untuk selesai.

  5. Jika Anda telah menetapkan penerapan ke mode audit, sebaiknya pantau metrik reCAPTCHA untuk pertahanan SMS reCAPTCHA untuk memastikan bahwa alur Anda dilindungi.

Mengonfigurasi SDK klien

Konfigurasikan SDK klien sesuai dengan platform aplikasi Anda.

Web

  1. Update ke SDK web versi terbaru.

    • Dukungan reCAPTCHA untuk autentikasi email dan sandi di aplikasi web tersedia di JavaScript SDK versi 9.20.0 dan yang lebih baru.
    • Dukungan reCAPTCHA untuk autentikasi telepon di aplikasi web tersedia di JavaScript SDK versi 11 dan yang lebih baru.

    Setelah Anda mengintegrasikan SDK web dengan aplikasi, SDK akan otomatis mengambil konfigurasi reCAPTCHA dan mengaktifkan perlindungan untuk penyedia yang telah Anda konfigurasi.

  2. Jika diperlukan, Anda dapat memaksa pengambilan sinyal reCAPTCHA sebagai berikut:

    import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Authentication
const auth = getAuth();
initializeRecaptchaConfig(auth)
  .then(() => {
    console.log("Recaptcha Enterprise Config Initialization successful.")
  })
  .catch((error) => {
    console.error("Recaptcha Enterprise Config Initialization failed with " + error)
  });

Android

  1. Update ke Android SDK versi terbaru. Dukungan reCAPTCHA untuk autentikasi email dan sandi serta autentikasi ponsel di aplikasi Android tersedia di Android SDK versi 23.1.0 dan yang lebih baru.

    Selain itu, dukungan reCAPTCHA memerlukan API level 23 (Marshmallow) atau yang lebih tinggi dan Android 6 atau yang lebih tinggi.

    Setelah Anda mengintegrasikan Android SDK dengan aplikasi, SDK akan otomatis mengambil konfigurasi reCAPTCHA dan mengaktifkan perlindungan untuk penyedia yang telah Anda konfigurasi.

  2. Tambahkan aturan build berikut ke bagian dependensi file build.gradle level aplikasi Anda:

    implementation 'com.google.android.recaptcha:recaptcha:18.5.1'

    Pastikan untuk menggunakan reCAPTCHA SDK versi 18.5.1 atau yang lebih baru.

  3. Jika diperlukan, Anda dapat memaksa pengambilan sinyal reCAPTCHA sebagai berikut:

    • Kotlin:
    // Initialize Firebase Authentication
auth = Firebase.auth

auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
    if (task.isSuccessful) {
        Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
    } else {
        Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
    }
}
    • Java:
    // Initialize Firebase Authentication
auth = FirebaseAuth.getInstance();
auth.initializeRecaptchaConfig().addOnCompleteListener(
  this, new OnCompleteListener<void>() {
  @Override
  public void onComplete(@NonNull Task<void> task) {
    if (task.isSuccessful()) {
      Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
    } else {
      Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
    }
  }
});

iOS

  1. Update ke iOS SDK versi 11.6.0 atau yang lebih baru. Setelah Anda mengintegrasikan iOS SDK dengan aplikasi, SDK akan otomatis mengambil konfigurasi reCAPTCHA dan mengaktifkan perlindungan untuk penyedia yang telah Anda konfigurasi.

  2. Untuk mengintegrasikan reCAPTCHA iOS SDK ke aplikasi Anda, lihat Menyiapkan lingkungan.

  3. Pastikan -ObjC tercantum dalam flag penaut Anda. Buka Target > Build Settings > All > Linking dan pastikan Other Linker Flags menampilkan -ObjC.

  4. Jika diperlukan, Anda dapat memaksa pengambilan sinyal reCAPTCHA sebagai berikut:

    • Swift:
    // Initialize Firebase Authentication
try await Auth.auth().initializeRecaptchaConfig()
    • Objective-C:
    // Initialize Firebase Authentication
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Authentication initialization finished
}];

Memantau metrik reCAPTCHA untuk reCAPTCHA SMS defense

Sebelum menetapkan penerapan reCAPTCHA ke mode penerapan, sebaiknya Anda menggunakan mode audit dan memantau metrik reCAPTCHA yang dihasilkan project Anda untuk memastikan bahwa alur autentikasi berbasis SMS Anda dilindungi. Misalnya, metrik ini dapat membantu Anda menentukan apakah Anda telah menyiapkan integrasi Identity Platform dengan reCAPTCHA Enterprise API dengan benar. Laporan ini juga dapat membantu Anda menyesuaikan nilai minimum skor untuk traffic pengguna.

Pastikan fitur reCAPTCHA SMS defense berfungsi dengan memeriksa metrik berikut yang dihasilkan project Anda ke Cloud Monitoring:

Untuk mengetahui informasi selengkapnya, lihat Memantau metrik reCAPTCHA.

Menerapkan reCAPTCHA SMS defense

Setelah memverifikasi bahwa aplikasi Anda menerima traffic pengguna yang dapat diterima, Anda dapat mengaktifkan penerapan reCAPTCHA untuk melindungi pengguna. Pastikan Anda tidak mengganggu pengguna yang ada, termasuk pengguna yang mungkin menggunakan versi lama aplikasi Anda.

Untuk mengaktifkan penerapan reCAPTCHA untuk alur autentikasi berbasis SMS di project atau tenant, gunakan Admin SDK untuk menjalankan perintah berikut:

  const enforceRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }
  };

Menonaktifkan reCAPTCHA SMS defense

Untuk menonaktifkan pertahanan SMS reCAPTCHA, gunakan Admin SDK untuk menjalankan perintah berikut:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'OFF',
      useSmsTollFraudProtection: 'false'
    }
  };

Untuk menonaktifkan reCAPTCHA SMS defense saat Anda menggunakan perlindungan dari bot, lihat Menonaktifkan reCAPTCHA SMS defense saat menggunakan perlindungan dari bot.

Menggunakan reCAPTCHA SMS defense dengan perlindungan dari bot

Anda dapat menggunakan reCAPTCHA SMS defense secara bersamaan dengan perlindungan terhadap bot. Untuk konfigurasi yang menggunakan kedua fitur perlindungan, pertimbangkan hal berikut:

  • Jika Anda telah menetapkan status penerapan autentikasi ponsel ke audit, Identity Platform akan meneruskan permintaan jika memenuhi setidaknya salah satu penilaian. Sebaiknya pantau metrik reCAPTCHA untuk memastikan reCAPTCHA SMS defense dan perlindungan bot dikonfigurasi dengan setelan skor yang wajar.
  • Jika Anda telah menetapkan status penerapan autentikasi telepon ke penerapan, Identity Platform hanya akan meneruskan permintaan jika memenuhi penilaian dan permintaan gagal ditutup tanpa kembali ke metode verifikasi lain.

Untuk mengaktifkan kedua fitur tersebut, gunakan Admin SDK untuk menjalankan perintah berikut:

  const enableBothRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: true,
      useSmsBotScore: true
    }
  };

Ganti ENFORCE_MODE dengan mode yang ingin Anda tetapkan untuk penerapan autentikasi telepon reCAPTCHA. Nilai yang valid adalah OFF, AUDIT, dan ENFORCE. Untuk mengaktifkan reCAPTCHA SMS defense, parameter ini harus ditetapkan ke AUDIT atau ENFORCE. Saat mengaktifkan reCAPTCHA SMS defense untuk pertama kalinya, sebaiknya tetapkan parameter ini ke AUDIT dan pastikan alur autentikasi Anda dilindungi sebelum menetapkannya ke ENFORCE. Untuk mengetahui informasi selengkapnya tentang cara kerja mode ini, lihat Mode penerapan autentikasi telepon reCAPTCHA.

Menonaktifkan reCAPTCHA SMS defense saat menggunakan perlindungan dari bot

Jika Anda menggunakan pertahanan SMS reCAPTCHA dan perlindungan bot secara bersamaan, dan ingin menonaktifkan pertahanan SMS reCAPTCHA tanpa menonaktifkan perlindungan bot, gunakan Admin SDK untuk menjalankan perintah berikut:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }
  };

Ganti ENFORCE_MODE dengan mode yang sebelumnya Anda tetapkan untuk penerapan autentikasi telepon reCAPTCHA. Nilai ini harus AUDIT atau ENFORCE. Untuk mengetahui informasi selengkapnya tentang cara kerja mode ini, lihat Mode penerapan autentikasi telepon reCAPTCHA.

Langkah berikutnya