Menginstal kunci Universal di halaman web

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.

Kunci Universal Fraud Defense membantu melindungi aplikasi web dan endpoint API Anda dari serangan bot otomatis, penyalahgunaan kredensial, dan penipuan. Dengan menggunakan kunci Universal, Anda dapat men-deploy perlindungan di seluruh situs Anda dengan intersepsi permintaan jaringan otomatis (AutoExecute), eksekusi JavaScript manual, atau kombinasi kedua metode tersebut.

Sebelum memulai

1. Menyiapkan lingkungan Anda untuk Google Cloud Fraud Defense.

2. Buat kunci Universal.

3. Konfigurasi domain untuk kunci Universal Anda.

4. Untuk melihat kolom Status untuk endpoint yang dilindungi di konsolGoogle Cloud , pastikan Anda memiliki izin monitoring.timeSeries.list Cloud Monitoring. Izin ini disertakan dalam peran Fraud Defense yang telah ditetapkan: reCAPTCHA Enterprise Admin, reCAPTCHA Enterprise Editor, dan reCAPTCHA Enterprise Viewer.

Menginstal kunci Universal di situs Anda

Untuk menginstal kunci Universal dan membantu melindungi halaman web, Anda dapat menggunakan konfigurasi AutoExecute, penginstalan JavaScript manual, atau kedua metode tersebut secara bersamaan di berbagai endpoint menggunakan kunci Universal yang sama:

• Konfigurasi AutoExecute (direkomendasikan): Otomatis mengintersepsi permintaan jaringan asinkron ke jalur URL yang dikonfigurasi dan melampirkan token reCAPTCHA ke header permintaan.
• Penginstalan manual: Menggunakan panggilan grecaptcha.enterprise.execute() manual atau atribut tombol HTML. Anda dapat menggunakan metode ini sendiri atau bersama AutoExecute untuk permintaan jaringan yang tidak didukung AutoExecute, permintaan yang memerlukan penempatan token kustom dalam payload, atau selama migrasi inkremental ke AutoExecute.

Perhatian: Jangan mengonfigurasi panggilan AutoExecute dan manual grecaptcha.enterprise.execute() di endpoint yang sama. Tindakan ini akan memicu permintaan duplikat, meningkatkan latensi, menampilkan verifikasi CAPTCHA duplikat, dan berpotensi menyebabkan biaya penilaian duplikat.

Mengonfigurasi AutoExecute

AutoExecute dapat membantu menyederhanakan integrasi JavaScript frontend Anda dengan mengintersepsi permintaan jaringan di halaman web Anda dan menghilangkan panggilan grecaptcha.enterprise.execute() manual untuk setiap tindakan frontend.

Cara kerja AutoExecute

Skrip Fraud Defense otomatis terintegrasi dengan tindakan jaringan yang ditentukan dalam konfigurasi kebijakan kunci Universal Anda. Saat skrip mendeteksi permintaan jaringan asinkron ke jalur yang dikonfigurasi, skrip akan mencegat permintaan, memicu evaluasi risiko, dan berpotensi menampilkan tantangan CAPTCHA kepada pengguna sebelum permintaan asli dilanjutkan. Token respons yang dihasilkan akan otomatis dilampirkan ke header X-Recaptcha-Token dalam permintaan.

API jaringan yang didukung

AutoExecute hanya mengintersepsi permintaan jaringan asinkron yang dimulai oleh API berikut (termasuk framework seperti AJAX yang mengandalkannya):

Nama API	Konfigurasi waktu tunggu	Contoh penerapan
Fetch API	Tetapkan waktu tunggu menggunakan pengontrol AbortSignal.	AbortSignal.timeout(n)
XMLHttpRequest	Tetapkan waktu tunggu menggunakan properti .timeout native.	xhr.timeout = n

Praktik terbaik integrasi

• Hanya tindakan yang dipicu pengguna: AutoExecute tidak mendukung resource yang dimuat secara otomatis selama pemuatan halaman. Untuk menghindari kegagalan integrasi, hanya terapkan AutoExecute ke permintaan yang dipicu oleh interaksi pengguna yang eksplisit (misalnya, mengklik tombol login atau kirim).
• Mencegah waktu tunggu latensi: Alur verifikasi Fraud Defense terkadang dapat menyebabkan penundaan jaringan. Untuk mencegah waktu tunggu sisi klien, selalu konfigurasikan waktu tunggu permintaan eksplisit secara langsung menggunakan mekanisme yang tercantum dalam tabel.
• Hanya lindungi jalur sensitif: Tentukan protectedEndpoints hanya untuk jalur sensitif, dan gunakan nama yang bermakna untuk interaksi pengguna dalam parameter action. Hindari melindungi setiap endpoint, karena memicu Fraud Defense pada setiap permintaan backend dapat berdampak negatif pada performa. Untuk panduan selengkapnya, lihat Tindakan.

Menambahkan tag skrip ke halaman web Anda

Untuk memuat Fraud Defense di halaman web Anda, tambahkan JavaScript API dengan kunci Universal Anda dalam elemen <head></head> halaman web Anda:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Fraud Defense menggunakan bahasa browser secara default. Jika Anda ingin menentukan bahasa lain, gunakan atribut hl=LANG dalam skrip Anda. Misalnya, untuk menggunakan bahasa Prancis, tentukan hal berikut:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk Fraud Defense.

Mengonfigurasi endpoint yang dilindungi

Untuk mengonfigurasi endpoint yang dilindungi untuk kunci Universal Anda, pilih tab:

Konsol

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

   Buka Fraud Defense

2. Di toolbar konsol, pastikan project Anda muncul di pemilih resource. Jika tidak, klik pemilih resource, lalu pilih project Anda.

3. Pilih tab Keys.

   Tab Kunci memiliki dua tampilan: Kartu dan Tabel. Jika project Anda memiliki banyak kunci, hanya tampilan Table yang tersedia.

4. Di bagian reCAPTCHA keys, temukan kunci Universal yang ingin Anda konfigurasi:

   • Di tampilan Kartu, klik Detail kunci pada kartu kunci.
   • Di tampilan Table, klik nama kunci.

5. Di halaman Key details, klik tab Integration.

6. Pada langkah Add reCAPTCHA to your website, pilih tab AutoExecute (recommended).

   Opsional: Untuk melindungi endpoint tertentu secara manual, klik tab Manual untuk melihat cuplikan kode grecaptcha.enterprise.execute().

7. Di bagian Protected endpoints, klik Add endpoint untuk mengonfigurasi setiap endpoint yang ingin Anda lindungi:

   1. Di kolom Tindakan, masukkan nama untuk interaksi pengguna. Misalnya, login, register, atau add_to_cart. Untuk panduan selengkapnya, lihat Tindakan.
   2. Di kolom Path, masukkan jalur URL unik atau pola glob yang akan diintersepsi. Misalnya, /login_api, /register_api, atau /cart_api/add/*.
   3. Opsional: Untuk menambahkan endpoint lain, klik Add endpoint.

8. Klik Save untuk menyimpan endpoint yang dilindungi.

Setelah Anda menyimpan konfigurasi, kolom Status di tabel Endpoint yang dilindungi menunjukkan apakah Fraud Defense menerima traffic untuk setiap tindakan dalam 24 jam terakhir. Status traffic dapat memerlukan waktu 10 menit untuk diperbarui setelah endpoint pertama kali menerima traffic.

gcloud

Untuk memeriksa konfigurasi kebijakan saat ini untuk kunci Universal Anda, gunakan perintah gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

Untuk memperbarui konfigurasi kebijakan dengan endpoint yang dilindungi, buat file YAML (misalnya, POLICY.yaml) yang menentukan jalur dan tindakan yang dilindungi:

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Perbarui konfigurasi kunci Anda dengan file YAML menggunakan perintah gcloud alpha recaptcha policies update:

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

Catatan: Perintah gcloud alpha recaptcha policies update memperbarui seluruh kebijakan. protectedEndpointGroup atau challengeRuleGroups yang ada harus disertakan dalam file POLICY.yaml Anda agar tidak terhapus.

REST API

Untuk memperbarui konfigurasi kebijakan guna menentukan endpoint yang dilindungi 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

Metode HTTP dan URL:

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

Meminta isi JSON:

{
"clientSettings": {
  "allowedDomains": [
    "example.com"
  ],
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

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"

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" | Select-Object -Expand Content

Jika berhasil, permintaan akan menampilkan konfigurasi kebijakan yang diperbarui.

Sintaksis dan batas endpoint yang dilindungi

Anda dapat mengonfigurasi hingga 25 endpoint yang dilindungi per kunci Universal. Setiap endpoint harus memenuhi persyaratan berikut:

• action: Nama tindakan harus berisi 1 hingga 100 karakter, dan hanya menggunakan huruf, angka, garis miring (/), dan garis bawah (_).
• path (peka huruf besar/kecil): Jalur harus memenuhi kriteria berikut:
  • Unik, dimulai dengan /, dan berisi 1 hingga 200 karakter tanpa garis miring berturut-turut (//).
  • Sertakan setidaknya satu segmen non-karakter pengganti. Misalnya, tidak boleh berupa /, /*, /**, atau /*/.
  • Karakter pengganti harus menempati segmen lengkap: * cocok dengan satu segmen. Misalnya, /api/*/login atau /api/* valid; /api/login* tidak valid, dan ** cocok dengan beberapa segmen sebagai segmen akhir saja. Misalnya, /api/** valid; /api/**/login tidak valid.

Perilaku pencocokan jalur

AutoExecute mengevaluasi endpoint yang dilindungi secara berurutan dari atas ke bawah terhadap jalur URL saja. Tindakan ini mengabaikan domain, skema, dan parameter kueri tujuan. Perilaku ini memiliki implikasi praktis berikut:

• Urutan pencocokan jalur: AutoExecute menerapkan endpoint pertama yang cocok. Jika tidak ada endpoint yang cocok, AutoExecute tidak akan mengintersepsi permintaan. Tempatkan jalur tertentu sebelum pola karakter pengganti untuk menghindari bayangan rute yang lebih spesifik. Misalnya, cantumkan /mysite/login sebelum /*/login.
• Permintaan pihak ketiga: Jika alat pihak ketiga yang berjalan di halaman Anda (seperti skrip analisis atau partner) mengirim permintaan ke jalur yang cocok dengan endpoint yang dilindungi (misalnya, https://analytics.example.net/login yang cocok dengan /login), AutoExecute juga akan mencegatnya. Hal ini dapat menyebabkan latensi jaringan tambahan, metrik yang tidak akurat, atau verifikasi CAPTCHA yang tidak terduga. Untuk menghindari konflik, pastikan jalur yang dilindungi berbeda (misalnya, /auth/v1/login), atau gunakan penginstalan manual jika terjadi tabrakan jalur.
• API lintas domain: Jika API backend Anda dihosting di domain yang berbeda dengan situs Anda (misalnya, cdn.example.com versus www.example.com), AutoExecute akan berfungsi secara otomatis tanpa konfigurasi domain tambahan.

Jika pencocokan dengan domain tujuan tertentu penting untuk integrasi Anda, ajukan permintaan fitur.

Memverifikasi token di backend Anda

Di backend, dapatkan token respons dari header permintaan X-Recaptcha-Token dan buat penilaian dalam waktu dua menit.

Penting: Backend Anda harus menentukan assessment.event.expected_action (atau expectedAction di JSON) di CreateAssessmentRequest, dan harus cocok dengan tindakan yang dikonfigurasi di ProtectedEndpoint. Misalnya, jika Anda mengonfigurasi tindakan endpoint yang dilindungi menjadi login, backend Anda harus menetapkan expected_action ke login saat membuat penilaian untuk permintaan tersebut. Jika ada ketidakcocokan, hal ini menunjukkan bahwa penyerang mencoba memalsukan tindakan.

Penginstalan manual

Sebaiknya tambahkan verifikasi Fraud Defense pada interaksi pengguna yang perlu diverifikasi. Misalnya, jika Anda ingin memverifikasi tindakan pengiriman formulir, Anda perlu menambahkan verifikasi Fraud Defense pada tindakan pengiriman.

Bergantung pada tempat Anda ingin menambahkan verifikasi Fraud Defense, pilih opsi yang sesuai:

• Menambahkan verifikasi pada interaksi pengguna
• Menambahkan Pertahanan Terhadap Penipuan di tombol HTML

Menambahkan verifikasi pada interaksi pengguna

1. Untuk memuat reCAPTCHA di halaman web Anda, tambahkan JavaScript API dengan kunci Universal Anda dalam elemen <head></head> halaman web Anda:

   <head>
     <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
     ...
   </head>
   

   Fraud Defense menggunakan bahasa browser secara default. Jika Anda ingin menentukan bahasa lain, gunakan atribut hl=LANG dalam skrip Anda. Misalnya, untuk menggunakan bahasa Prancis, tentukan hal berikut:

   <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

   Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk Fraud Defense.

   Jika Anda ingin menentukan lokasi untuk badge, gunakan badge=LOCATION sebagai parameter kueri dalam tag skrip. Contoh, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Secara default, lokasi ditetapkan ke bottomright. Nilai lainnya yang mungkin digunakan adalah inline dan bottomleft.

2. Untuk menambahkan verifikasi Fraud Defense pada interaksi pengguna, lakukan hal berikut:

   1. Untuk membantu memastikan bahwa grecaptcha.enterprise.execute() berjalan setelah library Fraud Defense dimuat, gunakan grecaptcha.enterprise.ready().

   2. Panggil grecaptcha.enterprise.execute() pada setiap interaksi yang ingin Anda lindungi dengan kunci Universal. Tentukan nama yang bermakna untuk interaksi pengguna dalam parameter action. Untuk panduan selengkapnya, lihat Tindakan.

      Tips: Tambahkan panggilan execute ke tindakan sensitif seperti LOGIN, SIGNUP, PASSWORD_RESET, atau PURCHASE.

      Contoh berikut menunjukkan cara memanggil grecaptcha.enterprise.execute() pada tindakan login:

      <script>
        // Use `requestSubmit()` for extra features like browser input
        // validation.
        function onClick(e) {
          e.preventDefault();
          grecaptcha.enterprise.ready(async () => {
            const token = await grecaptcha.enterprise.execute(
              'KEY_ID',
              {action: 'LOGIN'}
            );
            // IMPORTANT: The 'token' that results from execute is an
            // encrypted response sent by Fraud Defense to
            // the end user's browser.
            // This token must be validated by creating an assessment.
            // See https://cloud.google.com/recaptcha/docs/create-assessment
          });
        }
      </script>
      

3. Setelah token dibuat, kirim token reCAPTCHA ke backend Anda dan buat penilaian dalam waktu dua menit.

   Penting: Backend Anda harus menentukan assessment.event.expected_action (atau expectedAction di JSON) di CreateAssessmentRequest, dan harus cocok dengan tindakan yang dikonfigurasi dalam panggilan execute(). Misalnya, jika Anda mengonfigurasi tindakan frontend menjadi LOGIN, backend Anda harus menetapkan expected_action ke LOGIN saat membuat penilaian untuk permintaan tersebut. Jika ada ketidakcocokan, hal ini menunjukkan bahwa penyerang mencoba memalsukan tindakan.

Menambahkan Fraud Defense di tombol HTML

1. Untuk memuat reCAPTCHA di halaman web Anda, tambahkan JavaScript API dengan kunci Universal Anda dalam elemen <head></head> halaman web Anda:

   <head>
     <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
     ...
   </head>
   

   Fraud Defense menggunakan bahasa browser secara default. Jika Anda ingin menentukan bahasa lain, gunakan atribut hl=LANG dalam skrip Anda. Misalnya, untuk menggunakan bahasa Prancis, tentukan hal berikut:

   <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

   Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk Fraud Defense.

2. Untuk menambahkan Fraud Defense pada tombol HTML, lakukan tindakan berikut:

   1. Tentukan fungsi callback untuk menangani token.

      <script>
        function onSubmit(token) {
          document.getElementById("demo-form").submit();
        }
        // Use `requestSubmit()` for extra features like browser input
        // validation.
      </script>
      

      Untuk mengetahui informasi selengkapnya, lihat metode requestSubmit().

   2. Tambahkan atribut ke tombol HTML Anda.

      <button class="g-recaptcha"
          data-sitekey="KEY_ID"
          data-callback="onSubmit"
          data-action="submit">Submit</button>
      

      Jika Anda ingin menentukan lokasi untuk badge, gunakan atribut data-badge="LOCATION" pada elemen yang memiliki class="g-recaptcha". Secara default, lokasi ditetapkan ke bottomright. Nilai lainnya yang mungkin digunakan adalah inline dan bottomleft.

   3. Saat tombol ini digunakan untuk mengirimkan formulir di situs Anda, parameter POST g-recaptcha-response akan berisi token respons.

      Catatan: Jika Anda menetapkan tombol g-recaptcha sebagai disabled, tombol tersebut akan diaktifkan saat Fraud Defense dimuat.

3. Setelah token dibuat, kirim token reCAPTCHA ke backend Anda dan buat penilaian dalam waktu dua menit.

   Penting: Backend Anda harus menentukan assessment.event.expected_action (atau expectedAction dalam JSON) di CreateAssessmentRequest, dan harus cocok dengan tindakan yang dikonfigurasi pada tombol. Misalnya, jika Anda mengonfigurasi tindakan tombol menjadi submit, backend Anda harus menetapkan expected_action ke submit saat membuat penilaian untuk permintaan tersebut. Jika ada ketidakcocokan, hal ini menunjukkan bahwa penyerang mencoba memalsukan tindakan.

Langkah berikutnya

• Untuk memicu verifikasi CAPTCHA berdasarkan aturan kustom, konfigurasikan kebijakan verifikasi.

• Untuk menilai token respons reCAPTCHA, buat penilaian.