Mengintegrasikan Identity Platform dengan reCAPTCHA Enterprise API

Dokumen ini menunjukkan cara menggunakan integrasi Identity Platform dengan reCAPTCHA Enterprise API untuk meningkatkan keamanan bagi pengguna Anda. Fitur ini membuat aplikasi Anda lebih tahan terhadap spam, penyalahgunaan, dan aktivitas penipuan lainnya.

Integrasi ini membuat penilaian reCAPTCHA Enterprise atas nama Anda untuk memvalidasi permintaan pengguna. Untuk mengetahui informasi harga, lihat harga reCAPTCHA.

Ringkasan

Saat menyiapkan integrasi Identity Platform dengan reCAPTCHA Enterprise API, Anda mengaktifkan fitur perlindungan default reCAPTCHA, yaitu perlindungan bot reCAPTCHA. Dengan perlindungan terhadap bot, Identity Platform menyediakan kunci reCAPTCHA berbasis skor di project Anda atas nama Anda. Saat pengguna mengakses aplikasi atau situs Anda menggunakan salah satu operasi berikut, SDK klien akan memuat reCAPTCHA saat penyedia yang sesuai diaktifkan.

Penyedia Operasi Metode
passwordProvider Login dengan email dan sandi signInWithPassword
Pendaftaran dengan email dan sandi signUpPassword
Login dengan link email getOobCode
Reset sandi getOobCode
phoneProvider Pendaftaran atau login dengan nomor telepon sendVerificationCode
Pendaftaran nomor telepon MFA mfaSmsEnrollment
Login dengan nomor telepon MFA mfaSmsSignIn

reCAPTCHA kemudian memberikan skor kepada Identity Platform yang menilai risiko permintaan berdasarkan konfigurasi dan toleransi risiko Anda.

Untuk mengetahui informasi selengkapnya, lihat Ringkasan reCAPTCHA.

Sebelum memulai

Berdasarkan jenis alur autentikasi yang ingin Anda lindungi dengan reCAPTCHA, pastikan Anda telah menyiapkan hal berikut:

Membuat akun layanan

Integrasi Identity Platform dengan reCAPTCHA Enterprise API memerlukan akun layanan Identity Platform untuk setiap project yang akan menggunakan reCAPTCHA. Tindakan ini memungkinkan Identity Platform mengelola kunci reCAPTCHA atas nama Anda. Jika Anda sudah membuat akun layanan, beri akun tersebut akses ke reCAPTCHA.

Jika Anda belum membuat akun layanan atau memiliki project tambahan yang ingin dilindungi dengan reCAPTCHA, lakukan tindakan berikut:

  1. Gunakan Google Cloud CLI untuk membuat akun layanan:

    gcloud beta services identity create \
        --service=identitytoolkit.googleapis.com \
        --project=PROJECT_ID
    

    Ganti PROJECT_ID dengan project ID.

  2. Berikan akses akun layanan ke reCAPTCHA:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit. \
        --role=roles/identitytoolkit.serviceAgent
    

    Ganti kode berikut:

    • PROJECT_ID: the project ID
    • PROJECT_NUMBER: nomor akun project

Mode perlindungan terhadap bot reCAPTCHA

Perlindungan terhadap bot reCAPTCHA memiliki dua mode yang membantu Anda melindungi pengguna: audit dan tegakkan. Perilaku mode ini berbeda-beda berdasarkan penyedia identitas.

Penyedia email-sandi

Mode audit dan terapkan berperilaku sebagai berikut untuk alur autentikasi email-sandi.

Mode audit

Saat Anda menetapkan penerapan email-sandi ke mode audit, Identity Platform akan membuat satu atau beberapa kunci reCAPTCHA di project Anda yang digunakan untuk menilai traffic ke Identity Platform API tanpa memblokir permintaan apa pun. Gunakan metrik yang ditampilkan selama mode audit untuk menentukan apakah Anda harus mengaktifkan penerapan reCAPTCHA.

Mode terapkan

Saat Anda menetapkan penerapan email-sandi ke mode penerapan, Identity Platform akan membuat satu atau beberapa kunci reCAPTCHA di project Anda yang digunakan untuk menilai traffic ke Identity Platform API. Permintaan API yang tidak menyertakan token reCAPTCHA akan ditolak. Hanya aktifkan penerapan setelah Anda memigrasikan semua klien ke SDK dengan dukungan reCAPTCHA.

Penyedia telepon

Mode audit dan terapkan berperilaku sebagai berikut untuk alur autentikasi telepon.

Mode audit

Saat Anda menetapkan penerapan autentikasi telepon ke mode audit, Identity Platform akan menggunakan perlindungan bot reCAPTCHA untuk verifikasi aplikasi. Jika permintaan pengguna lulus penilaian perlindungan terhadap bot, Identity Platform akan mengirimkan pesan SMS yang berisi kode verifikasi ke ponsel pengguna. Jika permintaan gagal dalam penilaian perlindungan terhadap bot 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 perlindungan terhadap bot 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 perlindungan terhadap bot 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.

Mode terapkan

Saat Anda menetapkan penerapan autentikasi telepon ke mode penerapan, Identity Platform akan menggunakan perlindungan bot reCAPTCHA untuk verifikasi aplikasi. Jika permintaan pengguna lulus penilaian perlindungan bot, Identity Platform akan mengirimkan pesan SMS yang berisi kode verifikasi ke ponsel pengguna. Jika permintaan gagal dalam penilaian perlindungan bot, Identity Platform akan memblokir permintaan dan tidak mengirimkan 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 peverifikasi reCAPTCHA untuk aplikasi web guna memastikan reCAPTCHA v2 diaktifkan jika Anda memutuskan untuk mengubah mode reCAPTCHA aplikasi menjadi AUDIT atau OFF.

Menyiapkan integrasi Identity Platform dengan reCAPTCHA Enterprise API

Untuk menyiapkan integrasi Identity Platform dengan reCAPTCHA Enterprise API, Anda harus melakukan tugas berikut:

  • Gunakan Admin SDK untuk menetapkan status penerapan reCAPTCHA dan mengaktifkan perlindungan bot.
  • Konfigurasikan SDK klien untuk platform aplikasi Anda.

Sebaiknya aktifkan penerapan reCAPTCHA terlebih dahulu dalam mode audit dan pantau metrik reCAPTCHA yang dihasilkan project Anda untuk memastikan bahwa alur autentikasi dilindungi dengan benar. Anda melakukan hal ini agar tidak mengganggu traffic pengguna saat mengaudit penggunaan reCAPTCHA oleh mereka. Setelah memverifikasi bahwa alur autentikasi Anda dilindungi, tetapkan perlindungan bot ke ENFORCE.

Mengaktifkan perlindungan bot reCAPTCHA

Penyedia email-sandi

Untuk mengaktifkan perlindungan bot reCAPTCHA untuk alur autentikasi email-sandi, lakukan hal berikut:

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

  2. Untuk mengaktifkan perlindungan terhadap bot untuk project, gunakan Admin SDK. Dukungan reCAPTCHA tersedia di Node.js Admin SDK versi 11.7.0 dan yang lebih baru.

    Contoh:

    // Update project config with reCAPTCHA config
    const updateConfigRequest = {
      recaptchaConfig: {
        emailPasswordEnforcementState:  'ENFORCE_MODE',
        managedRules: [{
          endScore: END_SCORE,
          action: 'BLOCK'
        }]
      }
    };
    const updateProjectConfigWithRecaptcha = () => {
      getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
        console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
      }).catch((error) => {
        console.log('Error updating project config:', error);
      });
    }
    

    Ganti kode berikut:

    • ENFORCE_MODE: mode yang ingin Anda tetapkan untuk penerapan autentikasi email-sandi reCAPTCHA. Nilai yang valid adalah OFF, AUDIT, dan ENFORCE. Untuk mengaktifkan perlindungan bot, parameter ini harus ditetapkan ke AUDIT atau ENFORCE. Saat Anda mengaktifkan perlindungan terhadap bot untuk pertama kali, 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 perlindungan terhadap bot reCAPTCHA.
    • END_SCORE: skor penilaian perlindungan bot terendah yang dapat dimiliki permintaan sebelum gagal. Anda dapat menetapkan skor ini antara 0.0 dan 1.0. Misalnya, jika Anda menetapkan nilai minimum 0.6, reCAPTCHA akan menolak permintaan apa pun dengan 0.5 atau lebih rendah. Oleh karena itu, semakin tinggi skor yang Anda tetapkan, semakin ketat aturannya.

    Anda juga dapat mengaktifkan perlindungan terhadap bot dengan metode konfigurasi yang sama untuk tenant menggunakan Admin SDK. Untuk mengetahui informasi selengkapnya tentang cara memperbarui tenant, lihat Memperbarui tenant.

  3. Jika menggunakan Identity Platform di iOS atau Android, Anda harus mendaftarkan aplikasi dari Firebase console:

    Jika menggunakan Identity Platform di web, Anda harus menambahkan domain resmi untuk setiap domain yang menggunakan reCAPTCHA. Untuk menambahkan domain yang diotorisasi, lakukan hal berikut:

    1. Di konsol Google Cloud, buka halaman Identity Platform.

      Buka Identity Platform

    2. Buka Setelan > Keamanan.

    3. Klik Tambahkan domain.

    4. Masukkan nama domain, lalu klik Tambahkan untuk menyimpan domain.

    Penyediaan kunci reCAPTCHA dapat memerlukan waktu beberapa menit untuk diselesaikan.

  4. Jika Anda telah menetapkan penerapan ke mode audit, sebaiknya pantau metrik reCAPTCHA untuk perlindungan bot untuk memastikan bahwa alur Anda dilindungi.

Penyedia telepon

Untuk mengaktifkan perlindungan bot reCAPTCHA bagi alur autentikasi berbasis SMS, lakukan hal berikut:

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

  2. Untuk mengaktifkan perlindungan terhadap bot untuk project, gunakan Admin SDK. Dukungan reCAPTCHA tersedia di Node.js Admin SDK versi 12.7.0 dan yang lebih baru.

    Contoh:

    // Update project config with reCAPTCHA config
    const updateProjectConfigRequest = {
      recaptchaConfig: {
        phoneEnforcementState: 'ENFORCE_MODE',
        managedRules: [{ endScore: END_SCORE, action: 'BLOCK' }],
        useSmsBotScore: 'true',
      }
    }
    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 perlindungan bot untuk alur berbasis SMS, parameter ini harus ditetapkan ke AUDIT atau ENFORCE dan useSmsBotScore harus ditetapkan ke true.

      Saat mengaktifkan perlindungan terhadap bot untuk pertama kali, 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 perlindungan terhadap bot reCAPTCHA.

    • END_SCORE: skor penilaian perlindungan bot terendah yang dapat dimiliki permintaan sebelum gagal. Anda dapat menetapkan skor ini antara 0.0 dan 1.0. Misalnya, jika Anda menetapkan nilai minimum 0.6, reCAPTCHA akan menolak permintaan apa pun dengan 0.5 atau lebih rendah. Oleh karena itu, semakin tinggi skor yang Anda tetapkan, semakin ketat aturannya.

    Anda juga dapat mengaktifkan perlindungan terhadap bot dengan metode konfigurasi yang sama untuk tenant menggunakan Admin SDK. Untuk informasi selengkapnya tentang cara memperbarui tenant, lihat Memperbarui tenant.

  3. Jika menggunakan Identity Platform di iOS atau Android, Anda harus mendaftarkan aplikasi dari Firebase console:

    Jika menggunakan Identity Platform di web, Anda harus menambahkan domain yang diotorisasi untuk setiap domain yang menggunakan reCAPTCHA. Untuk menambahkan domain resmi, lakukan hal berikut:

    1. Di konsol Google Cloud, buka halaman Identity Platform.

      Buka Identity Platform

    2. Buka Setelan > Keamanan.

    3. Klik Tambahkan domain.

    4. Masukkan nama domain, lalu klik Tambahkan untuk menyimpan domain.

    Penyediaan kunci reCAPTCHA dapat memerlukan waktu beberapa menit untuk diselesaikan.

  4. Jika Anda telah menetapkan penerapan ke mode audit, sebaiknya pantau metrik reCAPTCHA untuk perlindungan bot 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. Untuk mengurangi jumlah panggilan jaringan yang dilakukan oleh SDK dan meningkatkan pengumpulan sinyal reCAPTCHA, sebaiknya konfigurasikan secara eksplisit seperti 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. Untuk mengurangi jumlah panggilan jaringan yang dilakukan oleh SDK dan membuat pengumpulan sinyal reCAPTCHA lebih efektif, sebaiknya konfigurasi secara eksplisit 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

Alur autentikasi telepon di iOS tidak didukung oleh integrasi Identity Platform dengan reCAPTCHA Enterprise API.

  1. Update ke iOS SDK versi 10.14.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. Untuk mengurangi jumlah panggilan jaringan yang dilakukan oleh SDK dan membuat pengumpulan sinyal reCAPTCHA lebih efektif, sebaiknya konfigurasi secara eksplisit, seperti 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 perlindungan terhadap bot

Sebelum menetapkan penerapan reCAPTCHA ke mode penerapan, sebaiknya gunakan mode audit dan pantau metrik reCAPTCHA yang dihasilkan project Anda untuk memastikan alur autentikasi 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. Jika penyediaan kunci reCAPTCHA gagal atau jika akun layanan yang diperlukan tidak dibuat, upaya autentikasi reCAPTCHA masih berhasil secara normal.

Pastikan autentikasi reCAPTCHA berfungsi dengan memeriksa metrik berikut yang dihasilkan project Anda ke Cloud Monitoring:

Untuk mengetahui informasi selengkapnya, lihat Memantau metrik reCAPTCHA.

Menerapkan perlindungan bot reCAPTCHA

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

Penyedia email-sandi

Untuk mengaktifkan penerapan reCAPTCHA untuk alur autentikasi email-sandi di project atau tenant, gunakan Admin SDK untuk menjalankan hal berikut:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    }]
  }
};

Penyedia telepon

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

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

Menonaktifkan perlindungan bot reCAPTCHA

Penyedia email-sandi

Untuk menonaktifkan perlindungan bot untuk alur autentikasi email-sandi, gunakan Admin SDK untuk menjalankan perintah berikut:

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

Penyedia telepon

Untuk menonaktifkan perlindungan bot untuk alur autentikasi berbasis SMS, gunakan Admin SDK untuk menjalankan perintah berikut:

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

Mengganti verdict reCAPTCHA dengan fungsi Cloud Run

Selain mengonfigurasi nilai minimum skor, Anda dapat mengganti verdict reCAPTCHA untuk token tertentu menggunakan fungsi pemblokiran fungsi Cloud Run kustom. Hal ini berguna jika skor reCAPTCHA untuk login pengguna tertentu mungkin rendah, tetapi pengguna tersebut tepercaya atau telah diverifikasi melalui cara lain, sehingga diizinkan untuk menyelesaikan login.

Untuk mempelajari lebih lanjut cara mengonfigurasi fungsi pemblokiran dengan reCAPTCHA, lihat Memperluas Firebase Authentication dengan fungsi pemblokiran Cloud Functions.

Langkah selanjutnya