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 tangguh 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—perlindungan bot reCAPTCHA. Dengan perlindungan 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.

Penting: Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih sebagai berikut:

• reCAPTCHA Enterprise
• Identity Platform

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Sebelum memulai

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

• Untuk alur autentikasi email-sandi, pastikan Anda telah mengonfigurasi login email untuk pengguna.

• Untuk alur autentikasi berbasis SMS, pastikan Anda telah melakukan aktivasi ke setidaknya salah satu hal berikut:

  • Login dengan ponsel untuk pengguna.
  • Autentikasi multi-faktor untuk aplikasi web, Android, atau iOS Anda.

Membuat akun layanan

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

Jika Anda belum membuat akun layanan atau memiliki project tambahan yang ingin dilindungi dengan reCAPTCHA, lakukan hal 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 ID project.

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

Perilaku perlindungan bot reCAPTCHA menurut penyedia

Perilaku perlindungan bot reCAPTCHA bergantung pada penyedia identitas yang Anda konfigurasi:

Penyedia email-sandi

Untuk alur autentikasi email-sandi, perlindungan bot reCAPTCHA mendukung dua mode: audit dan enforce.

Mode audit

Saat Anda menyetel penerapan sandi email 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 penerapan

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

Penyedia telepon

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Saat Anda mengaktifkan perlindungan bot untuk alur autentikasi ponsel dengan menetapkan phoneEnforcementState ke ENFORCE dan useSmsBotScore ke true, Identity Platform akan menggunakan perlindungan bot reCAPTCHA untuk verifikasi aplikasi. Jika permintaan pengguna lulus penilaian perlindungan bot, kode verifikasi SMS akan dikirim. Jika permintaan pengguna gagal dalam penilaian perlindungan bot, Identity Platform akan memblokir permintaan tersebut dan tidak akan mengirimkan pesan SMS yang berisi kode verifikasi.

Verifikasi penggantian tidak diperlukan jika perlindungan bot diaktifkan untuk alur autentikasi ponsel, dan Anda tidak perlu menyiapkan metode verifikasi tambahan untuk aplikasi Anda. Namun, sebaiknya siapkan pemverifikasi reCAPTCHA untuk aplikasi web guna memastikan reCAPTCHA v2 tersedia jika Anda memutuskan untuk menonaktifkan perlindungan bot.

Menyiapkan integrasi Identity Platform dengan reCAPTCHA Enterprise API

Untuk menyiapkan integrasi Identity Platform dengan reCAPTCHA Enterprise API, lakukan tugas berikut:

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

Untuk alur autentikasi email-sandi, sebaiknya aktifkan terlebih dahulu penerapan reCAPTCHA dalam mode audit dan pantau metrik reCAPTCHA yang dikeluarkan project Anda untuk menghindari gangguan traffic pengguna sekaligus memverifikasi bahwa alur autentikasi dilindungi. Setelah memverifikasi bahwa alur autentikasi Anda dilindungi, tetapkan perlindungan bot ke ENFORCE. Untuk alur autentikasi ponsel, aktifkan perlindungan bot dengan menetapkan phoneEnforcementState ke ENFORCE dan useSmsBotScore ke true, serta pantau metrik reCAPTCHA untuk menyesuaikan nilai minimum skor Anda.

Mengaktifkan perlindungan bot reCAPTCHA

Penting: Jangan edit atau hapus kunci reCAPTCHA bernama Key for Identity Platform integration with reCAPTCHA kecuali jika reCAPTCHA dinonaktifkan. Jika Anda melakukannya, Identity Platform tidak akan menerapkan perlindungan reCAPTCHA. Selain itu, SDK Identity Platform tidak dapat membuat token dari kunci reCAPTCHA yang Anda buat sendiri.

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 bot untuk project, gunakan Admin SDK. Dukungan reCAPTCHA tersedia di Admin SDK Node.js 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 bot 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, lihat perilaku perlindungan bot reCAPTCHA menurut penyedia.
   • 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 menggagalkan permintaan apa pun dengan nilai 0.5 atau lebih rendah. Oleh karena itu, makin tinggi skor yang Anda tetapkan, makin ketat aturannya.

   Anda juga dapat mengaktifkan perlindungan 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:

   • Untuk iOS, daftarkan setiap ID paket yang menggunakan Identity Platform
   • Untuk Android, daftarkan setiap nama paket Android yang menggunakan Identity Platform

   Jika menggunakan Identity Platform di web, Anda harus menambahkan domain yang diizinkan untuk setiap domain yang menggunakan reCAPTCHA. Untuk menambahkan domain yang diizinkan, lakukan tindakan 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 guna memastikan alur Anda dilindungi.

Penyedia telepon

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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

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

2. Untuk mengaktifkan perlindungan bot bagi 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',
       managedRules: [{
         endScore: END_SCORE,
         action: 'BLOCK'
       }],
       useSmsBotScore: true,
     }
   };
   let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
   

   Ganti END_SCORE dengan 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 menggagalkan permintaan apa pun dengan skor 0.5 atau lebih rendah. Oleh karena itu, makin tinggi skor yang Anda tetapkan, makin ketat aturannya.

   Menyetel phoneEnforcementState ke ENFORCE dan useSmsBotScore ke true akan mengaktifkan penerapan perlindungan bot untuk alur autentikasi berbasis SMS. Untuk mengetahui informasi selengkapnya tentang cara kerja penerapan penyedia telepon, lihat perilaku perlindungan bot reCAPTCHA berdasarkan penyedia.

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

   Catatan: Identity Platform tidak mendukung penggunaan autentikasi ponsel dan autentikasi multi-faktor SMS dengan beberapa tenant di platform seluler.

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

   • Untuk iOS, daftarkan setiap ID paket yang menggunakan Identity Platform
   • Untuk Android, daftarkan setiap nama paket Android yang menggunakan Identity Platform

   Jika menggunakan Identity Platform di web, Anda harus menambahkan domain yang diizinkan untuk setiap domain yang menggunakan reCAPTCHA. Untuk menambahkan domain yang diizinkan, 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. Pantau metrik reCAPTCHA untuk perlindungan bot guna memastikan alur Anda dilindungi.

Mengonfigurasi SDK klien

Konfigurasi 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 ponsel di aplikasi web tersedia di JavaScript SDK versi 11 dan yang lebih baru.

   Setelah Anda mengintegrasikan web SDK 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 Anda dan mengaktifkan perlindungan untuk penyedia yang telah Anda konfigurasi.

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

   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 perlindungan dari bot

Pantau metrik reCAPTCHA yang dikeluarkan project Anda untuk memastikan bahwa alur autentikasi dilindungi. Untuk alur autentikasi email-sandi, sebaiknya pantau metrik dalam mode audit sebelum menetapkan penerapan ke mode diterapkan. Misalnya, metrik ini dapat membantu Anda menentukan apakah Anda telah menyiapkan integrasi Identity Platform dengan reCAPTCHA Enterprise API dengan benar. Mereka juga dapat membantu Anda menyesuaikan nilai minimum skor untuk traffic pengguna Anda. Jika penyediaan kunci reCAPTCHA gagal atau jika akun layanan yang diperlukan tidak dibuat, upaya autentikasi reCAPTCHA akan tetap berhasil seperti biasa.

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

• identitytoolkit.googleapis.com/recaptcha/verdict_count: Melacak berbagai verdict yang ditampilkan oleh reCAPTCHA.
• identitytoolkit.googleapis.com/recaptcha/token_count: Melacak jumlah dan status token reCAPTCHA yang diterima oleh backend Identity Platform.
• identitytoolkit.googleapis.com/recaptcha/risk_scores: Melacak distribusi skor perlindungan bot.

Untuk mengetahui informasi selengkapnya, lihat Memantau metrik reCAPTCHA.

Menerapkan perlindungan bot reCAPTCHA untuk alur email-sandi

Untuk alur autentikasi email-sandi yang awalnya Anda konfigurasi dalam mode AUDIT, setelah memverifikasi bahwa aplikasi Anda menerima traffic pengguna yang dapat diterima, Anda dapat mengalihkan emailPasswordEnforcementState ke ENFORCE untuk memblokir permintaan yang gagal dalam penilaian reCAPTCHA. Pastikan Anda tidak mengganggu pengguna yang ada, termasuk pengguna yang mungkin menggunakan versi lama aplikasi Anda.

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

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

Menonaktifkan perlindungan dari 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 semua perlindungan reCAPTCHA ponsel, termasuk perlindungan bot, untuk alur autentikasi berbasis SMS, gunakan Admin SDK untuk menjalankan perintah berikut:

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

Jika Anda juga menggunakan SMS defense reCAPTCHA dan ingin tetap mengaktifkannya saat menonaktifkan perlindungan bot, tetapkan useSmsBotScore ke false dan biarkan phoneEnforcementState ditetapkan ke ENFORCE:

const disableBotScoreOnlyRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    useSmsBotScore: false,
    useSmsTollFraudProtection: true
  }
};

Mengganti putusan reCAPTCHA dengan fungsi Cloud Run

Selain mengonfigurasi nilai minimum skor, Anda dapat mengganti keputusan reCAPTCHA untuk token tertentu menggunakan fungsi pemblokiran untuk mengizinkan atau memblokir alur berdasarkan faktor 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.

Contoh berikut menunjukkan cara mengganti putusan reCAPTCHA menggunakan fungsi pemblokiran:

Node.js

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

Langkah berikutnya

• Aktifkan SMS defense reCAPTCHA untuk alur autentikasi berbasis SMS.
• Pelajari cara menggunakan kunci reCAPTCHA Anda sendiri.
• Pelajari lebih lanjut cara memantau metrik reCAPTCHA.
• Pelajari reCAPTCHA lebih lanjut.