Mengonfigurasi kebijakan tantangan

Dokumen ini menjelaskan cara mengonfigurasi kebijakan tantangan dengan integrasi Google Cloud Fraud Defense yang ada.

Kebijakan verifikasi memungkinkan Anda memicu verifikasi CAPTCHA secara selektif berdasarkan aturan kustom. Aturan ini memutuskan kapan harus menampilkan tantangan Pertahanan dari Penipuan berdasarkan skor risiko, alamat IP, agen pengguna, ASN, atau identitas bot (agen AI) terverifikasi.

Anda dapat menggunakan kebijakan tantangan dengan fitur yang direkomendasikan berikut:

  • Konfigurasi AutoExecute: Menyederhanakan integrasi JavaScript untuk aplikasi klien.
  • Tantangan: Memicu verifikasi pengguna saat diperlukan oleh aturan tantangan Anda. Fraud Defense mendukung jenis tantangan berikut:
    • Tantangan visual: Minta pengguna memilih gambar berdasarkan perintah. Secara default, tantangan visual akan dipilih saat aturan dikonfigurasi dengan opsi tantangan dipilih.
    • Tantangan audio: Meminta pengguna mengidentifikasi isyarat audio yang diucapkan sebagai alternatif aksesibilitas.
    • Tantangan kode QR: Minta pengguna memindai kode QR dengan perangkat seluler mereka untuk menyelesaikan tantangan. Kunci Universal Anda harus tercantum dalam daftar yang diizinkan untuk menggunakan fitur ini. Untuk menambahkan kunci Universal Anda ke daftar yang diizinkan, hubungi tim Perlindungan dari Penipuan di fraud-defense@google.com dan berikan kunci Universal Anda.

Sebelum memulai

  1. Siapkan lingkungan Anda untuk Google Cloud Fraud Defense.
  2. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda. Anda dapat mengaktifkan penagihan dengan menggunakan kartu kredit atau ID penagihan project Google Cloud yang ada. Jika Anda memerlukan bantuan terkait penagihan, hubungi dukungan Penagihan Cloud.

  3. Buat atau identifikasi Kunci universal untuk project Anda. Untuk membuat kunci, lihat Membuat kunci Universal. Atau, Anda dapat menyalin ID kunci Universal yang ada dengan menyelesaikan salah satu langkah berikut:

    • Untuk menyalin ID kunci yang ada dari konsol Google Cloud , lakukan langkah-langkah berikut:

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

        Buka Fraud Defense

      2. Dalam daftar kunci reCAPTCHA, temukan kunci yang ingin Anda salin, lalu klik Salin ke papan klip.

    • Untuk menyalin ID kunci yang ada menggunakan REST API, panggil metode projects.keys.list.

    • Untuk menyalin ID kunci yang ada menggunakan gcloud CLI, jalankan perintah gcloud recaptcha keys list.

  4. Rencanakan integrasi Fraud Defense dengan mengidentifikasi tindakan pengguna yang ingin Anda lindungi (seperti login, signup, atau password_reset) dan halaman di situs Anda yang memicu tindakan ini. Jika Anda menggunakan konfigurasi AutoExecute, pastikan tindakan ini konsisten dengan nama tindakan yang ditentukan dalam protected_endpoint_group.

  5. Integrasikan Fraud Defense ke halaman web Anda. Sebaiknya gunakan konfigurasi Fraud Defense AutoExecute. Untuk mengetahui petunjuk penyiapan umum, lihat Menginstal Kunci universal di situs.

Ringkasan konfigurasi kebijakan Fraud Defense

Konfigurasi kebijakan Fraud Defense memungkinkan Anda menyesuaikan perilaku perlindungan Fraud Defense. Anda dapat mengonfigurasi kebijakan tantangan menggunakan bagian challenge_rule_groups.

Anda dapat melihat dan mengupdate konfigurasi kebijakan menggunakan konsol Google Cloud , gcloud CLI, atau reCAPTCHA Enterprise REST API.

Konsol

Untuk melihat atau memperbarui konfigurasi kebijakan di konsol Google Cloud , lakukan hal berikut:

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

    Buka Fraud Defense

  2. Pastikan project Anda dipilih di pemilih resource.

  3. Di tabel reCAPTCHA keys, klik nama kunci yang ingin Anda konfigurasi kebijakan tantangannya.

  4. Di halaman Detail utama, buka tab Kebijakan.

  5. Di bagian Grup aturan, Anda dapat melihat, menambahkan, atau mengedit aturan tantangan dan ekspresi kondisi.

  6. Klik Simpan.

gcloud

Untuk memperbarui konfigurasi kebijakan kunci, jalankan perintah gcloud alpha recaptcha policies update:

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

Untuk melihat konfigurasi kebijakan saat ini untuk kunci, jalankan perintah gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

REST API

Untuk mengupdate konfigurasi kebijakan untuk kunci, panggil metode projects.keys.updatePolicy:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

Untuk melihat konfigurasi kebijakan saat ini untuk kunci, panggil metode projects.keys.getPolicy:

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

Konfigurasi kebijakan menggunakan format YAML untuk Google Cloud CLI dan format JSON untuk REST API. Untuk skema lengkap bagian challenge_rule_groups, lihat Mengonfigurasi kebijakan tantangan.

Untuk contoh kasus penggunaan yang berbeda, lihat Contoh konfigurasi aturan tantangan.

Mengonfigurasi kebijakan tantangan

Anda mengonfigurasi kebijakan tantangan dalam bagian challenge_rule_groups dari konfigurasi kebijakan Fraud Defense. Jika sudah memiliki kebijakan dengan client_settings, termasuk informasi domain, Anda dapat memperbarui kebijakan untuk menyertakan aturan kebijakan tantangan Anda.

Bagian challenge_rule_groups memiliki struktur berikut:

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

Dalam setiap aturan tantangan, kolom condition bersifat opsional. Jika condition tidak ditentukan atau kosong, aturan akan berlaku tanpa syarat. Selain itu, kolom challenge dan no_challenge bersifat eksklusif, dan tepat salah satu kolom tersebut harus ada di setiap aturan.

Urutan evaluasi aturan

Grup aturan dan aturan internalnya dievaluasi secara berurutan dari atas ke bawah. Aturan pertama yang cocok akan diterapkan. Jika tidak ada grup dan tidak ada aturan yang cocok dengan interaksi, evaluasi akan ditetapkan secara default ke penilaian standar tanpa tantangan yang ditampilkan, tetapi skor risiko akan dibuat untuk permintaan tersebut.

Tingkat kesulitan tantangan

Anda dapat menentukan tingkat kesulitan saat memicu tantangan. Untuk mengetahui daftar lengkap nilai kesulitan yang valid, lihat referensi API ChallengeSecurityPreference.

Sintaksis kondisi

Kolom condition adalah string opsional yang diformat sebagai ekspresi Common Expression Language (CEL). Jika condition tidak ditentukan atau kosong, aturan akan berlaku tanpa syarat. CEL menyediakan operator standar seperti C, termasuk operator relasional (<, <=, >, >=, ==, !=), aritmetika (+, -, /, *, %), logika (!, &&, ||), dan operator penampung ([], in). CEL mendukung jenis data primitif umum (bool, int, uint, double, string), jenis penampung dasar (lists, messages), dan konstanta (seperti true, 1, 0.5, "hello", dan [1, 2, 3]).

Dalam runtime, variabel Fraud Defense berikut dapat diakses:

Variabel Jenis Deskripsi
score double Skor bot Fraud Defense.
user_ip_address string Alamat IP (IPv4 atau IPv6) pengguna yang membuat permintaan.
user_agent string Agen pengguna dari pengguna yang membuat permintaan.
user_asn int Nomor Sistem Otonom (ASN) pengguna yang membuat permintaan. Hapus awalan AS (misalnya, gunakan 12345, bukan AS12345).
verified_bots list(Bot) Daftar crawler atau agen otomatis terverifikasi (seperti pengindeks mesin telusur, asisten penelusuran AI, dan scraper konten partner) yang telah diidentifikasi oleh Fraud Defense.

Jenis non-primitif tambahan berikut ditentukan. Untuk mengetahui daftar lengkap nilai, lihat Bot.

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

Untuk mengetahui informasi selengkapnya tentang kemungkinan nilai name, lihat referensi API Bot. Untuk mengetahui informasi selengkapnya tentang nilai enum bot_type yang valid, lihat referensi API BotType.

Dalam kebijakan tantangan Fraud Defense, Anda dapat menggunakan salah satu variabel ini untuk menghasilkan ekspresi boolean. Misalnya, score > 0.5, user_ip_address == "192.0.2.1", dan user_asn == 12345 adalah ekspresi kondisi valid yang dievaluasi ke boolean. Perhatikan bahwa karena user_asn adalah jenis bilangan bulat, Anda harus menghapus awalan AS saat memeriksa ASN.

Fungsi berikut tersedia untuk digunakan dalam kondisi kebijakan tantangan Fraud Defense:

Nama Signature Deskripsi
contains string.contains(string) -> bool Memeriksa apakah operand string berisi substring.
startsWith string.startsWith(string) -> bool Memeriksa apakah operand string dimulai dengan awalan yang ditentukan.
endsWith string.endsWith(string) -> bool Memeriksa apakah operand string diakhiri dengan akhiran yang ditentukan.
size size(string) -> int
size(list) -> int
string.size() -> int
list.size() -> int		 Menampilkan ukuran string (jumlah titik kode) atau daftar (jumlah elemen).

Fungsi pemahaman adalah gaya makro yang dibuat ke dalam CEL. Pemahaman berikut tersedia:

Nama Signature Deskripsi Contoh
has has(message.field) -> bool Memeriksa apakah kolom tersedia. has(verified_bots[0].name)
all list(A).all(A, predicate(A) -> bool) -> bool Memeriksa apakah semua elemen x dalam daftar e cocok dengan predikat p. [1, 2, 3].all(x, x > 0)
exists list(A).exists(A, predicate(A) -> bool) -> bool Memeriksa apakah ada elemen x dalam daftar e yang cocok dengan predikat p. [1, 2, 3].exists(i, i % 2 != 0)
exists_one list(A).exists_one(A, predicate(A)) -> bool Memeriksa apakah tepat satu elemen x dalam daftar e cocok dengan predikat p. [1, 2, 2].exists_one(i, i < 2)

Contoh konfigurasi aturan tantangan

Bagian ini berisi contoh konfigurasi aturan tantangan yang valid.

Menantang semua permintaan yang memiliki skor rendah

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Pilih tantangan dengan hambatan tinggi untuk semua permintaan dengan skor rendah

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

Menantang tindakan spesifik yang memiliki skor rendah

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Mengonfigurasi berbagai batas aturan untuk berbagai tindakan

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

Jangan menampilkan tantangan untuk alamat IP dalam daftar yang diizinkan

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.001", "123.255.255.002"]'
        no_challenge: {}

Catatan: Aturan ini berbeda dengan fitur Daftar yang diizinkan IP Fraud Defense.

Jangan menampilkan tantangan ke subnet alamat IP

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

Jangan menampilkan tantangan untuk permintaan dari ASN tertentu

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

Jangan tunjukkan tantangan kepada agen Google

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

Menampilkan tantangan berdasarkan kondisi kompleks

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

Langkah berikutnya