In Google Cloud Armor für mobile Anwendungen einbinden

In diesem Dokument erfahren Sie, wie Sie die Funktionen von reCAPTCHA mit Cloud Armor in mobile Anwendungen einbinden.

Implementieren Sie zum Abschließen der Integration mindestens ein Feature von reCAPTCHA und konfigurieren Sie Cloud Armor-Sicherheitsrichtlinien. Sie können jedoch nur reCAPTCHA-Aktionstokens für die Integration mit Cloud Armor in mobilen Apps implementieren.

Hinweis

  1. Aktivieren Sie die reCAPTCHA Enterprise API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    API aktivieren

  2. Geben Sie die Aktionen an, die Sie schützen möchten.

reCAPTCHA-Aktionstokens implementieren

reCAPTCHA muss in Ihrer mobilen App ausgeführt werden, damit Aktionstokens generiert werden können. Nachdem reCAPTCHA ein Aktionstoken generiert hat, hängen Sie es an einen vordefinierten Anfrageheader an, um Nutzeraktionen wie checkout zu schützen. Aktionstokens sind standardmäßig 30 Minuten lang gültig. Die Gültigkeitsdauer kann jedoch je nach Traffic variieren. Sie müssen das Aktions-Token an einen vordefinierten Anfrageheader anhängen, bevor das Token abläuft, damit Cloud Armor die Tokenattribute auswerten kann.

So implementieren Sie ein reCAPTCHA-Aktionstoken:

  1. Erstellen Sie einen Aktions-Tokenschlüssel für Ihre mobile Anwendung.

    Console

    1. Rufen Sie in der Google Cloud Console die Seite Google Cloud Fraud Defense auf.

      Zu Google Cloud Fraud Defense

    2. Prüfen Sie, ob der Name Ihres Projekts in der Ressourcenauswahl oben auf der Seite angezeigt wird.

      Wenn Sie den Namen Ihres Projekts nicht sehen, klicken Sie auf die Ressourcenauswahl und wählen Sie Ihr Projekt aus.

    3. Wählen Sie den Tab Keys aus.
    4. Klicken Sie auf Schlüssel erstellen.
    5. Geben Sie im Feld Anzeigename einen Anzeigenamen für den Schlüssel ein.
    6. Führen Sie je nach Art der Anwendung, für die Sie die reCAPTCHA-Schlüssel für WAF erstellen möchten, die entsprechende Aktion aus:

      7. reCAPTCHA-Schlüssel für WAF für iOS-Anwendungen erstellen

      Wir empfehlen, einen reCAPTCHA-Schlüssel pro iOS-Anwendung zu erstellen.

      1. Wählen Sie als Anwendungstyp die Option iOS aus.
        1. Klicken Sie im Abschnitt iOS-Bundle-ID-Liste auf iOS-Bundle-ID hinzufügen.

        2. Geben Sie im Feld Paket-ID den Namen Ihrer iOS-Paket-ID ein.

        3. Optional: Wenn Sie eine zusätzliche Paket-ID hinzufügen möchten, klicken Sie auf iOS-Paket-ID hinzufügen und geben Sie den Namen Ihrer iOS-Paket-ID in das Feld Paket-ID ein.
        4. Zum Schutz des reCAPTCHA-Schlüssels für Ihre Bundle-IDs müssen Sie den Ein/Aus-Button Bestätigung der Bundle-ID deaktivieren deaktivieren. Wenn Sie die Bestätigung der Bundle-ID deaktivieren, müssen Sie das Feld tokenProperties.iosBundleId in den von Ihnen erstellten Bewertungen prüfen.

        5. Optional: Geben Sie die Apple Developer-Einstellungen an.

          Wir empfehlen, diese Daten anzugeben, da Fraud Defense so genauere Risikobewertungen für Ihren Traffic erstellen kann.

          Geben Sie die folgenden Informationen ein:

          • Privater Schlüssel (.p8): Dieser wird im Apple Developer Center unter „Certificates, Identifiers & Profiles“ (Zertifikate, Kennungen und Profile) generiert.
          • Schlüsselkennung: Die Apple-Entwicklerschlüsselkennung (String mit 10 Zeichen).
          • Team-ID: Die Apple-Team-ID (10-stelliger String) des Bereitstellungsprofils, das zum Erstellen Ihrer Anwendung verwendet wird.
        6. Optional: Klicken Sie auf Nächster Schritt (optional).
          1. So erstellen Sie einen reCAPTCHA-Schlüssel für WAF:
            1. Aktivieren Sie unter Zusätzliche Einstellungen die Option
            2. Aktivieren Sie unter Zusätzliche Einstellungen die Ein/Aus-Schaltfläche Wird dieser Schlüssel in einer Web Application Firewall (WAF) bereitgestellt?.
            3. Wählen Sie in den Dienst-Optionen Cloud Armor aus.
            4. Wählen Sie in den Funktionsoptionen die Option Aktion aus.

          2. Wenn Sie für Ihre Nicht-Produktionsumgebung einen Wert angeben möchten, der für den Schlüssel zurückgegeben werden soll, wenn Bewertungen dafür erstellt werden, gehen Sie so vor:

            1. Klicken Sie unter Weitere Einstellungen auf den Schalter Erstellen Sie diesen Schlüssel nur zu Testzwecken?.
            2. Mit dem Schieberegler Punktzahl festlegen können Sie eine Punktzahl zwischen 0 und 1,0 angeben.
        7. Klicken Sie auf Schlüssel erstellen.

          8. Der neu erstellte Schlüssel wird auf der Seite reCAPTCHA-Schlüssel aufgeführt.

      reCAPTCHA-Schlüssel für WAF für Android-Anwendungen erstellen

      1. Wählen Sie als Anwendungstyp die Option Android aus.
      2. Klicken Sie im Abschnitt Android-Paketliste auf Android-Paket hinzufügen.
      3. Geben Sie im Feld Android-Paket den Namen Ihres Android-Pakets ein.
      4. Optional: Klicken Sie auf Android-Paket hinzufügen, um ein zusätzliches Paket hinzuzufügen, und geben Sie im Feld Android-Paket den Namen eines anderen Android-Pakets ein.
      5. Wenn Sie erzwingen möchten, dass der reCAPTCHA-Schlüssel nur in Ihrer App verwendet wird, deaktivieren Sie den Ein/Aus-Button Bestätigung des Paketnamens deaktivieren. Wenn Sie die Bestätigung des Paketnamens deaktivieren, müssen Sie das Feld tokenProperties.androidPackageName in den von Ihnen erstellten Bewertungen prüfen.
      6. Wenn Sie einen Schlüssel für eine Anwendung erstellen möchten, die neben dem Google Play Store auch in anderen App-Stores verfügbar ist, aktivieren Sie die Option Anwendungen unterstützen, die außerhalb des Google Play Store vertrieben werden.
      7. Optional: Klicken Sie auf Nächster Schritt (optional).
        1. So erstellen Sie einen reCAPTCHA-Schlüssel für WAF:
          1. Aktivieren Sie unter Zusätzliche Einstellungen die Option
          2. Aktivieren Sie unter Zusätzliche Einstellungen die Ein/Aus-Schaltfläche Wird dieser Schlüssel in einer Web Application Firewall (WAF) bereitgestellt?.
          3. Wählen Sie in den Dienst-Optionen Cloud Armor aus.
          4. Wählen Sie in den Funktionsoptionen die Option Aktion aus.

        2. Wenn Sie für Ihre Nicht-Produktionsumgebung einen Wert angeben möchten, der für den Schlüssel zurückgegeben werden soll, wenn Bewertungen dafür erstellt werden, gehen Sie so vor:

          1. Klicken Sie unter Weitere Einstellungen auf den Schalter Erstellen Sie diesen Schlüssel nur zu Testzwecken?.
          2. Mit dem Schieberegler Punktzahl festlegen können Sie eine Punktzahl zwischen 0 und 1,0 angeben.
      8. Klicken Sie auf Schlüssel erstellen.

        9. Der neu erstellte Schlüssel wird auf der Seite reCAPTCHA-Schlüssel aufgeführt.

    gcloud (iOS)

    Verwenden Sie zum Erstellen von reCAPTCHA-Schlüsseln den Befehl gcloud recaptcha keys create.

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.
    • BUNDLE_IDs: iOS-Bundle-IDs von Apps, die den Schlüssel verwenden dürfen. Geben Sie mehrere Bundle-IDs als durch Kommas getrennte Liste an.
    • WAF_FEATURE: Name des WAF-Features. Geben Sie action-token an.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Cloud Armor an.

    Führen Sie den Befehl gcloud recaptcha keys create aus:

    Linux, macOS oder 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

    Die Antwort enthält den neu erstellten reCAPTCHA-Schlüssel.

    gcloud (Android)

    Verwenden Sie zum Erstellen von reCAPTCHA-Schlüsseln den Befehl gcloud recaptcha keys create.

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.
    • PACKAGE_NAMES: Android-Paketnamen von Apps, die den Schlüssel verwenden dürfen. Geben Sie mehrere Paketnamen als durch Kommas getrennte Liste an.
    • WAF_FEATURE: Name des WAF-Features. Geben Sie action-token an.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Cloud Armor an.

    Führen Sie den Befehl gcloud recaptcha keys create aus:

    Linux, macOS oder 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

    Die Antwort enthält den neu erstellten reCAPTCHA-Schlüssel.

    REST (iOS)

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Anwendungsname.
    • BUNDLE_IDs: iOS-Bundle-IDs von Apps, die den Schlüssel verwenden dürfen. Geben Sie mehrere Bundle-IDs als durch Kommas getrennte Liste an.
    • WAF_FEATURE: Name des WAF-Features. Geben Sie action-token an.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Cloud Armor an.

    HTTP-Methode und URL: 

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

    JSON-Text der Anfrage:

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

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    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

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    $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

    Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

    
{
  "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)

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Anwendungsname.
    • PACKAGE_NAMES: Android-Paketnamen von Apps, die den Schlüssel verwenden dürfen. Geben Sie mehrere Paketnamen als durch Kommas getrennte Liste an.
    • WAF_FEATURE: Name des WAF-Features. Geben Sie action-token an.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Cloud Armor an.

    HTTP-Methode und URL: 

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

    JSON-Text der Anfrage:

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

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    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

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    $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

    Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

    
{
  "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. Binden Sie das reCAPTCHA Mobile SDK in Ihre mobilen Apps ein. Verwenden Sie dazu den von Ihnen erstellten Schlüssel für das Aktionstoken. Eine Anleitung finden Sie in dem Dokument, das dem Typ Ihrer mobilen Anwendung entspricht.

  3. Nachdem Sie das Token von reCAPTCHA erhalten haben, hängen Sie es an einen vordefinierten Anfrageheader im folgenden Format an:

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

    Der folgende Beispielcode zeigt, wie Sie das Token anhängen:

    Android

    Beispielcode in 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

    Beispielcode in 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)
 }

Cloud Armor-Sicherheitsrichtlinien konfigurieren

Nachdem Sie die Funktionen von reCAPTCHA for WAF implementiert haben, müssen Sie Cloud Armor-Sicherheitsrichtlinien konfigurieren, die reCAPTCHA-Tokens für die Bot-Verwaltung auswerten.

Informationen zum Konfigurieren von Cloud Armor-Sicherheitsrichtlinien und zum Verwenden der Aktionstoken-Schlüssel mit Ihren Sicherheitsrichtlinien finden Sie unter Regeln für die Bot-Verwaltung konfigurieren.

reCAPTCHA-Werte abrufen

Bei reCAPTCHA-Aktionstokens können Sie reCAPTCHA-Scores aus dem X-Recaptcha-Wafdata-Header abrufen. Anhand dieser Werte können Sie benutzerdefinierte Aktionen konfigurieren, die für Nutzeranfragen erforderlich sind.

Das folgende Beispiel zeigt einen X-Recaptcha-Wafdata-Header:

X-Recaptcha-Wafdata: waf_service="Google Cloud Armor", action_token;score=0.9\r\n

Sie können reCAPTCHA-Bewertungen auch in den Google Cloud Armor-Logs ansehen.

Nächste Schritte