Halaman ini menjelaskan cara mengonfigurasi Autentikasi multi-faktor (MFA) yang memungkinkan Anda memverifikasi identitas pengguna dengan mengirimkan kode verifikasi melalui email. Dengan fitur ini, Anda dapat memverifikasi bahwa pengguna Anda memiliki alamat email yang dikaitkan dengan akun mereka. MFA dapat membantu melindungi pengguna Anda dari serangan credential stuffing dan pengambilalihan akun (ATO).
MFA tersedia untuk kunci berbasis skor dan tidak tersedia untuk kunci kotak centang.
Memahami proses konfigurasi MFA
Fitur MFA reCAPTCHA diterapkan di atas alur kerja reCAPTCHA reguler.
Pada tingkat tinggi, alur kerja MFA adalah sebagai berikut:
- Instrumen alur kerja penting di situs Anda.
- Buat penilaian dengan menggunakan token yang ditampilkan oleh panggilan
execute()dan parameter MFA untuk mendapatkanrequestTokenMFA. - Memicu verifikasi multi-faktor dengan
requestTokensesuai dengan saluran yang ingin Anda gunakan (hanya email yang didukung). - Verifikasi PIN yang dimasukkan oleh pengguna akhir di situs Anda.
- Buat penilaian baru menggunakan token yang ditampilkan dalam permintaan verifikasi.
Sebelum memulai
MFA dapat diakses setelah peninjauan keamanan, yang dimulai saat Anda menambahkan akun penagihan ke project. Tambahkan akun penagihan untuk melakukan aktivasi situs Anda ke fitur ini.
Jika Anda ingin mengaktifkan fitur verifikasi email MFA, lakukan langkah berikut:
Di konsol Google Cloud, buka halaman reCAPTCHA.
Pastikan nama project Anda muncul di pemilih resource.
Jika tidak melihat nama project, klik pemilih resource, lalu pilih project Anda.
Klik Setelan.
Di panel Multi Factor Authentication, klik Configure.
Di dialog Configure MFA, lakukan hal berikut:
- Untuk mengaktifkan verifikasi email, klik tombol Aktifkan email.
- Di kotak Nama pengirim, masukkan nama Anda.
Di kotak Email pengirim, masukkan alamat email Anda.
Klik Simpan.
Siapkan reCAPTCHA di situs Anda menggunakan kunci berbasis skor.
Menginstrumentasikan alur kerja penting di situs Anda
Teruskan informasi yang diperlukan ke reCAPTCHA melalui
fungsi execute() untuk penilaian risiko. Fungsi execute() menampilkan promise yang diselesaikan setelah token dibuat.
Tambahkan parameter twofactor tambahan ke fungsi execute()
seperti yang ditunjukkan dalam contoh kode berikut:
grecaptcha.enterprise.execute(KEY_ID, {
action: 'login',
twofactor: true
}).then(token => {
// Handle the generated token.
});
Ganti KEY_ID dengan kunci berbasis skor yang Anda buat untuk situs Anda.
Membuat penilaian
Dengan token yang dihasilkan oleh fungsi execute(), buat penilaian menggunakan Library Klien reCAPTCHA atau REST API dari backend Anda.
Dokumen ini menunjukkan cara membuat penilaian untuk MFA menggunakan REST API. Untuk mempelajari cara membuat penilaian menggunakan Library Klien, lihat Membuat penilaian untuk situs.
Sebelum membuat penilaian, lakukan hal berikut:
Siapkan autentikasi ke reCAPTCHA.
Metode autentikasi yang Anda pilih bergantung pada lingkungan tempat reCAPTCHA disiapkan. Tabel berikut membantu Anda memilih metode autentikasi yang sesuai dan antarmuka yang didukung untuk menyiapkan autentikasi:
Lingkungan Antarmuka Metode autentikasi Google Cloud - REST
- Library klien
Gunakan akun layanan terlampir. Lokal atau penyedia cloud lain REST Gunakan kunci API atau Workload identity federation. Jika Anda ingin menggunakan kunci API, sebaiknya amankan kunci API dengan menerapkan pembatasan kunci API.
Library klien Gunakan resource berikut:
- Untuk Python atau Java, gunakan kunci API atau Workload identity federation.
Jika Anda ingin menggunakan kunci API, sebaiknya amankan kunci API dengan menerapkan pembatasan kunci API.
- Untuk bahasa lain, gunakan Workload identity federation.
Pilih ID akun
accountIdyang stabil dan tidak sering diubah oleh pengguna dan berikan ke penilaian dalam metodeprojects.assessments.create. ID akun stabil ini harus memiliki nilai yang sama untuk semua peristiwa yang terkait dengan pengguna yang sama. Anda dapat memberikan hal berikut sebagai ID akun:ID pengguna
Jika setiap akun dapat dikaitkan secara unik dengan nama pengguna, alamat email, atau nomor telepon yang stabil, Anda dapat menggunakannya sebagai
accountId. Saat Anda memberikan ID lintas situs tersebut (ID yang dapat digunakan kembali di seluruh situs), reCAPTCHA menggunakan informasi ini untuk meningkatkan perlindungan bagi akun pengguna Anda berdasarkan model lintas situs dengan menandai ID akun yang melakukan penyalahgunaan dan menggunakan pengetahuan tentang pola penyalahgunaan lintas situs yang terkait dengan ID ini.Atau, jika Anda memiliki User-ID internal yang dikaitkan secara unik dengan setiap akun, Anda dapat memberikannya sebagai
accountId.Di-hash atau dienkripsi
Jika tidak memiliki ID pengguna internal yang secara unik dikaitkan dengan setiap akun, Anda dapat mengubah ID stabil menjadi ID akun spesifik per situs yang buram. ID ini masih diperlukan agar reCAPTCHA account defender dapat memahami pola aktivitas pengguna dan mendeteksi perilaku yang tidak normal, tetapi tidak dibagikan di situs lain.
Pilih ID akun yang stabil dan buat buram sebelum dikirim ke reCAPTCHA dengan menggunakan enkripsi atau hashing:
enkripsi (direkomendasikan): mengenkripsi ID akun menggunakan metode enkripsi deterministik yang menghasilkan ciphertext yang stabil. Untuk petunjuk selengkapnya, lihat mengenkripsi data secara deterministik. Jika memilih enkripsi simetris daripada hashing, Anda tidak perlu menyimpan pemetaan antara ID pengguna dan ID pengguna buram yang sesuai. Dekripsi ID buram yang ditampilkan oleh reCAPTCHA untuk mengubahnya menjadi ID pengguna.
hashing: sebaiknya lakukan hashing pada ID akun menggunakan metode SHA256-HMAC dengan salt kustom pilihan Anda. Karena hash hanya bersifat satu arah, Anda perlu mempertahankan pemetaan antara hash yang dihasilkan dan ID pengguna agar dapat memetakan ID akun yang di-hash yang ditampilkan kembali ke akun asli.
Tambahkan parameter accountId dan endpoint, seperti alamat email untuk
diverifikasi dalam penilaian di metode projects.assessments.create.
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Google Cloud Anda.
- TOKEN: token yang ditampilkan dari panggilan
grecaptcha.enterprise.execute(). - KEY_ID: kunci berbasis skor yang Anda instal di situs.
- ACCOUNT_ID: ID untuk akun pengguna yang unik untuk situs Anda.
- EMAIL_ID: alamat email yang permintaan verifikasinya perlu dipicu.
Metode HTTP dan URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Isi JSON permintaan:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"userInfo": {
"accountId": "ACCOUNT_ID"
}
}
"accountVerification": {
"endpoints": [{
"emailAddress": "EMAIL_ID",
}]
}
}
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json,
dan jalankan perintah berikut:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"
PowerShell
Simpan isi permintaan dalam file bernama request.json,
dan jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content
Anda akan melihat respons JSON seperti berikut:
{
[...],
"accountVerification": {
"endpoints": [{
"emailAddress": "foo@bar.com",
"requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv",
"lastVerificationTime": "",
}],
"latestVerificationResult": "RESULT_UNSPECIFIED"
}
}
Penilaian ini berisi tanggal dan waktu verifikasi terbaru yang berhasil
untuk endpoint tertentu di perangkat yang menerbitkan token, jika ada. File ini juga
berisi satu kolom requestToken per endpoint, yang berisi string
terenkripsi. Jika Anda memutuskan untuk memicu tantangan MFA untuk endpoint tersebut, Anda harus
mengirim string terenkripsi ini kembali ke halaman web. Token permintaan berlaku
selama 15 menit.
Tindakan yang disarankan
Jika Anda mengaktifkan reCAPTCHA account defender
untuk project, respons penilaian akan berisi informasi terkait
account defender selain informasi terkait MFA. Kolom
recommended_action menampilkan kemungkinan tindakan yang dapat Anda lakukan sebelum
memicu verifikasi multi-faktor.
Contoh berikut menunjukkan contoh penilaian yang menunjukkan lewati MFA sebagai tindakan yang direkomendasikan:
{ [...], "accountDefenderAssessment": { labels: ["PROFILE_MATCH"], "recommended_action": "SKIP_2FA" } }
Kolom recommended_action dapat memiliki salah satu nilai berikut:
| Nilai | Deskripsi |
|---|---|
RECOMMENDED_ACTION_UNSPECIFIED |
Menunjukkan bahwa pelindung akun tidak dapat membuat penilaian untuk permintaan ini. |
SKIP_2FA |
Menunjukkan bahwa pelindung akun menganggap aman untuk melewati MFA untuk penilaian ini. Hal ini biasanya berarti bahwa pengguna baru-baru ini diverifikasi untuk situs Anda di perangkat ini. |
REQUEST_2FA |
Menunjukkan bahwa Anda memicu tantangan MFA untuk pengguna. Untuk informasi selengkapnya, lihat respons penilaian Account Defender. |
Memicu verifikasi MFA di situs Anda
Untuk menantang pengguna berdasarkan informasi yang terdapat dalam penilaian, kirim requestToken MFA untuk endpoint yang ingin Anda verifikasi dari penilaian kembali ke halaman web.
Picu tantangan MFA dengan panggilan ke challengeAccount().
Fungsi challengeAccount() menampilkan promise yang diselesaikan setelah
tantangan selesai, atau ditolak jika terjadi error atau waktu tunggu habis.
Setelah selesai, token baru yang berisi informasi yang diperbarui akan dibuat,
yang kemudian dikirim untuk penilaian.
Untuk memicu verifikasi multi-faktor, lakukan hal berikut:
Uji integrasi MFA.
Memicu tantangan MFA dengan panggilan ke
challengeAccount()dengan memberikan nilai berikut:- KEY_ID: kunci berbasis skor yang Anda instal di situs.
- REQUEST_TOKEN_FROM_ASSESSMENT: nilai kolom
requestTokendari respons penilaian. - CONTAINER_HTML_COMPONENT_ID: ID komponen HTML tempat tantangan verifikasi harus dirender. Jika Anda tidak menentukan parameter ini, tantangan akan dirender dalam overlay di atas halaman.
Contoh berikut menunjukkan cara memicu tantangan MFA dengan panggilan ke
challengeAccount():grecaptcha.enterprise.challengeAccount(KEY_ID, { 'account-token': REQUEST_TOKEN_FROM_ASSESSMENT, 'container': CONTAINER_HTML_COMPONENT_ID }).then(newToken => { // Handle the new token. });Jika permintaan
challengeAccount()berhasil, komponen HTML akan ditampilkan untuk memasukkan PIN yang diterima. Setelah PIN yang benar dimasukkan, variabelnewTokenditeruskan ke fungsi berantai yang berisi token verdict untuk diverifikasi melalui penilaian yang dibuat di backend.Buat nama sebutan verifikasi dan mulai tantangan dengan parameter berikut:
// Initialize verification handle. const verificationHandle = grecaptcha.enterprise.eap.initTwoFactorVerificationHandle( KEY_ID, REQUEST_TOKEN_FROM_ASSESSMENT ); // Call the challenge API. verificationHandle.challengeAccount().then( (challengeResponse) => { if (challengeResponse.isSuccess()) { // Handle success: This means displaying an input for the end user to // enter the PIN that they received and then call the `verifyAccount(pin)` // method. } else { // Handle API failure } });
Memverifikasi kode MFA dari halaman web
Setelah mendapatkan PIN dari pengguna akhir, Anda harus memvalidasi apakah PIN tersebut benar atau tidak.
Untuk memvalidasi PIN, panggil verificationHandle.verifyAccount() dengan PIN
yang dimasukkan oleh pengguna akhir.
verificationHandle.verifyAccount(pin).then(
(verifyResponse) => {
if (verifyResponse.isSuccess()) {
// Handle success: Send the result of `verifyResponse.getVerdictToken()`
// to the backend in order to determine if the code was valid.
} else {
// Handle API failure
}
},
(error) => {
// Handle other errors
}
);
Membuat penilaian baru
Buat penilaian baru dengan accountId dan endpoints. Untuk mengetahui petunjuknya, lihat
membuat penilaian untuk MFA.
Setelah alur kerja selesai di klien, Anda akan menerima token baru yang dapat digunakan untuk mendapatkan verdict verifikasi yang Anda picu. Penilaian ini berisi stempel waktu terbaru terkait verifikasi terbaru yang berhasil, beserta status hasil berhasil.
Contoh berikut menunjukkan contoh penilaian yang Anda terima setelah membuat penilaian baru menggunakan token baru yang diperoleh dari situs:
{ [...], "accountVerification": { "endpoints": [{ "emailAddress": "foo@bar.com", "requestToken": "tplIUFvvJUIpLaOH0hIVj2H71t5Z9mDK2RhB1SAGSIUOgOIsBv", "lastVerificationTime": "2020-03-23 08:27:12 PST", }], "latestVerificationResult": "SUCCESS_USER_VERIFIED" } }
Kolom latestVerificationResult dapat menampilkan status yang berbeda seperti yang tercantum dalam
tabel berikut:
| Status hasil verifikasi | Deskripsi |
|---|---|
| SUCCESS_USER_VERIFIED | Pengguna berhasil diverifikasi. |
| ERROR_USER_NOT_VERIFIED | Pengguna gagal dalam tantangan verifikasi. |
| ERROR_SITE_ONBOARDING_INCOMPLETE | Situs Anda tidak diaktivasi dengan benar untuk menggunakan fitur ini. |
| ERROR_RECIPIENT_NOT_ALLOWED | Penerima ini tidak disetujui untuk menerima email (hanya selama pengujian). |
| ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED | Penerima ini telah menerima terlalu banyak kode verifikasi dalam waktu singkat. |
| ERROR_CUSTOMER_QUOTA_EXHAUSTED | Anda telah melampaui kuota MFA yang tersedia. |
| ERROR_CRITICAL_INTERNAL | Verifikasi tidak selesai karena error internal dalam sistem kami. |
| RESULT_UNSPECIFIED | Tidak ada informasi tentang verifikasi terbaru (belum pernah diverifikasi). |