Menyiapkan reCAPTCHA ekspres di server aplikasi

reCAPTCHA Express dapat disiapkan di server aplikasi jika integrasi sisi klien dengan reCAPTCHA JavaScript atau SDK seluler tidak memungkinkan, misalnya, untuk perlindungan endpoint API.

reCAPTCHA Express adalah fitur yang memungkinkan Anda membuat penilaian tanpa integrasi sisi klien atau sinyal sisi klien. reCAPTCHA Express hanya menggunakan sinyal backend untuk menghasilkan skor risiko reCAPTCHA. Anda dapat menggunakan skor risiko ini untuk memutuskan apakah akan menayangkan permintaan, mengalihkan ke halaman verifikasi, atau mencatatnya untuk analisis nanti.

Sebelum memulai

1. Di konsol Google Cloud , pada halaman pemilih project, pilih atau buat project Google Cloud .

   Peran yang diperlukan untuk memilih atau membuat project

   • Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
   • Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

   Buka pemilih project

   Catat project ID Google Cloud Anda untuk digunakan nanti.

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

3. Aktifkan reCAPTCHA Enterprise API.

   Peran yang diperlukan untuk mengaktifkan API

   Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

   Mengaktifkan API

4. Buat kunci API untuk autentikasi:

   1. Di konsol Google Cloud , buka halaman Credentials.

      Buka Kredensial

   2. Klik Buat kredensial, lalu pilih Kunci API.

   3. Catat kunci API untuk digunakan nanti.

Membuat kunci ekspres reCAPTCHA

Untuk menerapkan reCAPTCHA ekspres, buat kunci reCAPTCHA ekspres.

1. Di konsol Google Cloud , aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

2. gcloud

   Untuk membuat kunci reCAPTCHA, gunakan perintah gcloud recaptcha keys create.

   Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score.
   • DISPLAY_NAME: Nama untuk kunci. Biasanya nama situs.

   Jalankan perintah gcloud recaptcha keys create:

   Linux, macOS, atau Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME

   Respons berisi kunci reCAPTCHA yang baru dibuat.

   REST

   Untuk mengetahui informasi referensi API tentang jenis kunci dan jenis integrasi, lihat Kunci dan Jenis integrasi.

   Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score.
   • DISPLAY_NAME: Nama untuk kunci. Biasanya nama situs.
   • DEFAULT_SCORE_THRESHOLD: Untuk kunci tantangan berbasis kebijakan, parameter ini menentukan nilai minimum tantangan universal untuk kunci saat nilai minimum skor kustom tidak ditentukan. Fitur ini dalam pratinjau.
   • ACTION_SCORE_THRESHOLDS: Untuk kunci tantangan berbasis kebijakan, ini menentukan tindakan dan skor ambang yang sesuai antara 0,0 dan 1,0. Contoh, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Fitur ini dalam pratinjau.
     Catatan: Hanya skor akhir yang dihitung setelah tantangan apa pun ditampilkan dalam penilaian. Skor awal yang dihitung oleh reCAPTCHA dibandingkan dengan nilai minimum.

   Metode HTTP dan URL:

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

   Meminta isi JSON:

   
   {
     "displayName": "DISPLAY_NAME",
     "expressSettings": {}
   }
   
   

   Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

   curl

   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 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/keys"

   PowerShell

   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 POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   Anda akan melihat respons JSON seperti berikut:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "expressSettings": {
   }
   }
   
   

Catat kunci ekspres Anda untuk digunakan nanti.

Membuat penilaian

Untuk membuat permintaan dari server aplikasi Anda ke reCAPTCHA, buat penilaian menggunakan metode projects.assessments.create.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• API_KEY: Kunci API yang Anda buat untuk autentikasi.
• EXPRESS_KEY: kunci reCAPTCHA Express yang Anda buat untuk aplikasi Anda.
• USER_IP_ADDRESS: Alamat IP dalam permintaan dari perangkat pengguna yang terkait dengan peristiwa ini.
• HEADER_INFO: Opsional. Header HTTP yang dikirim klien ke server aplikasi Anda. Ini adalah array string yang berisi header permintaan dalam format `[key:value]`. Misalnya, `[key:value, key:value,...]`. Sebaiknya Anda membagikan sebanyak mungkin header dalam urutan yang diperlukan. Pastikan urutan header konsisten di semua permintaan dalam sesi yang sama.
• JA3_FINGERPRINT: Opsional. JA3 adalah sidik jari MD5 dari kolom tertentu pada paket TLS client hello. Untuk mengetahui informasi selengkapnya, lihat JA3 - A method for profiling SSL/TLS Clients.
• URI_NAME: Opsional. URI yang diakses oleh pengguna.
• USER_AGENT: Opsional. Agen pengguna yang ada dalam permintaan dari perangkat pengguna yang terkait dengan peristiwa ini.
• ACCOUNT_ID: Opsional. ID unik dan persisten untuk akun pengguna, seperti nama akun yang di-hash.

Metode HTTP dan URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

Meminta isi JSON:

{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

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

$headers = @{  }

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?key=API_KEY" | Select-Object -Expand Content

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

Menafsirkan skor

reCAPTCHA Express hanya menampilkan dua skor: 0.3 dan 0.7. 0.3 menunjukkan bahwa interaksi pengguna menimbulkan lebih banyak risiko dan kemungkinan bersifat menipu, dan 0.7 menunjukkan bahwa interaksi pengguna menimbulkan risiko rendah dan kemungkinan sah.

Jika tidak ada sinyal, reCAPTCHA Express akan menampilkan 0.7 secara default.

Langkah berikutnya

• Pelajari cara menafsirkan skor risiko.
• Pelajari cara menggunakan reCAPTCHA Express di lapisan WAF.