Mengonfigurasi kebijakan tantangan

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

Kebijakan verifikasi memungkinkan Anda memicu verifikasi CAPTCHA secara selektif berdasarkan aturan kustom. Aturan ini menentukan kapan harus menampilkan verifikasi Fraud Defense berdasarkan skor risiko, alamat IP, agen pengguna, ASN, wilayah geografis, atau identitas bot (agen AI) yang terverifikasi.

Anda dapat menggunakan kebijakan verifikasi dengan fitur yang direkomendasikan berikut:

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

Sebelum memulai

  1. Menyiapkan lingkungan Anda untuk Google Cloud Fraud Defense.
  2. Pastikan penagihan diaktifkan untuk project Google Cloud Anda. Anda dapat mengaktifkan penagihan 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 hal berikut:

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

        Buka Fraud Defense

      2. Dalam daftar Keys, temukan kunci yang ingin Anda salin, lalu klik Copy to clipboard.

    • 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 mana 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. Mengintegrasikan 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 verifikasi menggunakan bagian challenge_rule_groups.

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

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 verifikasinya.

  4. Di halaman Key details, buka tab Policy.

  5. Di bagian Rule groups, Anda dapat melihat, menambahkan, atau mengedit aturan verifikasi 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 memperbarui 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 verifikasi.

Untuk contoh berbagai kasus penggunaan, lihat Contoh konfigurasi aturan verifikasi.

Mengonfigurasi kebijakan verifikasi

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

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: {}

Di setiap aturan verifikasi, kolom condition bersifat opsional. Jika condition tidak ditentukan atau kosong, aturan akan berlaku tanpa syarat. Selain itu, kolom challenge dan no_challenge bersifat sama-sama eksklusif, dan hanya satu dari kolom tersebut yang 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 aturan yang cocok dengan interaksi, evaluasi akan ditetapkan secara default ke penilaian standar tanpa menampilkan verifikasi, tetapi skor risiko akan dibuat untuk permintaan tersebut.

Tingkat kesulitan tantangan

Anda dapat menentukan tingkat kesulitan saat memicu tantangan. Untuk mengetahui daftar lengkap nilai tingkat 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 (+, -, /, *, %), logis (!, &&, ||), dan 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. Hilangkan awalan AS (misalnya, gunakan 12345, bukan AS12345).
region_code string Kode wilayah CLDR Unicode (berdasarkan ISO 3166-1 alpha-2) yang terkait dengan lokasi permintaan (misalnya, "US", "CA", atau "FR").
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 verifikasi Fraud Defense, Anda dapat menggunakan salah satu variabel ini untuk menghasilkan ekspresi boolean. Misalnya, score > 0.5, user_ip_address == "192.0.2.1", region_code == "US", dan user_asn == 12345 adalah ekspresi kondisi valid yang dievaluasi ke boolean. Perhatikan bahwa karena user_asn adalah jenis bilangan bulat, Anda harus menghilangkan awalan AS saat memeriksa ASN.

Fungsi berikut tersedia untuk digunakan dalam kondisi kebijakan verifikasi 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 disertakan 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 elemen x dalam daftar e 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 verifikasi

Bagian ini berisi contoh konfigurasi aturan verifikasi yang valid.

Memverifikasi semua permintaan yang memiliki skor rendah

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

Pilih verifikasi dengan friksi tinggi untuk semua permintaan dengan skor rendah

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

Menantang tindakan tertentu yang memiliki skor rendah

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

Mengonfigurasi batas aturan yang berbeda untuk tindakan yang berbeda

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

Jangan tampilkan verifikasi ke alamat IP di 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 IP yang diizinkan untuk Perlindungan dari Penipuan.

Jangan tampilkan verifikasi ke subnet alamat IP

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

Jangan tampilkan verifikasi 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 tampilkan tantangan kepada agen Google

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

Menampilkan verifikasi berdasarkan kondisi yang 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