Mengintegrasikan reCAPTCHA Enterprise untuk WAF dengan Cloudflare

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini menunjukkan cara mengintegrasikan reCAPTCHA Enterprise untuk WAF dengan Cloudflare.

Untuk menyelesaikan integrasi, Anda harus mengimplementasikan satu atau beberapa fitur reCAPTCHA Enterprise untuk WAF, membuat kebijakan firewall reCAPTCHA, dan berintegrasi dengan Cloudflare dengan men-deploy dan mengonfigurasi aplikasi Cloudflare Worker serverless.

Sebelum memulai

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

   Buka pemilih project

   Catat ID project Google Cloud Anda untuk digunakan nanti.

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

   Catatan: Uji coba gratis tidak ditagih.

3. Aktifkan API reCAPTCHA Enterprise.

   Mengaktifkan API

4. Buat kunci API untuk autentikasi:

   1. Di konsol Google Cloud, buka halaman Credentials.

      Buka Kredensial

   2. Klik Create credentials, lalu pilih API key.
   3. Catat kunci API untuk digunakan nanti.

5. Rencanakan bagaimana Anda ingin mengimplementasikan fitur reCAPTCHA Enterprise untuk WAF guna melindungi situs Anda.

   1. Pilih satu atau beberapa fitur WAF yang paling cocok dengan kasus penggunaan Anda.
   2. Identifikasi halaman yang ingin Anda lindungi.
   3. Pilih jenis fitur WAF yang ingin Anda terapkan pada halaman yang diidentifikasi.
   4. Identifikasi kondisi untuk mengelola akses pengguna.
   5. Pahami komponen kebijakan firewall reCAPTCHA dan atributnya yang membantu Anda membuat kebijakan firewall reCAPTCHA. Misalnya, lihat Contoh kebijakan firewall reCAPTCHA.

6. Buat atau pilih akun Cloudflare dengan kemampuan Cloudflare Worker.

7. Buat atau pilih situs Cloudflare.

8. Download paket reCAPTCHA untuk Cloudflare recaptcha_cloudflare_client_0.0.2.tar.gz.

Mengimplementasikan fitur reCAPTCHA Enterprise untuk WAF

Bergantung pada persyaratan, Anda dapat menggunakan satu atau beberapa fitur reCAPTCHA Enterprise untuk WAF dalam satu aplikasi.

Jika ingin menggunakan lebih dari satu fitur, Anda harus membuat kunci reCAPTCHA untuk setiap fitur tersebut dan menggunakannya di aplikasi Anda. Misalnya, jika ingin menggunakan token tindakan reCAPTCHA dan halaman tantangan reCAPTCHA, Anda harus membuat kunci token tindakan dan kunci halaman tantangan, lalu menggunakannya di aplikasi Anda.

token tindakan

Anda harus menjalankan reCAPTCHA Enterprise di halaman web Anda untuk membuat token tindakan. Setelah reCAPTCHA Enterprise membuat token tindakan, Anda akan melampirkan token tindakan tersebut ke header permintaan yang telah ditetapkan di mana pun Anda perlu melindungi tindakan pengguna, seperti checkout. Secara default, token tindakan berlaku selama 30 menit, tetapi dapat bervariasi bergantung pada traffic. Anda harus memasang token tindakan ke header permintaan yang telah ditentukan sebelum masa berlaku token berakhir, agar cloudflare dapat mengevaluasi atribut token.

Untuk mengimplementasikan token tindakan reCAPTCHA, lakukan hal berikut:

1. Buat kunci token tindakan untuk situs Anda.

   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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score atau checkbox.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci.

     Tentukan beberapa domain sebagai daftar yang dipisahkan koma. Opsional: Tentukan --allow-all-domains untuk menonaktifkan verifikasi domain.

     Menonaktifkan verifikasi domain merupakan risiko keamanan karena tidak ada pembatasan di situs, sehingga kunci reCAPTCHA Anda dapat diakses dan digunakan oleh siapa saja.

   • WAF_FEATURE: Nama fitur WAF. Tentukan action-token.
   • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan cloudflare untuk cloudflare.

   Jalankan perintah gcloud recaptcha keys create:

   Linux, macOS, atau Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score atau checkbox.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci.

     Tentukan beberapa domain sebagai daftar yang dipisahkan koma. Opsional: Tentukan --allow-all-domains untuk menonaktifkan verifikasi domain.

     Menonaktifkan verifikasi domain merupakan risiko keamanan karena tidak ada pembatasan di situs, sehingga kunci reCAPTCHA Anda dapat diakses dan digunakan oleh siapa saja.

   • WAF_FEATURE: Nama fitur WAF. Tentukan action-token.
   • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan cloudflare untuk cloudflare.

   Metode HTTP dan URL:

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

   Isi JSON permintaan:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

   curl

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini 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 CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini 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,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "ACTION_TOKEN"
   
   }
   }
   
   

   Catat kunci token tindakan untuk digunakan di lain waktu.

2. Integrasikan JavaScript reCAPTCHA di halaman web Anda dengan kunci token tindakan yang Anda buat. Untuk mendapatkan petunjuk, lihat dokumen yang sesuai dengan jenis integrasi kunci token tindakan Anda.
   • Untuk jenis integrasi SCORE, lihat Mengintegrasikan kunci berbasis skor dengan frontend.
   • Untuk jenis integrasi CHECKBOX, lihat Merender widget reCAPTCHA di frontend.
3. Setelah Anda menerima token dari reCAPTCHA Enterprise, lampirkan token ke header permintaan yang telah ditetapkan dalam format berikut:

    X-Recaptcha-Token: value-of-your-action-token
   

   Anda dapat menggunakan bahasa seperti XHR, Ajax, atau Fetch API untuk melampirkan token ke header permintaan yang telah ditentukan.

   Contoh skrip berikut menunjukkan cara melindungi tindakan execute dan melampirkan token ke header permintaan yang telah ditentukan menggunakan JavaScript + XHR:

   
     <script>
       src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_KEY"></script>
   
       <script>
       function onSuccess(action_token) {
            const xhr = new XMLHttpRequest();
            xhr.open('GET','YOUR_URL', false);
            // Attach the action-token to the predefined request header
            xhr.setRequestHeader("X-Recaptcha-Token", action_token);
            xhr.send(null);
          }
          function onError(reason) {
            alert('Response promise rejected: ' + reason);
          grecaptcha.enterprise.ready(function () {
            document.getElementById("execute-button").onclick = () => {
              grecaptcha.enterprise.execute('ACTION_TOKEN_KEY', {
              }).then(onSuccess, onError);
            };
          });
         }
       </script>
   
     

token sesi

JavaScript reCAPTCHA menetapkan token sesi reCAPTCHA sebagai cookie di browser pengguna akhir setelah penilaian. Browser pengguna akhir melampirkan cookie dan memuat ulang cookie selama JavaScript reCAPTCHA tetap aktif.

Untuk memberikan token sesi sebagai cookie, instal kunci token sesi di minimal salah satu halaman web Anda yang dijelajahi pengguna akhir sebelum halaman yang perlu dilindungi. Misalnya, jika Anda ingin melindungi halaman checkout, instal kunci token sesi di halaman beranda atau halaman produk.

Anda dapat menyertakan JavaScript reCAPTCHA di halaman web dengan mengonfigurasi file wrangler.toml saat menginstal paket reCAPTCHA untuk Cloudflare atau menginstal kunci sesi di halaman web Anda. Menyertakan reCAPTCHA JavaScript dari Cloudflare akan mengintegrasikan reCAPTCHA Enterprise menggunakan kunci token sesi tanpa perlu menginstal kunci secara manual di halaman web Anda.

Anda dapat menggunakan cookie ini untuk melindungi permintaan berikutnya dan pemuatan halaman dari pengguna akhir di domain tertentu. Token sesi valid selama 30 menit secara default. Namun, jika pengguna akhir tetap berada di halaman tempat Anda mengimplementasikan token sesi, reCAPTCHA Enterprise akan memperbarui token sesi secara berkala untuk mencegah masa berlaku token tersebut habis.

Instal token sesi di setiap halaman yang perlu dilindungi reCAPTCHA Enterprise. Sebaiknya lindungi setiap halaman dengan reCAPTCHA Enterprise dan gunakan aturan Google Cloud Armor untuk menerapkan akses di semua halaman, kecuali halaman pertama yang dijelajahi pengguna akhir.

Berikut adalah contoh token sesi reCAPTCHA:

   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

Untuk mengimplementasikan token sesi reCAPTCHA, lakukan hal berikut:

1. Buat kunci token sesi untuk situs Anda.

   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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci.

     Tentukan beberapa domain sebagai daftar yang dipisahkan koma. Opsional: Tentukan --allow-all-domains untuk menonaktifkan verifikasi domain.

     Menonaktifkan verifikasi domain merupakan risiko keamanan karena tidak ada pembatasan di situs, sehingga kunci reCAPTCHA Anda dapat diakses dan digunakan oleh siapa saja.

   • WAF_FEATURE: Nama fitur WAF. Tentukan session-token.
   • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan cloudflare untuk cloudflare.

   Jalankan perintah gcloud recaptcha keys create:

   Linux, macOS, atau Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci.

     Tentukan beberapa domain sebagai daftar yang dipisahkan koma. Opsional: Tentukan --allow-all-domains untuk menonaktifkan verifikasi domain.

     Menonaktifkan verifikasi domain merupakan risiko keamanan karena tidak ada pembatasan di situs, sehingga kunci reCAPTCHA Anda dapat diakses dan digunakan oleh siapa saja.

   • WAF_FEATURE: Nama fitur WAF. Tentukan session-token.
   • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan cloudflare untuk cloudflare.

   Metode HTTP dan URL:

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

   Isi JSON permintaan:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

   curl

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini 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 CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini 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,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "SESSION_TOKEN"
   
   }
   }
   
   

   Catat kunci token sesi Anda untuk digunakan nanti.

   Jika Anda ingin memasukkan JavaScript reCAPTCHA dari Cloudflare, lewati langkah berikutnya dan konfigurasi wranger.toml.

2. Tambahkan kunci token sesi dan waf=session ke JavaScript reCAPTCHA.

   Contoh skrip berikut menunjukkan cara menerapkan token sesi di halaman web:

   
   <!DOCTYPE html>
   <html lang="en">
   <head>
    <meta charset="UTF-8">
    <title>reCAPTCHA WAF Session Token</title>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=SESSION_TOKEN_KEY&waf=session" async defer></script>
    <body></body>
   </head>
   </html>
   
   

halaman-tantangan

Saat Anda menerapkan halaman tantangan reCAPTCHA, reCAPTCHA Enterprise akan dialihkan ke halaman interstisial yang menentukan apakah verifikasi CAPTCHA perlu ditampilkan kepada pengguna atau tidak. Oleh karena itu, tantangan CAPTCHA mungkin tidak terlihat oleh semua pengguna.

Untuk mengimplementasikan halaman tantangan reCAPTCHA, lakukan hal berikut:

1. Buat kunci halaman tantangan untuk situs Anda.

   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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan invisible.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci. Tentukan --allow-all-domains.
   • WAF_FEATURE: Nama fitur WAF. Tentukan challenge-page.
   • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan cloudflare untuk cloudflare.

   Jalankan perintah gcloud recaptcha keys create:

   Linux, macOS, atau Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan invisible.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci. Tentukan --allow-all-domains.
   • WAF_FEATURE: Nama fitur WAF. Tentukan challenge-page.
   • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan cloudflare untuk cloudflare.

   Metode HTTP dan URL:

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

   Isi JSON permintaan:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

   curl

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini 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 CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini 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,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
     "integrationType": "INVISIBLE",
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "CHALLENGE_PAGE"
   
   }
   }
   
   

   Catat kunci halaman tantangan untuk digunakan nanti.

2. Untuk mengalihkan pengguna ke halaman tantangan reCAPTCHA dan menerima token reCAPTCHA, buat kebijakan firewall dengan tindakan redirect di halaman yang dilindungi.

ekspres

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Untuk mengimplementasikan perlindungan ekspres reCAPTCHA WAF, buat kunci ekspres.

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka 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 sesi.

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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci. Tentukan --allow-all-domains.
   • WAF_FEATURE: Nama fitur WAF. Tentukan express.
   • WAF_SERVICE: Nama penyedia layanan WAF.

   Jalankan perintah gcloud recaptcha keys create:

   Linux, macOS, atau Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   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.
   • INTEGRATION_TYPE: Jenis integrasi. Tentukan score.
   • DOMAIN_NAME: Domain atau subdomain situs yang diizinkan untuk menggunakan kunci. Tentukan --allow-all-domains.
   • WAF_FEATURE: Nama fitur WAF. Tentukan express.
   • WAF_SERVICE: Nama penyedia layanan WAF.

   Metode HTTP dan URL:

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

   Isi JSON permintaan:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

   curl

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini 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 CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini 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,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "EXPRESS"
   
   }
   }
   
   

   Rekam kunci ekspres untuk digunakan di lain waktu.

Integrasi dengan Cloudflare

Untuk menggunakan kebijakan firewall reCAPTCHA, Anda harus men-deploy dan mengonfigurasi aplikasi serverless Cloudflare Worker.

Sebelum memulai proses integrasi, lakukan hal berikut:

1. Buat CLOUDFLARE_API_TOKEN, lalu pilih template Edit Cloudflare Workers. Rekam token API untuk digunakan di lain waktu.

2. Dapatkan ID akun Cloudflare API Anda dan catat untuk digunakan di lain waktu.

Menginstal paket reCAPTCHA untuk Cloudflare

1. Download dan instal paket reCAPTCHA untuk Cloudflare:

   1. Di konsol Google Cloud, aktifkan Cloud Shell.

      Aktifkan Cloud Shell

      Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka 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 sesi.

   2. Instal paket wrangler:

       npm install -g wrangler
      

   3. Download paket reCAPTCHA untuk Cloudflare:

      wget --load-cookies /tmp/cookies.txt https://dl.google.com/recaptchaenterprise/cloudflare_client/releases/recaptcha_cloudflare_client_0.0.2.tar.gz -O recaptcha_cloudflare_client_0.0.2.tar.gz && rm -rf /tmp/cookies.txt
      

   4. Ekstrak paket reCAPTCHA untuk Cloudflare:

      tar -xvzf recaptcha_cloudflare_client_0.0.2.tar.gz
      

2. Dalam file wrangler.toml, konfigurasikan variabel berikut di bagian vars:

   • GCP_API_KEY: kunci Google Cloud API yang Anda buat untuk autentikasi.
   • GCP_PROJECT_NUMBER: nomor project Google Cloud Anda.
   • RECAPTCHA_EXPRESS_SITE_KEY: kunci ekspres jika Anda menggunakan perlindungan ekspres reCAPTCHA WAF.
   • RECAPTCHA_SESSION_SITE_KEY: kunci token sesi jika Anda menggunakan token sesi reCAPTCHA.
   • RECAPTCHA_ACTION_SITE_KEY: kunci token tindakan jika Anda menggunakan token tindakan reCAPTCHA.
   • RECAPTCHA_CHALLENGE_SITE_KEY: kunci halaman tantangan jika Anda menggunakan halaman tantangan reCAPTCHA.
   • RECAPTCHA_JS_INSTALL: URL halaman tempat Anda ingin pekerja Cloudflare menginstal JavaScript reCAPTCHA menggunakan kunci token sesi. Tentukan jalur sebagai pola glob dan gunakan ; sebagai pembatas. Opsi ini hanya tersedia untuk token sesi reCAPTCHA.

   • RECAPTCHA_ASSESSMENT_CALL: URL halaman tempat Anda ingin pekerja Cloudflare memanggil reCAPTCHA API untuk menilai skor reCAPTCHA dan melakukan tindakan yang dikonfigurasi dalam kebijakan firewall. Tentukan jalur sebagai pola glob dan gunakan ; sebagai pembatas.

     Catatan: Jalur yang Anda tentukan dalam variabel ini harus cocok dengan jalur yang ditentukan dalam aturan kebijakan firewall.

3. Deploy aplikasi:

   wrangler deploy
   

Mengonfigurasi rute Cloudflare ke aplikasi Worker

1. Login ke dasbor Cloudflare, lalu pilih akun Anda.
2. Di menu navigasi, klik Workers & Pages, lalu pilih aplikasi Pekerja Anda.
3. Klik tab Pemicu, lalu klik Tambahkan rute.
4. Pada dialog Tambahkan rute, masukkan jalur halaman web Anda yang perlu dilindungi reCAPTCHA Enterprise, pilih zona yang sesuai, lalu klik Tambahkan rute.

Membuat kebijakan firewall reCAPTCHA

Anda harus membuat kebijakan firewall yang menentukan aturan untuk setiap halaman yang ingin dilindungi di situs Anda. Anda dapat membuat kebijakan firewall dengan satu atau beberapa fitur reCAPTCHA Enterprise untuk WAF.

Di kebijakan firewall reCAPTCHA, tambahkan aturan sesuai urutan prioritas yang diinginkan. Aturan pertama memiliki urutan tertinggi. Anda juga dapat mengurutkan ulang prioritas menggunakan ReorderFirewallPoliciesRequest. Untuk permintaan masuk, jika suatu kondisi kebijakan cocok dengan jalur yang ditentukan, penyedia layanan WAF Anda akan mengimplementasikan tindakan yang telah ditentukan dan aturan berikutnya tidak akan dievaluasi.

1. Berdasarkan fitur yang Anda pilih, lakukan tindakan berikut:
   • Identifikasi jalur yang ingin Anda lindungi.
   • Identifikasi kondisi untuk mengizinkan, mengalihkan, atau memblokir akses.
   • Memprioritaskan aturan.
2. Pahami komponen kebijakan firewall dan atributnya.

3. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka 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 sesi.

4. Untuk mengganti gcloud CLI agar dapat mengakses reCAPTCHA Enterprise API versi pratinjau publik, jalankan perintah berikut:

       gcloud config set api_endpoint_overrides/recaptchaenterprise https://public-preview-recaptchaenterprise.googleapis.com/
       

5. Untuk membuat kebijakan firewall reCAPTCHA, gunakan perintah gcloud recaptcha firewall-policies create:

   Di kebijakan firewall reCAPTCHA, tambahkan aturan sesuai urutan prioritas yang diinginkan. Anda harus menambahkan aturan dengan prioritas tertinggi terlebih dahulu. Untuk permintaan masuk, saat suatu kondisi kebijakan cocok untuk jalur yang ditentukan, penyedia layanan WAF Anda akan mengimplementasikan tindakan yang telah ditentukan dan aturan berikutnya tidak dievaluasi. Aturan defaultnya adalah mengizinkan akses.

      gcloud recaptcha firewall-policies create \
         --actions=ACTION \
         --condition=CONDITION \
         --description=DESCRIPTION \
         --path=PATH
   
     

   Berikan nilai berikut:

   • ACTION: Tindakan yang harus dilakukan penyedia layanan WAF Anda untuk permintaan masuk. Objek ini dapat berisi maksimal satu tindakan terminal, yaitu tindakan yang memaksa respons. Tentukan salah satu tindakan berikut:
     • allow: mengizinkan akses ke halaman yang diminta. Ini adalah tindakan terakhir.
     • block: menolak akses ke halaman yang diminta. Ini adalah tindakan terakhir.
     • redirect: mengalihkan permintaan pengguna yang masuk ke halaman tantangan reCAPTCHA. Ini adalah tindakan terakhir.
     • substitute: menayangkan halaman yang berbeda selain halaman yang diminta untuk permintaan pengguna yang bersifat menipu. Ini adalah tindakan terakhir.
     • set_header: menetapkan header kustom dan memungkinkan permintaan pengguna masuk untuk dilanjutkan ke backend. Backend kemudian dapat memicu perlindungan yang disesuaikan. Ini adalah tindakan non-terminal.
   • CONDITION: ekspresi kondisional CEL (Common Expression Language) yang menentukan apakah kebijakan firewall reCAPTCHA berlaku untuk permintaan pengguna yang masuk. Jika kondisi ini bernilai true dan jalur yang diminta cocok dengan pola jalur, tindakan terkait akan dijalankan oleh penyedia layanan WAF. String kondisi diperiksa untuk mengetahui ketepatan sintaksis CEL saat pembuatan. Untuk mengetahui informasi selengkapnya tentang definisi bahasa, definisi bahasa CEL.
   • DESCRIPTION: deskripsi tentang apa yang ingin dicapai oleh kebijakan firewall reCAPTCHA. Deskripsi harus berisi maksimal 256 karakter UTF-8.
   • PATH: jalur yang menerapkan kebijakan firewall reCAPTCHA. Ini harus ditentukan sebagai pola glob. Untuk mengetahui informasi selengkapnya tentang glob, lihat halaman manual.

   Setelah berhasil mengeksekusi perintah, output yang mirip dengan berikut akan ditampilkan:

        Created [100].
      

   Contoh berikut membuat kebijakan firewall reCAPTCHA untuk memblokir penargetan traffic untuk `/example/page.html` jika skornya kurang dari 0,1.

      gcloud recaptcha firewall-policies create \
        --description="example policy" \
        --path="/example/page.html" \
        --condition="recaptcha.score < 0.1" \
        --actions="block"
      

Langkah selanjutnya

• Mengelola kebijakan firewall.