reCAPTCHA Express auf Anwendungsservern einrichten

reCAPTCHA Express kann auf einem Anwendungsserver eingerichtet werden, wenn eine clientseitige Integration mit dem reCAPTCHA JavaScript oder dem mobilen SDK nicht möglich ist, z. B. zum Schutz von API-Endpunkten.

Mit reCAPTCHA Express können Sie Bewertungen ohne clientseitige Integration oder clientseitige Signale erstellen. reCAPTCHA Express verwendet nur Backend-Signale, um einen reCAPTCHA-Risikowert zu generieren. Anhand dieses Risikowerts können Sie entscheiden, ob Sie die Anfrage bearbeiten, zu einer Aufgaben-Seite weiterleiten oder sie für eine spätere Analyse protokollieren.

Hinweis

  1. Wählen Sie in der Google Cloud Console auf der Seite für die Projektauswahl ein Projekt vonaus oder erstellen Sie eines Google Cloud .

    Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

    • Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
    • Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die resourcemanager.projects.create Berechtigung enthält. Informationen zum Zuweisen von Rollen.

    Zur Projektauswahl

    Notieren Sie sich Ihre Google Cloud Projekt-ID für später.

  2. Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

  3. Aktivieren Sie die reCAPTCHA Enterprise API.

    Erforderliche Rollen zum Aktivieren von APIs

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) mit der Berechtigung serviceusage.services.enable. Informationen zum Zuweisen von Rollen.

    API aktivieren

  4. Erstellen Sie einen API-Schlüssel für die Authentifizierung:

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

      Zu den Anmeldedaten

    2. Klicken Sie auf Anmeldedaten erstellen und wählen Sie anschließend API-Schlüssel aus.

    3. Notieren Sie sich den API-Schlüssel für später.

reCAPTCHA Express-Schlüssel erstellen

Um reCAPTCHA Express zu implementieren, erstellen Sie einen reCAPTCHA Express-Schlüssel.

  1. Aktivieren Sie Cloud Shell in der Google Cloud Console.

    Cloud Shell aktivieren

    Unten in der Google Cloud Console wird eine Cloud Shell Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.

  2. gcloud

    Verwenden Sie den Befehl „gcloud recaptcha keys create“, um reCAPTCHA-Schlüssel zu erstellen.

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

    • INTEGRATION_TYPE: Art der Integration. Geben Sie score an.
    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.

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

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

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

    REST

    API-Referenzinformationen zu Schlüsseltypen und Integrationstypen, siehe Schlüssel und Integrationstyp.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • INTEGRATION_TYPE: Art der Integration. Geben Sie score an.
    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.
    • DEFAULT_SCORE_THRESHOLD: Bei richtlinienbasierten Aufgaben-Schlüsseln wird hier der universelle Aufgaben-Schwellenwert für den Schlüssel definiert, wenn kein benutzerdefinierter Schwellenwert für den Score festgelegt ist. Diese Funktion befindet sich im Vorschaumodus.
    • ACTION_SCORE_THRESHOLDS: Bei richtlinienbasierten Aufgaben-Schlüsseln wird hier die Aktion und der entsprechende Schwellenwert für den Score zwischen 0,0 und 1,0 angegeben. Beispiel: login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Diese Funktion befindet sich im Vorschaumodus.

    HTTP-Methode und URL: 

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

    JSON-Text der Anfrage: 

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

    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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,
"expressSettings": {
}
}

Notieren Sie sich Ihren Express-Schlüssel für später.

Bewertung erstellen

Wenn Sie eine Anfrage von Ihrem Anwendungsserver an reCAPTCHA senden möchten, erstellen Sie eine Bewertung mit der projects.assessments.create Methode.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • API_KEY: Der API-Schlüssel, den Sie für die Authentifizierung erstellt haben.
  • EXPRESS_KEY: Der reCAPTCHA Express-Schlüssel, den Sie für Ihre Anwendung erstellt haben.
  • USER_IP_ADDRESS: Die IP-Adresse in der Anfrage vom Gerät des Nutzers im Zusammenhang mit diesem Ereignis.
  • HEADER_INFO: Optional. Die HTTP-Header, die der Client an Ihren Anwendung server gesendet hat. Dies ist ein String-Array, das Anfrageheader im Format `[key:value]` enthält. Beispiel: `[key:value, key:value,...]`. Wir empfehlen, so viele Header wie möglich in der erforderlichen Reihenfolge zu teilen. Achten Sie darauf, dass die Reihenfolge der Header in allen Anfragen in derselben Sitzung einheitlich ist.
  • JA3_FINGERPRINT: Optional. JA3 ist ein MD5-Fingerabdruck bestimmter Felder des TLS Client-Hello-Pakets. Weitere Informationen finden Sie unter JA3 – Eine Methode zur Profilerstellung von SSL/TLS-Clients.
  • URI_NAME: Optional. Der URI, auf den der Nutzer zugreift.
  • USER_AGENT: Optional. Der User-Agent, der in der Anfrage vom Gerät des Nutzers im Zusammenhang mit diesem Ereignis vorhanden ist.
  • ACCOUNT_ID: Optional. Eine eindeutige und dauerhafte Kennung für das Konto des Nutzers, z. B. ein gehashter Kontoname.

HTTP-Methode und URL: 

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

JSON-Text der Anfrage: 


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

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 "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

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

$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

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

{
  "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": []
  }
}

Bewertungen interpretieren

reCAPTCHA Express gibt nur zwei Scores zurück: 0.3 und 0.7. 0.3 bedeutet, dass die Nutzerinteraktion ein höheres Risiko darstellt und wahrscheinlich betrügerisch ist. 0.7 bedeutet, dass die Nutzerinteraktion ein geringes Risiko darstellt und wahrscheinlich legitim ist.

Wenn nicht genügend Signale vorhanden sind, gibt reCAPTCHA Express standardmäßig 0.7 zurück.

Nächste Schritte