Mengonfigurasi Autentikasi multi-faktor

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 adalah pemilik 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 diimplementasikan di atas alur kerja reCAPTCHA reguler.

Pada tingkat tinggi, alur kerja MFA adalah sebagai berikut:

1. Ukur alur kerja penting di situs Anda.
2. Buat penilaian dengan menggunakan token yang ditampilkan oleh panggilan execute() dan parameter MFA untuk mendapatkan requestToken MFA.
3. Memicu verifikasi MFA dengan requestToken sesuai dengan saluran yang ingin Anda gunakan (hanya email yang didukung).
4. Verifikasi PIN yang dimasukkan oleh pengguna akhir di situs Anda.
5. Buat penilaian baru menggunakan token yang ditampilkan dalam permintaan verifikasi.

Sebelum memulai

1. Siapkan lingkungan Anda untuk reCAPTCHA.

2. MFA dapat diakses setelah peninjauan keamanan, yang dimulai saat Anda menambahkan akun penagihan ke project Anda. Tambahkan akun penagihan untuk mengaktifkan fitur ini di situs Anda.

3. Jika Anda ingin mengaktifkan fitur verifikasi email MFA, lakukan hal berikut:

   1. Di konsol Google Cloud , buka halaman reCAPTCHA.

      Buka reCAPTCHA

   2. Pastikan nama project Anda muncul di pemilih resource.

      Jika tidak melihat nama project, klik pemilih resource, lalu pilih project Anda.

   3. Klik settingsSetelan.

   4. Di panel Multi Factor Authentication, klik Configure.

   5. Pada dialog Konfigurasi MFA, lakukan hal berikut:

      1. Untuk mengaktifkan verifikasi email, klik tombol Aktifkan email.
      2. Di kotak Nama pengirim, masukkan nama Anda.

      3. Di kotak Email pengirim, masukkan alamat email Anda.

         

   6. Klik Simpan.

4. Siapkan reCAPTCHA di situs Anda dengan menggunakan kunci berbasis skor.

Ukur 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 pembuatan token.

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 reCAPTCHA Client Libraries 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 Anda 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 accountId yang stabil dan tidak sering diubah oleh pengguna dan berikan ke penilaian dalam metode projects.assessments.create. ID akun yang 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 melanggar dan menggunakan pengetahuan tentang pola penyalahgunaan lintas situs yang terkait dengan ID ini.

  Atau, jika Anda memiliki ID pengguna 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 yang stabil menjadi ID akun spesifik per situs yang tidak transparan. ID ini tetap diperlukan agar reCAPTCHA account defender dapat memahami pola aktivitas pengguna dan mendeteksi perilaku anomali, tetapi ID ini tidak dibagikan ke situs lain.

  Pilih ID akun stabil apa pun dan buat ID tersebut menjadi buram sebelum mengirimkannya ke reCAPTCHA dengan menggunakan enkripsi atau hashing:

  • enkripsi (direkomendasikan): mengenkripsi ID akun menggunakan metode enkripsi deterministik yang menghasilkan ciphertext stabil. Untuk petunjuk mendetail, 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 satu arah, Anda perlu menyimpan pemetaan antara hash yang dihasilkan dan ID pengguna Anda agar Anda dapat memetakan ID akun yang di-hash yang dikembalikan ke akun asli.

Tambahkan parameter accountId dan endpoint, seperti alamat email yang akan diverifikasi dalam penilaian di metode projects.assessments.create.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• TOKEN: token yang ditampilkan dari panggilan grecaptcha.enterprise.execute().
• KEY_ID: kunci berbasis skor yang Anda instal di situs Anda.
• 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 -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"

$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 berhasil terbaru untuk endpoint tertentu di perangkat yang mengeluarkan token, jika ada. Objek ini juga berisi satu kolom requestToken per endpoint, yang berisi string terenkripsi. Jika Anda memutuskan untuk memicu verifikasi MFA untuk endpoint tersebut, Anda harus mengirim kembali string terenkripsi ini ke halaman web. Token permintaan berlaku selama 15 menit.

Tindakan yang disarankan

Jika Anda telah mengaktifkan Account Defender reCAPTCHA untuk project Anda, respons penilaian akan berisi informasi terkait Account Defender selain informasi terkait MFA. Kolom recommended_action menampilkan kemungkinan tindakan yang dapat Anda lakukan sebelum memicu tantangan MFA.

Contoh berikut menunjukkan contoh penilaian yang menampilkan lewati MFA sebagai tindakan yang direkomendasikan:

{
  [...],
  "accountDefenderAssessment": {
    labels: ["PROFILE_MATCH"],
    "recommended_action": "SKIP_2FA"
  }
}

Kolom recommended_action dapat memiliki salah satu nilai berikut:

Memicu tantangan MFA di situs Anda

Untuk menantang pengguna berdasarkan informasi yang ada 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 tantangan MFA, lakukan hal berikut:

1. Uji integrasi MFA.

   Picu tantangan MFA dengan panggilan ke challengeAccount() dengan memberikan nilai berikut:

   • KEY_ID: kunci berbasis skor yang Anda instal di situs Anda.
   • REQUEST_TOKEN_FROM_ASSESSMENT: nilai kolom requestToken dari 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 bagian 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, variabel newToken diteruskan ke fungsi berantai yang berisi token putusan untuk diverifikasi melalui penilaian yang dibuat di backend.

2. 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 hasil verifikasi yang Anda picu. Penilaian ini berisi stempel waktu terbaru terkait verifikasi berhasil terakhir, 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:

Langkah berikutnya

• Mendeteksi dan mencegah aktivitas penipuan terkait akun menggunakan reCAPTCHA account defender