Menyiapkan reCAPTCHA ekspres di server aplikasi

Dokumen ini menunjukkan cara menyiapkan reCAPTCHA Express di server aplikasi dalam lingkungan tempat integrasi JavaScript reCAPTCHA atau SDK seluler tidak memungkinkan, misalnya, perlindungan untuk endpoint API.

reCAPTCHA ekspres adalah fitur yang memungkinkan Anda membuat penilaian tanpa fitur sisi klien. reCAPTCHA ekspres 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 ke dalam log untuk analisis di lain waktu.

Sebelum memulai

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    Catat project ID Google Cloud Anda untuk digunakan nanti.

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Enable the API

  4. Buat kunci API untuk autentikasi:

    1. Di Konsol Google Cloud, buka halaman Kredensial.

      Buka Kredensial

    2. Klik Create credentials, lalu pilih API key.

    3. Catat kunci API untuk digunakan nanti.

Membuat kunci ekspres reCAPTCHA

Untuk menerapkan reCAPTCHA ekspres, buat kunci reCAPTCHA ekspres.

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. gcloud

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

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

    • 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 Kunci dan Jenis integrasi.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • DISPLAY_NAME: Nama untuk kunci. Biasanya nama situs.

    Metode HTTP dan URL: 

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

    Isi JSON permintaan: 

    
{
  "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 ekspres Anda untuk digunakan nanti.

Membuat penilaian

Untuk membuat permintaan dari server aplikasi 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 ekspres reCAPTCHA yang Anda buat untuk aplikasi.
  • 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 client hello TLS. Untuk informasi selengkapnya, lihat JA3 - Metode untuk membuat profil Klien SSL/TLS.
  • URI_NAME: Opsional. URI yang sedang 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

Isi JSON permintaan: 


{
  "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/",
    "firewallPolicyEvaluation": false,
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

Menafsirkan skor

reCAPTCHA ekspres 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 merupakan interaksi yang sah.

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

Langkah selanjutnya