Integrasi dengan Google Cloud Armor untuk aplikasi seluler

Dokumen ini menunjukkan cara mengintegrasikan fitur WAF dari reCAPTCHA Enterprise dengan Google Cloud Armor di aplikasi seluler.

Untuk menyelesaikan integrasi, Anda harus menerapkan satu atau beberapa fitur reCAPTCHA Enterprise untuk WAF dan mengonfigurasi kebijakan keamanan Google Cloud Armor. Namun, Anda hanya dapat mengimplementasikan token tindakan reCAPTCHA untuk berintegrasi dengan Google Cloud Armor di aplikasi seluler.

Sebelum memulai

  1. Aktifkan reCAPTCHA Enterprise API.

    Enable the API

  2. Identifikasi tindakan yang ingin Anda lindungi.

Mengimplementasikan token tindakan reCAPTCHA

Anda harus menjalankan reCAPTCHA Enterprise di aplikasi seluler 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 menambahkan token tindakan ke header permintaan yang telah ditentukan sebelum masa berlaku token berakhir, agar Google Cloud Armor dapat mengevaluasi atribut token.

Untuk mengimplementasikan token tindakan reCAPTCHA, lakukan hal berikut:

  1. Buat kunci token tindakan untuk aplikasi seluler Anda.

    Konsol

    1. Di konsol Google Cloud, buka halaman reCAPTCHA Enterprise.

      Buka reCAPTCHA Enterprise

    2. Pastikan nama project Anda muncul di pemilih resource di bagian atas halaman.

      Jika tidak melihat nama project, klik pemilih resource, lalu pilih project Anda.

    3. Klik Create key.

    4. Di kolom Nama tampilan, masukkan nama tampilan untuk kunci.
    5. Bergantung pada jenis aplikasi yang ingin Anda buatkan kunci reCAPTCHA untuk WAF, lakukan tindakan yang sesuai:

      6. Membuat kunci reCAPTCHA untuk WAF untuk aplikasi iOS

      Sebaiknya buat satu kunci reCAPTCHA per aplikasi iOS.

      1. Dari menu Pilih jenis platform, pilih Aplikasi iOS.
        1. Di bagian Daftar ID paket iOS, klik Tambahkan ID paket iOS.

        2. Di kolom ID Paket, masukkan nama ID paket iOS Anda.

        3. Opsional: Untuk menambahkan ID paket tambahan, klik Add iOS bundle ID dan masukkan nama ID paket iOS Anda di kolom Bundle ID.

        4. Opsional: Berikan Apple Developer settings.

          Sebaiknya berikan data ini karena memungkinkan reCAPTCHA Enterprise memberikan skor risiko yang lebih akurat untuk traffic Anda.

          Masukkan informasi berikut:

          • Kunci pribadi (.p8): Kunci ini dibuat di Apple Developer Center di bagian Certificates, Identifiers & Profiles.
          • Key identifier: ID kunci developer Apple (string 10 karakter).
          • Team ID: ID tim Apple (string 10 karakter) yang memiliki profil penyediaan yang digunakan untuk membuat aplikasi Anda.
        5. Luaskan Bundle ID verification and key type.
          1. Untuk membuat kunci reCAPTCHA untuk WAF, lakukan tindakan berikut:
            1. Aktifkan tombol Firewall aplikasi web (WAF).
            2. Dari menu Layanan, pilih Cloud Armor.
            3. Dari menu Feature, pilih Action token.
          2. Untuk melindungi kunci reCAPTCHA untuk ID paket Anda, pastikan tombol Nonaktifkan verifikasi ID paket dinonaktifkan.

          3. Untuk lingkungan non-produksi, jika Anda ingin menentukan skor yang ingin ditampilkan oleh kunci saat penilaian dibuat untuk itu, lakukan hal berikut:

            1. Klik tombol This is a testing key.
            2. Di kotak Score, tentukan skor antara 0 hingga 1.0.
        6. Klik Create key.

          7. Kunci yang baru dibuat akan tercantum di halaman kunci reCAPTCHA.

      Membuat kunci reCAPTCHA bagi WAF untuk aplikasi Android

      1. Dari menu Pilih jenis platform, pilih Aplikasi Android.
      2. Di bagian Android package list, klik Add Android package.

      3. Di kolom Android package, masukkan nama paket Android Anda.

      4. Opsional: Untuk menambahkan paket tambahan, klik Add Android package, lalu masukkan nama paket Android lainnya di kolom Android package.
      5. Luaskan Verifikasi nama paket, distribusi aplikasi, dan kunci pengujian.
        1. Untuk membuat kunci reCAPTCHA untuk WAF, lakukan tindakan berikut:
          1. Aktifkan tombol Firewall aplikasi web (WAF).
          2. Dari menu Layanan, pilih Cloud Armor.
          3. Dari menu Feature, pilih Action token.
        2. Untuk memastikan bahwa kunci reCAPTCHA hanya digunakan dalam aplikasi Anda, nonaktifkan tombol Nonaktifkan verifikasi nama paket.
        3. Jika ingin membuat kunci untuk aplikasi yang tersedia di app store lain selain Google Play Store, aktifkan Dukung aplikasi yang didistribusikan di luar Google Play Store.

        4. Untuk lingkungan non-produksi, jika Anda ingin menentukan skor yang ingin ditampilkan oleh kunci saat penilaian dibuat untuk itu, lakukan hal berikut:

          1. Klik tombol This is a testing key.
          2. Di kotak Score, tentukan skor antara 0 hingga 1.0.
      6. Klik Create key.

        7. Kunci yang baru dibuat akan tercantum di halaman kunci reCAPTCHA.

    gcloud (iOS)

    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.
    • BUNDLE_IDs: ID paket iOS aplikasi yang diizinkan untuk menggunakan kunci. Tentukan beberapa ID paket sebagai daftar yang dipisahkan koma.
    • WAF_FEATURE: Nama fitur WAF. Tentukan action-token.
    • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan CA untuk Google Cloud Armor.

    Jalankan perintah gcloud recaptcha keys create:

    Linux, macOS, atau Cloud Shell

    
gcloud recaptcha keys create \
--display-name=DISPLAY_NAME  \
--ios --bundle-ids=BUNDLE_IDs \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    
gcloud recaptcha keys create `
--display-name=DISPLAY_NAME  `
--ios --bundle-ids=BUNDLE_IDs `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    
gcloud recaptcha keys create ^
--display-name=DISPLAY_NAME  ^
--ios --bundle-ids=BUNDLE_IDs ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

    Respons berisi kunci reCAPTCHA yang baru dibuat.

    gcloud (Android)

    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.
    • PACKAGE_NAMES: Nama paket Android dari aplikasi yang diizinkan untuk menggunakan kunci. Tentukan beberapa nama paket sebagai daftar yang dipisahkan koma.
    • WAF_FEATURE: Nama fitur WAF. Tentukan action-token.
    • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan CA untuk Google Cloud Armor.

    Jalankan perintah gcloud recaptcha keys create:

    Linux, macOS, atau Cloud Shell

    
gcloud recaptcha keys create \
--display-name=DISPLAY_NAME  \
--android --package-names=PACKAGE_NAMES \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    
gcloud recaptcha keys create `
--display-name=DISPLAY_NAME  `
--android --package-names=PACKAGE_NAMES `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    
gcloud recaptcha keys create ^
--display-name=DISPLAY_NAME  ^
--android --package-names=PACKAGE_NAMES ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

    Respons berisi kunci reCAPTCHA yang baru dibuat.

    REST (iOS)

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • DISPLAY_NAME: Nama untuk kunci. Biasanya nama aplikasi.
    • BUNDLE_IDs: ID paket iOS aplikasi yang diizinkan untuk menggunakan kunci. Tentukan beberapa ID paket sebagai daftar yang dipisahkan koma.
    • WAF_FEATURE: Nama fitur WAF. Tentukan action-token.
    • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan CA untuk Google Cloud Armor.

    Metode HTTP dan URL: 

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

    Isi JSON permintaan: 

    {
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
 "allowedBundleIds": "BUNDLE_IDS"
 },
   'wafSettings': "  {
       "wafService": "CA",
 "wafFeature": "ACTION_TOKEN"
  }
 }

    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/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT",
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
    "allowAllBundleIds": false,
    "allowedBundleIds": [
        BUNDLE_IDS
    ]
  },
  "labels": {},
  "wafSettings": {
      "wafService": "CA",
      "wafFeature": "ACTION_TOKEN"
  }
}

    REST (Android)

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • DISPLAY_NAME: Nama untuk kunci. Biasanya nama aplikasi.
    • PACKAGE_NAMES: Nama paket Android dari aplikasi yang diizinkan untuk menggunakan kunci. Tentukan beberapa nama paket sebagai daftar yang dipisahkan koma.
    • WAF_FEATURE: Nama fitur WAF. Tentukan action-token.
    • WAF_SERVICE: Nama penyedia layanan WAF. Tentukan CA untuk Google Cloud Armor.

    Metode HTTP dan URL: 

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

    Isi JSON permintaan: 

    {
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
  "allowedPackageNames":"PACKAGE_NAMES"
 },
   'wafSettings': "  {
       "wafService": "CA",
 "wafFeature": "ACTION_TOKEN"
  }
 }

    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/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy",
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
      "allowAllPackageNames": false,
      "allowedPackageNames": [
          PACKAGE_NAMES
      ],
      "supportNonGoogleAppStoreDistribution": false
  },
  "labels": {},
  "wafSettings": {
      "wafService": "CA",
      "wafFeature": "ACTION_TOKEN"
  }
}

  2. Integrasikan SDK seluler reCAPTCHA Enterprise di aplikasi seluler Anda dengan kunci token tindakan yang Anda buat. Untuk mendapatkan petunjuk, lihat dokumen yang sesuai dengan jenis aplikasi seluler Anda.

  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

    Kode contoh berikut menunjukkan cara melampirkan token:

    Android

    Kode contoh di Java

    
// This example shows how to send an HTTP request to the backend server
// attached with the reCAPTCHA token in the header.
//
// @param serverUrl: the URL of the backend server.
// @param rceToken: reCAPTCHA token that is attached to the header of the
// HTTP request.

public static void sendRequestToServerWithRceToken(
    String serverUrl, String rceToken) throws JSONException, IOException {
 URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl));
 HttpURLConnection connection = (HttpURLConnection) url.openConnection();
 connection.setRequestProperty("X-Recaptcha-Token", rceToken);

 try {
    String requestBody = "['']";
    sendRequest(connection, requestBody, "AccessWithRceToken", "GET");
 } finally {
    connection.disconnect();
 }
}

private static void sendRequest(
    HttpURLConnection connection, String requestString, String requestName, String action)
    throws IOException {
 connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS);
 connection.setReadTimeout(HTTP_READ_TIMEOUT_MS);
 connection.setRequestProperty("Content-type", CONTENT_TYPE);
 connection.setRequestProperty(
    "Content-Length", Integer.toString(Utf8.encodedLength(requestString)));
 connection.setRequestMethod(action);
 connection.setDoOutput(true);
 connection.connect();
 try (OutputStream postStream = connection.getOutputStream()) {
    postStream.write(requestString.getBytes(UTF_8));
 }

 int responseCode = connection.getResponseCode();
 String response = connection.getResponseMessage();
 if (responseCode != HttpURLConnection.HTTP_OK) {
    throw new IOException(
       String.format(
          "Failed to complete request.\nResponse code:%s\nError Detail:\n%s",
          responseCode, response));
 }
}

    iOS

    Kode contoh di Swift

    
// This example shows how to send an HTTP request to the backend server
// attached with the reCAPTCHA token in the header.
// @param serverUrl: the URL of the backend server.
// @param rceToken: reCAPTCHA token that is attached to the header of
// the HTTP request.

 public static func accessWafServer(rceToken: String, serverUrl: String)
    async throws -> String
 {
    let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl)
    var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET")
    request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token")

    let data = try await HttpHelper.getDataFromServer(request)

    return String(decoding: data, as: UTF8.self)
 }

Mengonfigurasi kebijakan keamanan Google Cloud Armor

Setelah menerapkan fitur reCAPTCHA Enterprise untuk WAF, Anda harus mengonfigurasi kebijakan keamanan Google Cloud Armor yang mengevaluasi token reCAPTCHA Enterprise untuk pengelolaan bot.

Untuk mempelajari cara mengonfigurasi kebijakan keamanan Google Cloud Armor dan menggunakan kunci token tindakan dengan kebijakan keamanan Anda, lihat Mengonfigurasi aturan untuk pengelolaan bot.

Langkah selanjutnya