reCAPTCHA Express auf Anwendungsservern einrichten

In diesem Dokument erfahren Sie, wie Sie reCAPTCHA Express einrichten auf einem Anwendungsserver in einer Umgebung, in der die reCAPTCHA-Integration JavaScript oder mobiles SDK sind nicht praktikabel, z. B. Schutz für API-Endpunkte.

Mit reCAPTCHA Express können Sie Bewertungen ohne clientseitige Funktionen erstellen. reCAPTCHA Express nutzt nur Back-End-Signale, um eine reCAPTCHA-Risikobewertung. Anhand dieses Risikowerts können Sie entscheiden, ob Sie die Anfrage ausführen, zu einer Bestätigungsseite weiterleiten oder sie für eine spätere Analyse protokollieren möchten.

Hinweise

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

    Go to project selector

    Notieren Sie sich Ihre Google Cloud-Projekt-ID zur späteren Verwendung.

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

  3. Enable the reCAPTCHA Enterprise API.

    Enable the API

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

    1. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten.

      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

Erstellen Sie ein reCAPTCHA, um reCAPTCHA Express zu implementieren Express-Taste.

  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

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

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

    • 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 finden Sie unter Schlüssel und Integrationstyp.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.

    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 in etwa folgende JSON-Antwort erhalten:

    
{
  "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,
"expressSettings": {
}
}

Notieren Sie sich Ihren Expressschlüssel zur späteren Verwendung.

Bewertung erstellen

Um eine Anfrage von Ihrem Anwendungsserver an reCAPTCHA zu senden, eine Bewertung mit dem projects.assessments.create erstellen .

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • API_KEY: API-Schlüssel, den Sie für die Authentifizierung erstellt haben.
  • EXPRESS_KEY: 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, die sich auf diesen Termin.
  • HEADER_INFO: Optional. Die HTTP-Header, die der Client an Ihren Anwendungsserver gesendet hat. Dabei handelt es sich um ein String-Array, das Anfrageheader im Format „[Schlüssel:Wert]“ enthält. Beispiel: `[Schlüssel:Wert, Schlüssel:Wert,...]`. Wir empfehlen, möglichst viele Header in der erforderlichen Reihenfolge zu teilen. Achten Sie darauf, dass die Reihenfolge der Header bei 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 für 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 zu 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 in etwa folgende JSON-Antwort 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/",
    "firewallPolicyEvaluation": false,
    "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 Werte zurück: 0.3 und 0.7. 0.3 gibt an, dass die Nutzerinteraktion ein höheres Risiko darstellt und wahrscheinlich betrügerisch ist. 0.7 gibt an, 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