Menyiapkan Policy Engine dengan kunci Universal

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini menjelaskan cara mengonfigurasi Policy Engine di situs Anda menggunakan kunci Universal. Kunci universal adalah kunci baru Google Cloud Fraud Defense yang mendukung pembuatan aturan dalam Policy Engine.

Dengan Policy Engine, Fraud Defense dapat memicu verifikasi CAPTCHA secara deterministik berdasarkan aturan kebijakan kustom yang Anda konfigurasi. Aturan ini dapat memutuskan kapan harus menampilkan tantangan Pertahanan dari Penipuan berdasarkan skor risiko, alamat IP, agen pengguna, ASN, atau identitas bot (agen AI) yang terverifikasi.

Konfigurasi Fraud Defense Policy Engine menyediakan dua fitur utama:

• Integrasi AutoExecute (protected_endpoint_group): Menyederhanakan integrasi JavaScript frontend dengan memeriksa permintaan jaringan asinkron keluar secara otomatis dan melampirkan token reCAPTCHA ke permintaan tersebut, sehingga hanya tag skrip yang diperlukan di frontend Anda.
• Kebijakan tantangan (challenge_rule_groups): Menentukan apakah akan menampilkan tantangan di berbagai tindakan pengguna dan mengonfigurasi tingkat kesulitan tantangan terkait (USABILITY, BALANCE, SECURITY) menggunakan aturan berbasis CEL kustom.

Sebelum memulai

1. Siapkan lingkungan Anda untuk reCAPTCHA.

2. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

   Fraud Defense memerlukan penagihan untuk ditautkan dan diaktifkan di project agar dapat menggunakan Policy Engine. Anda dapat mengaktifkan penagihan menggunakan kartu kredit atau ID penagihan project yang ada Google Cloud . Jika Anda memerlukan bantuan terkait penagihan, hubungi Dukungan Penagihan Cloud.

Membuat Kunci universal

Bergantung pada antarmuka pilihan Anda, pilih opsi yang sesuai untuk membuat kunci Universal:

Konsol

1. Di konsol Google Cloud , buka halaman reCAPTCHA.

   Buka reCAPTCHA

2. Pastikan nama project Anda muncul di pemilih resource di bagian atas halaman.

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

3. Pilih tab Keys.
4. Klik Create key.
5. Di kolom Nama tampilan, masukkan nama tampilan untuk kunci.
6. Untuk Application type, pilih Universal.
7. Klik Create key.

Kunci yang baru dibuat akan tercantum di halaman reCAPTCHA keys.

gcloud

Untuk membuat kunci Universal menggunakan Google Cloud CLI, gunakan perintah gcloud recaptcha keys create dengan flag --universal:

gcloud recaptcha keys create --universal --display-name=DISPLAY_NAME

Respons berisi kunci Universal reCAPTCHA yang baru dibuat.

REST API

Untuk membuat kunci Universal menggunakan REST API, gunakan metode projects.keys.create dan tentukan universalSettings:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

{
  "displayName": "DISPLAY_NAME",
  "universalSettings": {}
}

Ganti kode berikut:

• PROJECT_ID: Project ID Google Cloud Anda
• DISPLAY_NAME: nama tampilan untuk kunci Anda, biasanya nama situs Anda

Respons berisi kunci Universal reCAPTCHA yang baru dibuat.

Mengonfigurasi domain untuk Policy Engine

Catatan: Untuk situs, kunci reCAPTCHA bersifat unik untuk domain dan sub-domain yang Anda tentukan. Anda dapat menentukan lebih dari satu domain jika Anda menayangkan situs dari beberapa domain. Jika Anda menentukan domain (misalnya, examplepetstore.com), Anda tidak perlu menentukan subdomainnya (misalnya, subdomain.examplepetstore.com).

Bergantung pada antarmuka pilihan Anda, pilih opsi yang sesuai untuk mengonfigurasi domain yang diizinkan untuk Kunci universal Anda:

Konsol

1. Di konsol Google Cloud , buka halaman Fraud Defense.

   Buka Fraud Defense

2. Pastikan nama project Anda muncul di pemilih resource di bagian atas halaman.

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

3. Klik tab Kunci reCAPTCHA.

4. Identifikasi Kunci universal yang ingin Anda konfigurasi, lalu klik kunci tersebut.

5. Di halaman Key details, klik Edit key.

6. Identifikasi bagian Setelan penggunaan kunci.

   Untuk melindungi kunci reCAPTCHA untuk domain dan subdomain Anda, pastikan tombol Nonaktifkan verifikasi domain dinonaktifkan.

   Menonaktifkan verifikasi domain merupakan risiko keamanan karena tidak ada batasan di situs, sehingga kunci reCAPTCHA Anda dapat diakses dan digunakan oleh siapa saja.

   Masukkan nama domain untuk situs Anda:

   1. Di bagian Daftar domain, klik Tambahkan domain.
   2. Di kolom Domain, masukkan nama domain Anda.
   3. Opsional: Untuk menambahkan domain lain, klik Tambahkan domain, lalu masukkan nama domain lain di kolom Domain. Anda dapat menambahkan hingga 250 domain.

7. Klik Simpan perubahan.

Catatan: Untuk menggunakan kebijakan di lebih dari 250 domain, klik tombol Nonaktifkan verifikasi domain. Jika verifikasi domain dinonaktifkan, Fraud Defense akan mengabaikan daftar domain, dan Anda harus melakukan verifikasi domain sendiri dengan memeriksa kolom tokenProperties.hostname di penilaian yang Anda buat.

gcloud

Untuk memperbarui domain yang diizinkan untuk kunci Universal menggunakan Google Cloud CLI, gunakan perintah gcloud alpha recaptcha policies update dan tentukan domain dalam file konfigurasi kebijakan (misalnya, POLICY.yaml):

gcloud alpha recaptcha policies update --key=KEY_ID --policy=POLICY.yaml

Catatan: Perintah gcloud alpha recaptcha policies update memperbarui seluruh kebijakan. protected_endpoint_group atau challenge_rule_groups yang ada harus disertakan dalam file POLICY.yaml agar tidak dihapus.

File POLICY.yaml harus menentukan domain yang diizinkan di bagian clientSettings:

clientSettings:
  allowedDomains:
    - DOMAIN_NAME_1
    - DOMAIN_NAME_2

Atau, untuk mengizinkan semua domain dan menonaktifkan verifikasi domain, tetapkan allowAllDomains ke true dalam file POLICY.yaml Anda:

clientSettings:
  allowAllDomains: true

Ganti kode berikut:

• KEY_ID: ID atau nama lengkap resource kunci Universal Anda
• DOMAIN_NAME_1, DOMAIN_NAME_2: nama domain situs yang diizinkan untuk menggunakan kunci

Catatan: Jika allowAllDomains disetel ke true, Fraud Defense mengabaikan daftar domain, dan Anda harus melakukan verifikasi domain sendiri dengan memeriksa kolom tokenProperties.hostname dalam penilaian yang Anda buat.

REST API

Untuk memperbarui domain yang diizinkan untuk kunci Universal menggunakan REST API, gunakan metode projects.keys.updatePolicy.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• PROJECT_ID: Project ID Google Cloud Anda
• KEY_ID: ID kunci Universal Anda
• DOMAIN_NAME_1, DOMAIN_NAME_2: nama domain situs yang diizinkan untuk menggunakan kunci

Metode HTTP dan URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains

Meminta isi JSON:

{
"clientSettings": {
  "allowedDomains": [
    "DOMAIN_NAME_1",
    "DOMAIN_NAME_2"
  ],
  "allowAllDomains": false
}
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

curl -X PATCH \
     -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/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains" | Select-Object -Expand Content

Jika berhasil, permintaan akan menampilkan konfigurasi kebijakan yang diperbarui.

Catatan: Untuk menggunakan kebijakan di lebih dari 250 domain, tetapkan allowAllDomains ke true di isi permintaan. Jika allowAllDomains disetel ke true, Fraud Defense mengabaikan daftar domain, dan Anda harus melakukan verifikasi domain sendiri dengan memeriksa kolom tokenProperties.hostname di penilaian yang Anda buat.

Langkah berikutnya

• Instal kunci Universal di halaman web.