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 terkait dengan akun mereka. MFA dapat membantu melindungi pengguna dari serangan penjejalan kredensial dan pengambilalihan akun (ATO).

MFA tersedia untuk kunci berbasis skor dan tidak tersedia untuk tombol kotak centang.

Memahami proses konfigurasi MFA

Fitur MFA reCAPTCHA Enterprise diimplementasikan bersama alur kerja reCAPTCHA Enterprise reguler.

Pada dasarnya, alur kerja MFA adalah sebagai berikut:

  1. Lengkapi alur kerja penting di situs Anda.
  2. Buat penilaian menggunakan token yang ditampilkan oleh panggilan execute() dan parameter MFA untuk mendapatkan requestToken MFA.
  3. Picu tantangan MFA dengan requestToken sesuai dengan saluran yang ingin Anda gunakan (hanya mendukung email).
  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. Menyiapkan lingkungan Anda untuk reCAPTCHA Enterprise.

  2. MFA dapat diakses setelah peninjauan keamanan. Hubungi tim penjualan kami untuk mengaktivasi situs Anda menggunakan fitur ini. Berikan informasi orientasi berikut kepada tim penjualan:

    • Nomor project Google Cloud
    • Kunci reCAPTCHA untuk melakukan aktivasi
    • QPS rata-rata (pesan email per detik)
    • QPS puncak (pesan email per detik)
    • Untuk MFA email, alamat pengirim, dan alamat email atau domain yang Anda perlukan selama pengujian
  3. Jika Anda ingin mengaktifkan fitur verifikasi email MFA, lakukan hal berikut:

    1. Di konsol Google Cloud, buka halaman reCAPTCHA Enterprise.

      Buka reCAPTCHA Enterprise

    2. Pastikan nama project Anda muncul di pemilih resource.

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

    3. Klik Setelan.

    4. Di panel Multi Factor Authentication, klik Configure.

    5. Dalam dialog Configure MFA, lakukan hal berikut:

      1. Untuk mengaktifkan verifikasi email, klik tombol Aktifkan email.
      2. Dalam kotak Nama pengirim, masukkan nama Anda.
      3. Dalam kotak Email pengirim, masukkan alamat email Anda.

    6. Klik Save.

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

Menginstrumentasikan alur kerja penting di situs Anda

Teruskan informasi yang diperlukan ke reCAPTCHA Enterprise melalui fungsi execute() untuk penilaian risiko. Fungsi execute() menampilkan promise yang diselesaikan saat pembuatan token.

Tambahkan parameter twofactor tambahan ke fungsi execute() Anda seperti yang ditunjukkan dalam kode contoh berikut:

  grecaptcha.enterprise.execute(KEY_ID, {
    action: 'login',
    twofactor: true
  }).then(token => {
    // Handle the generated token.
  });

Ganti KEY_ID dengan kunci berbasis skor yang dibuat untuk situs Anda.

Membuat penilaian

Dengan token yang dihasilkan oleh fungsi execute(), buat penilaian menggunakan Library Klien reCAPTCHA Enterprise 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 Enterprise.

    Metode autentikasi yang Anda pilih bergantung pada lingkungan tempat reCAPTCHA Enterprise disiapkan. Tabel berikut membantu Anda memilih metode autentikasi yang tepat 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 federasi identitas workload.

    Jika Anda ingin menggunakan kunci API, sebaiknya amankan kunci API dengan menerapkan pembatasan kunci API.

    Library klien

    Gunakan resource berikut:

  • Pilih ID akun stabil accountId yang tidak sering diubah oleh pengguna dan berikan untuk penilaian di metode projects.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. Ketika Anda memberikan ID lintas situs (ID yang dapat digunakan kembali di seluruh situs), reCAPTCHA Enterprise 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 terkait secara unik dengan setiap akun, Anda dapat memberikannya sebagai accountId.

    Di-hash atau dienkripsi

    Jika tidak memiliki ID pengguna internal yang secara unik terkait dengan setiap akun, Anda dapat mengubah ID stabil menjadi ID akun khusus situs yang buram. ID ini masih diperlukan untuk pelindung akun reCAPTCHA Enterprise untuk memahami pola aktivitas pengguna dan mendeteksi perilaku anomali, tetapi tidak dibagikan ke situs lain.

    Pilih ID akun stabil dan buat menjadi buram sebelum mengirim ke reCAPTCHA Enterprise dengan menggunakan enkripsi atau hashing:

    • enkripsi (direkomendasikan): enkripsi ID akun menggunakan metode enkripsi deterministik yang menghasilkan ciphertext yang 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 Enterprise 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 harus menyimpan pemetaan antara hash yang dihasilkan dan ID pengguna sehingga Anda dapat memetakan ID akun yang di-hash yang dikembalikan ke akun aslinya.

Tambahkan parameter accountId dan endpoint, seperti alamat email untuk memverifikasi dalam penilaian dalam 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 diinstal di situs Anda.
  • ACCOUNT_ID: ID untuk akun pengguna yang unik untuk situs Anda.
  • EMAIL_ID: alamat email yang akan digunakan untuk memicu permintaan verifikasi.

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

Jika pelindung akun reCAPTCHA Enterprise diaktifkan untuk project Anda, respons penilaian akan berisi informasi yang terkait dengan pelindung akun selain informasi yang terkait dengan MFA. Kolom recommended_action menunjukkan kemungkinan tindakan yang dapat Anda lakukan sebelum memicu tantangan MFA.

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 pembela akun tidak dapat membuat keputusan atas 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 telah diverifikasi untuk situs Anda di perangkat ini.
REQUEST_2FA Menunjukkan bahwa Anda memicu tantangan MFA untuk pengguna. Untuk mengetahui informasi selengkapnya, lihat respons penilaian pelindung akun.

Memicu tantangan MFA di situs Anda

Untuk menantang pengguna berdasarkan informasi yang terdapat dalam penilaian, kirim kembali 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. 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 diinstal 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 verdict yang akan diverifikasi melalui penilaian yang dibuat di backend.

  2. Buat nama sebutan channel 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 sudah 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
  }
);

Buat penilaian baru

Buat penilaian baru dengan accountId dan endpoints. Untuk mengetahui petunjuknya, lihat membuat penilaian untuk MFA.

Setelah alur kerja selesai pada klien, Anda akan menerima token baru yang dapat digunakan untuk mendapatkan verdict verifikasi yang Anda picu. Penilaian berisi stempel waktu terbaru terkait verifikasi terbaru yang berhasil, beserta status hasil sukses.

Contoh berikut menunjukkan contoh penilaian yang Anda terima saat 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 dengan 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 mengirim email ke (hanya selama pengujian).
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED Penerima ini sudah menerima terlalu banyak kode verifikasi dalam jangka waktu yang singkat.
ERROR_CUSTOMER_QUOTA_EXHAUSTED Anda telah melebihi kuota MFA yang tersedia.
ERROR_CRITICAL_INTERNAL Verifikasi tidak selesai karena terjadi error internal dalam sistem kami.
RESULT_UNSPECIFIED Tidak ada informasi tentang verifikasi terbaru (tidak pernah diverifikasi).

Langkah selanjutnya