Aktifkan reCAPTCHA Enterprise

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

Integrasi Identity Platform dengan reCAPTCHA Enterprise membuat penilaian reCAPTCHA Enterprise atas nama Anda untuk memvalidasi permintaan pengguna. Untuk informasi harga, lihat harga reCAPTCHA Enterprise.

Ringkasan

Saat Anda mengonfigurasi integrasi Identity Platform dengan reCAPTCHA Enterprise, Identity Platform akan menyediakan kunci situs reCAPTCHA Enterprise berbasis skor di project Anda untuk Anda. Saat pengguna mengakses aplikasi atau situs Anda menggunakan salah satu operasi berikut, SDK Klien akan memuat reCAPTCHA Enterprise:

Operasi	Metode
Login dengan email dan sandi	`signInWithPassword`
Pendaftaran email dan sandi	`signUpPassword`
Login dengan link email	`getOobCode`
Reset sandi	`getOobCode`

reCAPTCHA kemudian memberikan sinyal risiko ke Identity Platform yang menilai risiko permintaan berdasarkan konfigurasi dan toleransi risiko Anda.

Untuk mengetahui informasi selengkapnya, lihat Ringkasan reCAPTCHA Enterprise.

Sebelum memulai

Mengonfigurasi login email untuk pengguna.

Membuat akun layanan

Sebelum mengaktifkan reCAPTCHA Enterprise, Anda harus membuat akun layanan untuk setiap project yang akan menggunakan reCAPTCHA dan memberi setiap akun layanan akses ke reCAPTCHA Enterprise. Hal ini memungkinkan Identity Platform mengelola kunci reCAPTCHA atas nama Anda.

Untuk membuat akun layanan, lakukan hal berikut:

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.

Beri akun layanan akses ke reCAPTCHA Enterprise:

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

Ganti kode berikut:

PROJECT_ID: the project ID
PROJECT_NUMBER: nomor akun project

Aktifkan reCAPTCHA Enterprise

reCAPTCHA memiliki dua mode yang dapat membantu Anda melindungi pengguna:

Audit: Jika diaktifkan, Identity Platform akan membuat satu atau beberapa kunci reCAPTCHA Enterprise 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 atau tidak.
Penerapan: Jika diaktifkan, Identity Platform akan membuat satu atau beberapa kunci reCAPTCHA Enterprise 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 Enterprise.

Untuk mengaktifkan reCAPTCHA Enterprise, lakukan hal berikut:

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

Aktifkan integrasi Identity Platform dengan reCAPTCHA Enterprise untuk project menggunakan Admin SDK. Dukungan reCAPTCHA Enterprise tersedia di Node.js admin SDK versi 11.7.0 dan yang lebih baru.

Contoh:

// Get project config
const getProjectConfig = () => {
  getAuth().projectConfigManager().getProjectConfig()
  .then((response) => {
    console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error getting project config:', error);
  });
}

// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      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);
  });
}

Aktifkan integrasi Identity Platform dengan reCAPTCHA Enterprise untuk tenant menggunakan SDK admin. Contoh:

// Update tenant with reCAPTCHA config
const updateTenantRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'AUDIT',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};
const updateTenantWithRecaptchaConfig = () => {
  getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
  .then((response) => {
    console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
  }).catch((error) => {
    console.log('Error updating the tenant:', error);
  });
}

Ganti kode berikut:

TENANT_ID: ID tenant

Jika menggunakan Identity Platform di platform Apple atau Android, Anda harus mendaftarkan aplikasi dari Firebase console:
- Untuk platform Apple, 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 diberi otorisasi 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.
Proses penyediaan kunci situs dapat memerlukan waktu beberapa menit. Untuk memastikan alur Anda terlindungi, periksa metrics.

Mengonfigurasi SDK Klien

Konfigurasikan SDK Klien sesuai dengan platform aplikasi Anda.

Web

Update ke SDK web versi terbaru. Dukungan reCAPTCHA Enterprise tersedia di JavaScript SDK versi 9.20.0 dan yang lebih baru. Setelah Anda mengintegrasikan web SDK dengan aplikasi Anda, Web SDK akan otomatis mengambil konfigurasi reCAPTCHA Enterprise dan melindungi penyedia yang telah Anda konfigurasi.

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 Auth
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

Update ke Android SDK versi 31.5.0 atau yang lebih baru. Dukungan reCAPTCHA Enterprise memerlukan API level 19 (KitKat) atau versi yang lebih tinggi, dan Android 4.4 atau yang lebih tinggi. Setelah Anda mengintegrasikan Android SDK dengan aplikasi, Android SDK akan otomatis mengambil konfigurasi reCAPTCHA Enterprise dan melindungi penyedia yang telah Anda konfigurasi.
Tambahkan aturan build berikut ke bagian dependensi file build.gradle level aplikasi:
```
implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
```
Pastikan Anda menggunakan reCAPTCHA SDK versi 18.4.0 atau yang lebih baru.

Untuk mengurangi jumlah panggilan jaringan yang dilakukan oleh SDK dan untuk membuat pengumpulan sinyal reCAPTCHA lebih efektif, sebaiknya konfigurasikan secara eksplisit seperti berikut:

Kotlin:

// Initialize Firebase Auth
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 Auth
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

Update ke iOS SDK versi 10.14.0 atau yang lebih baru. Setelah Anda mengintegrasikan iOS SDK dengan aplikasi Anda, SDK ini akan otomatis mengambil konfigurasi reCAPTCHA Enterprise dan melindungi penyedia yang telah Anda konfigurasi.
Untuk mengintegrasikan reCAPTCHA iOS SDK ke aplikasi Anda, lihat Menyiapkan lingkungan Anda.
Pastikan -ObjC tercantum dalam tanda penaut. Buka Target > Build Settings > All > Linking dan pastikan Other Linker Flags menampilkan -ObjC.

Untuk mengurangi jumlah panggilan jaringan yang dilakukan oleh SDK dan membuat pengumpulan sinyal reCAPTCHA lebih efektif, sebaiknya Anda mengonfigurasinya secara eksplisit, seperti berikut:

Swift:

// Initialize Firebase Auth
try await Auth.auth().initializeRecaptchaConfig()

Objective-C:

// Initialize Firebase Auth
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Auth initialization finished
}];

Metrik reCAPTCHA Enterprise

Setelah Anda mengaktifkan reCAPTCHA Enterprise, pantau metrik reCAPTCHA yang dihasilkan project Anda untuk memastikan bahwa alur autentikasi terlindungi. Jika penyediaan kunci situs reCAPTCHA gagal atau jika akun layanan yang diperlukan tidak dibuat, autentikasi reCAPTCHA akan gagal dibuka.

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

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

Melacak berbagai verdict yang ditampilkan oleh reCAPTCHA Enterprise. Verdict akan dibuat jika token tersedia. Anda dapat memfilter verdict berikut:

PASSED: Menunjukkan bahwa permintaan tertentu diizinkan saat penerapan diaktifkan.
FAILED_AUDIT: Menunjukkan bahwa permintaan tertentu ditolak saat mode audit reCAPTCHA diaktifkan.
FAILED_ENFORCE: Menunjukkan bahwa permintaan tertentu ditolak saat mode penerapan reCAPTCHA diaktifkan.
CLIENT_TYPE_MISSING: Menunjukkan bahwa permintaan tertentu tidak memiliki jenis klien saat penerapan reCAPTCHA diaktifkan. Hal ini biasanya terjadi jika permintaan dikirim menggunakan versi SDK Klien yang sudah tidak berlaku dan tidak memiliki dukungan reCAPTCHA.
KEYS_MISSING: Menunjukkan bahwa permintaan tertentu tidak dapat diverifikasi karena ketidakmampuan untuk mengambil atau membuat kunci reCAPTCHA yang valid ketika penerapan reCAPTCHA diaktifkan.

Untuk mengubah rentang skor guna mengubah rasio verdict yang lulus hingga gagal, lihat Mengaktifkan reCAPTCHA Enterprise.

`identitytoolkit.googleapis.com/recaptcha/token_count`

Melacak jumlah dan status token reCAPTCHA Enterprise yang diterima oleh backend Identity Platform. Anda dapat memfilter status berikut:

VALID: Menunjukkan bahwa token reCAPTCHA yang diteruskan valid.
EXPIRED: Menunjukkan bahwa token reCAPTCHA yang diteruskan telah habis masa berlakunya. Token yang habis masa berlakunya dapat menunjukkan masalah atau penyalahgunaan jaringan klien.
DUPLICATE: Menunjukkan bahwa token reCAPTCHA yang diteruskan merupakan duplikat. Token duplikat dapat menunjukkan masalah atau penyalahgunaan jaringan klien.
INVALID: Menunjukkan bahwa token reCAPTCHA yang diteruskan tidak valid. Token yang tidak valid dapat mengindikasikan adanya penyalahgunaan.
MISSING: Menunjukkan bahwa token reCAPTCHA tidak ada dalam permintaan yang diberikan. Token yang tidak ada mungkin menunjukkan aplikasi klien yang sudah usang.
UNCHECKED: Menunjukkan bahwa token reCAPTCHA tidak diperiksa karena verdict CLIENT_TYPE_MISSING atau KEYS_MISSING.

Jika aplikasi berhasil diluncurkan kepada pengguna, Anda akan melihat traffic dengan token yang valid. Jumlah token yang valid cenderung sebanding dengan jumlah pengguna yang menggunakan aplikasi Anda yang telah diupdate.

`identitytoolkit.googleapis.com/recaptcha/risk_scores`

Melacak distribusi skor reCAPTCHA. Hal ini dapat membantu Anda menentukan rentang skor optimal untuk konfigurasi Anda.

Gunakan metrik ini untuk menentukan apakah Anda dapat mengaktifkan penerapan. Anda harus mempertimbangkan hal berikut sebelum mengaktifkan penerapan:

Jika sebagian besar permintaan terbaru memiliki token yang valid dan rasio verdict PASSED hingga FAILED_AUDIT atau FAILED_ENFORCE dapat diterima untuk kasus bisnis Anda, pertimbangkan untuk mengaktifkan penerapan.
Jika sebagian besar permintaan terbaru kemungkinan berasal dari klien yang sudah tidak berlaku, sebaiknya tunggu lebih banyak pengguna untuk mengupdate aplikasi mereka sebelum mengaktifkan penerapan. Menerapkan integrasi Identity Platform dengan reCAPTCHA Enterprise akan merusak versi aplikasi sebelumnya yang tidak terintegrasi dengan reCAPTCHA Enterprise.

Untuk melihat metrik ini, lakukan tindakan berikut:

Di Konsol Google Cloud, buka halaman Metrics Explorer.

Buka Metrics Explorer
Dari bagian Select a metric, masukkan Identity Toolkit Tenant. Jika menggunakan multi-tenancy, Anda dapat melihat metrik untuk setiap tenant, serta project induk, dengan mengosongkan tenant_name.

Aktifkan penerapan

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

Untuk mengaktifkan penerapan reCAPTCHA untuk project atau tenant, gunakan Admin SDK untuk menjalankan perintah berikut:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

Nonaktifkan reCAPTCHA Enterprise

Untuk menonaktifkan reCAPTCHA Enterprise, gunakan Admin SDK untuk menjalankan hal berikut:

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

Mengganti verdict reCAPTCHA Enterprise dengan Cloud Functions

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

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

Pemecahan masalah

Pengguna tidak dapat login, mendaftar, atau mereset sandi mereka

Pengguna mungkin menggunakan versi aplikasi yang sudah usang. Jika Anda belum menyediakan versi terupdate aplikasi yang menggunakan SDK Klien, segera nonaktifkan mode penerapan. Jika tidak, minta pengguna untuk mengupdate aplikasi mereka.

Atau, pengguna mungkin diblokir berdasarkan konfigurasi Anda saat ini. Coba langkah berikut untuk mengatasinya:

Pertimbangkan konfigurasi yang lebih permisif dengan menyesuaikan. Skor kunci reCAPTCHA.
Minta pengguna untuk mencoba perangkat, browser, atau jaringan lain.
Kembali ke mode audit dan pantau metrik sebelum mengaktifkan kembali mode penerapan.