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:
- Untuk alur autentikasi email-sandi, pastikan Anda telah mengonfigurasi login email untuk pengguna.
Untuk alur autentikasi berbasis SMS, pastikan Anda telah melakukan aktivasi untuk setidaknya salah satu hal berikut:
- Login dengan telepon untuk pengguna.
- Autentikasi multi-faktor untuk aplikasi web atau Android.
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:
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.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 IDPROJECT_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
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).
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:
Jika Anda belum melakukannya, aktifkan reCAPTCHA Enterprise API di project Anda.
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 adalahOFF
,AUDIT
, danENFORCE
. Untuk mengaktifkan perlindungan bot, parameter ini harus ditetapkan keAUDIT
atauENFORCE
. Saat Anda mengaktifkan perlindungan terhadap bot untuk pertama kali, sebaiknya tetapkan parameter ini keAUDIT
dan pastikan alur autentikasi Anda dilindungi sebelum menetapkannya keENFORCE
. 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 antara0.0
dan1.0
. Misalnya, jika Anda menetapkan nilai minimum0.6
, reCAPTCHA akan menolak permintaan apa pun dengan0.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.
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 resmi untuk setiap domain yang menggunakan reCAPTCHA. Untuk menambahkan domain yang diotorisasi, lakukan hal berikut:
Di konsol Google Cloud, buka halaman Identity Platform.
Buka Setelan > Keamanan.
Klik Tambahkan domain.
Masukkan nama domain, lalu klik Tambahkan untuk menyimpan domain.
Penyediaan kunci reCAPTCHA dapat memerlukan waktu beberapa menit untuk diselesaikan.
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:
Jika Anda belum melakukannya, aktifkan reCAPTCHA Enterprise API di project Anda.
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 adalahOFF
,AUDIT
, danENFORCE
. Untuk mengaktifkan perlindungan bot untuk alur berbasis SMS, parameter ini harus ditetapkan keAUDIT
atauENFORCE
danuseSmsBotScore
harus ditetapkan ketrue
.Saat mengaktifkan perlindungan terhadap bot untuk pertama kali, sebaiknya tetapkan parameter ini ke
AUDIT
dan pastikan alur autentikasi Anda dilindungi sebelum menetapkannya keENFORCE
. 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 antara0.0
dan1.0
. Misalnya, jika Anda menetapkan nilai minimum0.6
, reCAPTCHA akan menolak permintaan apa pun dengan0.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.
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 diotorisasi untuk setiap domain yang menggunakan reCAPTCHA. Untuk menambahkan domain resmi, lakukan hal berikut:
Di konsol Google Cloud, buka halaman Identity Platform.
Buka Setelan > Keamanan.
Klik Tambahkan domain.
Masukkan nama domain, lalu klik Tambahkan untuk menyimpan domain.
Penyediaan kunci reCAPTCHA dapat memerlukan waktu beberapa menit untuk diselesaikan.
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
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.
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
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.
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.
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.
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.
Untuk mengintegrasikan reCAPTCHA iOS SDK ke aplikasi Anda, lihat Menyiapkan lingkungan.
Pastikan
-ObjC
tercantum dalam flag penaut Anda. Buka Target > Build Settings > All > Linking dan pastikanOther Linker Flags
menampilkan-ObjC
.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:
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 terhadap bot.
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
- Aktifkan perlindungan terhadap penipuan pulsa SMS reCAPTCHA untuk alur autentikasi berbasis SMS.
- Pelajari cara menggunakan kunci reCAPTCHA Anda sendiri.
- Pelajari lebih lanjut cara memantau metrik reCAPTCHA.
- Pelajari reCAPTCHA lebih lanjut.