Menyiapkan reCAPTCHA ekspres di server aplikasi

reCAPTCHA Express dapat disiapkan di server aplikasi jika integrasi sisi klien dengan JavaScript reCAPTCHA 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 tantangan, atau mencatatnya untuk analisis nanti.

Sebelum memulai

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

    Peran yang diperlukan untuk memilih atau membuat project

    • Memilih 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 Google Cloud project ID Anda untuk digunakan nanti.

  2. Pastikan penagihan diaktifkan untuk Google Cloud project 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 Google Cloud konsol, buka halaman Credentials.

      Buka Kredensial

    2. Klik Create credentials, lalu pilih API key.

    3. Catat kunci API untuk digunakan nanti.

Membuat kunci reCAPTCHA Express

Untuk menerapkan reCAPTCHA Express, buat kunci reCAPTCHA Express.

  1. Di Google Cloud konsol, 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 informasi referensi API tentang jenis kunci dan jenis integrasi, lihat Jenis 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, nilai ini menentukan nilai minimum tantangan universal untuk kunci saat nilai minimum skor kustom tidak ditentukan. Fitur ini berada dalam pratinjau.
    • ACTION_SCORE_THRESHOLDS: Untuk kunci tantangan berbasis kebijakan, nilai ini menentukan tindakan dan skor nilai minimum yang sesuai antara 0,0 dan 1,0. Misalnya, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Fitur ini berada dalam pratinjau.

    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

    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

    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 Express Anda untuk digunakan nanti.

Membuat penilaian

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

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 server Anda. Header ini adalah array string yang berisi header permintaan dalam format `[key:value]`. Misalnya, `[key:value, key:value,...]`. Sebaiknya bagikan header sebanyak mungkin dalam urutan yang diperlukan. Pastikan urutan header konsisten di semua permintaan dalam sesi yang sama.
  • JA4_FINGERPRINT: Opsional. JA4 adalah sidik jari dari kolom tertentu paket TLS Client Hello. Untuk mengetahui informasi selengkapnya, lihat Pelacakan Sidik Jari Jaringan JA4+™.
  • URI_NAME: Opsional. URI yang diakses oleh pengguna.
  • USER_AGENT: Opsional. User agent yang ada dalam permintaan dari perangkat pengguna 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"],
    "ja4": "JA4_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": []
  }
}

Menginterpretasikan 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 penipuan, sedangkan 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