Kontobezogene betrügerische Aktivitäten auf Websites erkennen und verhindern

In diesem Dokument erfahren Sie, wie Sie reCAPTCHA Enterprise Account Defender verwenden, um kontobezogene betrügerische Aktivitäten auf Websites zu erkennen und zu verhindern.

Mit reCAPTCHA Enterprise können Sie kritische Aktionen wie die Anmeldung und den Bezahlvorgang schützen. Es gibt jedoch viele subtile Formen von Kontomissbrauch, die sich erkennen lassen, indem das Verhalten eines bestimmten Nutzers auf einer Website über einen bestimmten Zeitraum beobachtet wird. Der Account Defender von reCAPTCHA Enterprise hilft dabei, diese Art von subtilem Missbrauch zu erkennen, indem ein websitespezifisches Modell für Ihre Website erstellt wird, um einen Trend verdächtigen Verhaltens oder eine Änderung der Aktivität zu erkennen. Mithilfe des websitespezifischen Modells können Sie mit reCAPTCHA Enterprise Account Defender Folgendes erkennen:

  • Verdächtige Aktivitäten
  • Konten mit ähnlichen Verhaltensmustern
  • Anfragen von Geräten, die für bestimmte Nutzer als vertrauenswürdig markiert wurden

Basierend auf der Analyse von reCAPTCHA Enterprise Account Defender und des standortspezifischen Modells können Sie die folgenden Maßnahmen ergreifen:

  • Betrügerische Konten einschränken oder deaktivieren
  • Verhindern Sie Versuche, Konten zu übernehmen.
  • Minimieren Sie erfolgreiche Kontoübernahmen.
  • Gewähren Sie nur Zugriff auf Anfragen von legitimen Nutzerkonten.
  • Vereinfachen Sie die Anmeldung über ein vertrauenswürdiges Gerät.

Hinweise

  1. Bereiten Sie Ihre Umgebung für reCAPTCHA Enterprise vor.
  2. Erstellen Sie einen punktebasierten Websiteschlüssel.

Webseiten für reCAPTCHA Enterprise Account Defender konfigurieren

reCAPTCHA Enterprise Account Defender erfordert ein umfassendes Verständnis der Kontoaktivitäten, um eine effektive Erkennung zu ermöglichen. Führen Sie die folgenden Schritte aus, um kontobezogene Aktivitäten an reCAPTCHA Enterprise Account Defender zu senden und Ihr websitespezifisches Modell zu erstellen und zu verbessern:

  1. Erfassen horizontaler Telemetriedaten aktivieren
  2. Berichte zu kritischen Nutzeraktionen erstellen
  3. Kritische Nutzerereignisse bewerten
  4. Nutzerereignisse annotieren, um Ihr websitespezifisches Modell zu optimieren

Erhebung von horizontalen Telemetriedaten aktivieren

reCAPTCHA Enterprise Account Defender benötigt einen vollständigen Überblick über Nutzeraktionen, z. B. ob der Nutzer angemeldet ist oder zur Anmeldung führt. Wenn Sie die passive Erfassung horizontaler Telemetriedaten durch reCAPTCHA Enterprise Account Defender aktivieren möchten, laden Sie das reCAPTCHA Enterprise-JavaScript-Script mit dem wertungsbasierten Websiteschlüssel, den Sie im Hintergrund aller Webseiten erstellt haben, die Teil Ihres Nutzerworkflows sind.

Das folgende Beispiel zeigt, wie das reCAPTCHA Enterprise-JavaScript-Script auf einer Webseite geladen wird.

    <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

Berichte zu kritischen Nutzeraktionen erstellen

Der Account Defender von reCAPTCHA Enterprise benötigt Informationen zu kritischen Nutzeraktionen, um verdächtige Aktivitätsmuster zu erkennen und typische Aktivitätsmuster auf Ihrer Website besser zu verstehen. Melden Sie daher wichtige Nutzeraktionen auf den Webseiten, indem Sie für diese kritischen Nutzeraktionen grecaptcha.enterprise.execute() aufrufen.

Wir empfehlen, alle kritischen Nutzeraktionen zu melden, da dies bei der Erfassung zusätzlicher Signale hilfreich ist. Ersetzen Sie für jede Nutzeraktion, die Sie melden möchten, den Wert des Parameters action von grecaptcha.enterprise.execute() durch einen Aktionsnamen, der die Nutzeraktion beschreibt.

In der folgenden Tabelle sind die Aktionsnamen aufgeführt, die Sie für Berichte zu kritischen Nutzeraktionen verwenden können.

Aktionsname Vom Nutzer initiiertes Ereignis oder eine Nutzeraktion
LOGIN

Melden Sie sich auf der Website an.
REGISTRATION Registrierung auf der Website
SECURITY_QUESTION_CHANGE Anfrage zur Änderung der Sicherheitscheck-Frage
PASSWORD_RESET Anfrage zum Zurücksetzen des Passworts
PHONE_NUMBER_UPDATE Anfrage zur Aktualisierung der Telefonnummer
EMAIL_UPDATE Anfrage zur Aktualisierung der E-Mail-Adresse
ACCOUNT_UPDATE Anfrage zur Aktualisierung kontobezogener Informationen wie Kontaktdaten
TRIGGER_MFA Eine Aktion, die eine MFA-Abfrage auslöst.
REDEEM_CODE Gutscheincode beantragen.
LIST_PAYMENT_METHODS Rufen Sie die Liste der Zahlungsmethoden ab.

Das folgende Beispiel zeigt, wie grecaptcha.enterprise.execute() bei einer Aktualisierung der Telefonnummer angerufen wird:

    <script>
    function onClick(e) {
      e.preventDefault();
      grecaptcha.enterprise.ready(async () => {
        const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'PHONE_NUMBER_UPDATE'});
      });
    }
    </script>

Kritische Nutzerereignisse bewerten

Wenn Sie grecaptcha.enterprise.execute() für eine Nutzeraktion aufrufen, wird ein Token generiert. Erstellen Sie für die kritischen Nutzerereignisse wie erfolgreiche und fehlgeschlagene Anmeldungen, Registrierungen und Aktionen angemeldeter Nutzer eine Bewertung, um die Ergebnisse des grecaptcha.enterprise.execute()-Aufrufs zu bewerten. Die Bewertung liefert Ihnen ein Risikoergebnis, das Sie verwenden können, um eine Entscheidung über den Umgang mit potenziell betrügerischen Aktivitäten zu treffen. Sie können beispielsweise verdächtige Anfragen blockieren, riskante Anmeldungen anfordern und relevante Konten untersuchen.

Für reCAPTCHA Enterprise Account Defender müssen Sie eine stabile Konto-ID bereitstellen, um Nutzeraktivitäten wie Anmelde-, Anmelde- und Registrierungsanfragen einem bestimmten Konto zuzuordnen. So kann reCAPTCHA Enterprise Account Defender die Aktivitätsmuster der Nutzer besser verstehen und für jedes Konto ein Aktivitätsmodell erstellen, um anomalen und missbräuchlichen Traffic besser zu erkennen.

Wählen Sie eine stabile Konto-ID accountId, die nicht oft vom Nutzer geändert wird, und stellen Sie sie der Bewertung in der Methode projects.assessments.create zur Verfügung. Diese stabile Konto-ID sollte für alle Ereignisse desselben Nutzers denselben Wert haben. Du kannst Folgendes als Konto-ID angeben:

Nutzerkennungen

Wenn jedes Konto eindeutig mit einem stabilen Nutzernamen, einer E-Mail-Adresse oder einer Telefonnummer verknüpft werden kann, können Sie es als accountId verwenden. Wenn Sie solche websiteübergreifenden Kennungen (IDs, die websiteübergreifend wiederverwendet werden können) angeben, verwendet reCAPTCHA Enterprise diese Informationen, um den Schutz Ihrer Nutzerkonten anhand von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Kontokennungen gemeldet und das Wissen über websiteübergreifende Missbrauchsmuster im Zusammenhang mit diesen Kennungen genutzt.

Wenn eine interne Nutzer-ID mit jedem Konto eindeutig verknüpft ist, können Sie sie auch als accountId angeben.

Gehasht oder verschlüsselt

Wenn keine interne Nutzer-ID mit jedem Konto eindeutig verknüpft ist, können Sie eine beliebige stabile Kennung in eine intransparente, websitespezifische Konto-ID umwandeln. Diese Kennung wird weiterhin für reCAPTCHA Enterprise Account Defender benötigt, um Nutzeraktivitätsmuster zu verstehen und anomales Verhalten zu erkennen. Sie wird jedoch nicht für andere Websites verwendet.

Wählen Sie eine beliebige stabile Konto-ID aus und machen Sie sie undurchsichtig, bevor Sie sie an reCAPTCHA Enterprise senden. Verwenden Sie dazu Verschlüsselung oder Hashing:

  • Verschlüsselung (empfohlen): Verschlüsseln Sie die Kontokennung mit einer deterministischen Verschlüsselungsmethode, die einen stabilen Geheimtext erzeugt. Eine ausführliche Anleitung finden Sie unter Daten deterministisch verschlüsseln. Wenn Sie sich für die symmetrische Verschlüsselung gegenüber der Hash-Technologie entscheiden, müssen Sie keine Zuordnung zwischen Ihren Nutzerkennungen und den entsprechenden intransparenten Nutzerkennungen vornehmen. Entschlüsseln Sie die intransparenten Kennungen, die von reCAPTCHA Enterprise zurückgegeben werden, um sie in die Nutzerkennungen umzuwandeln.

  • Hash-Technologie: Wir empfehlen, die Kontokennung mithilfe der SHA256-HMAC-Methode mit einem benutzerdefinierten Salt Ihrer Wahl zu hashen. Da Hashes nur einseitig sind, müssen Sie eine Zuordnung zwischen den generierten Hashes und Ihren Nutzerkennungen beibehalten, damit Sie die gehashten Konto-IDs, die zurückgegeben werden, den ursprünglichen Konten zuordnen können.

Neben einer stabilen Konto-ID für alle kontobezogenen Anfragen können Sie für bestimmte Anfragen zusätzliche Konto-IDs angeben, die möglicherweise instabil sind. Kontextspezifische Kontokennungen, die zusätzlich zu accountId angegeben werden, helfen reCAPTCHA Enterprise Account Defender dabei, Nutzeraktivitäten besser zu verstehen und Versuche von Kontoübernahmen zu erkennen, um Ihre Nutzerkonten zu schützen. Wenn Sie zusätzliche Kennungen angeben, verwendet reCAPTCHA Enterprise diese Informationen, um den Schutz Ihrer Nutzerkonten anhand von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Kontokennungen gemeldet und das Wissen über websiteübergreifende Missbrauchsmuster im Zusammenhang mit diesen Kennungen genutzt. Sie können beispielsweise Folgendes angeben:

  • Der Nutzername, die E-Mail-Adresse oder die Telefonnummer, die als Anmelde-Handle für Anmeldeanfragen verwendet wurde

  • Die E-Mail-Adresse oder Telefonnummer, die für eine Anfrage zur Multi-Faktor-Authentifizierung bestätigt wurde

  • Eine E-Mail-Adresse oder Telefonnummer (primär oder sekundär), die der Nutzer bei einer Anfrage zur Kontoaktualisierung angegeben hat

  • Die E-Mail-Adressen und Telefonnummern, die der Nutzer bei der Registrierungsanfrage angegeben hat

Hängen Sie die ausgewählte stabile Konto-ID für alle kontobezogenen Anfragen an den Parameter accountId in der Methode projects.assessments.create an. Optional können Sie in der Bewertung über das Feld userIds zusätzliche Konto-IDs für die relevanten Anfragen angeben.

Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud-Projekt-ID
  • TOKEN: vom Aufruf grecaptcha.enterprise.execute() zurückgegebenes Token
  • KEY_ID: reCAPTCHA-Schlüssel, der mit der Website verknüpft ist
  • ACCOUNT_ID: die Kennung, die dem Nutzerkonto für ein Nutzerkonto Ihrer Website eindeutig zugeordnet ist
  • EMAIL_ADDRESS: Optional. Gegebenenfalls eine E-Mail-Adresse, die mit dieser Anfrage verknüpft ist
  • PHONE_NUMBER: Optional. Gegebenenfalls eine Telefonnummer, die mit dieser Anfrage verknüpft ist
  • USERNAME: Optional. Gegebenenfalls ein Nutzername, der mit dieser Anfrage verknüpft ist

HTTP-Methode und URL: 

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

JSON-Text der Anfrage: 

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
      "accountId": "ACCOUNT_ID",
      "userIds": [
        {
          "email": "EMAIL_ADDRESS"
        },
        {
          "phoneNumber": "PHONE_NUMBER"
        },
        {
          "username": "USERNAME"
        }
      ]
    }
  }
}

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/assessments"

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/assessments" | Select-Object -Expand Content

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "login",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.6,
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "userInfo": {
      "accountId": "ACCOUNT_ID"
    }
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000",
  "accountDefenderAssessment": {
    "labels": ["SUSPICIOUS_LOGIN_ACTIVITY"]
  }
}

Codebeispiel

Java

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei reCAPTCHA Enterprise zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AccountDefenderAssessment.AccountDefenderLabel;
import com.google.recaptchaenterprise.v1.Assessment;
import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
import com.google.recaptchaenterprise.v1.Event;
import com.google.recaptchaenterprise.v1.ProjectName;
import com.google.recaptchaenterprise.v1.RiskAnalysis.ClassificationReason;
import com.google.recaptchaenterprise.v1.TokenProperties;
import com.google.recaptchaenterprise.v1.UserId;
import com.google.recaptchaenterprise.v1.UserInfo;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.List;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AccountDefenderAssessment {

  public static void main(String[] args)
      throws IOException, NoSuchAlgorithmException, InvalidKeyException {
    // TODO(developer): Replace these variables before running the sample.
    // projectId: Google Cloud Project ID
    String projectId = "project-id";

    // recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha
    // services.
    String recaptchaSiteKey = "recaptcha-site-key";

    // token: The token obtained from the client on passing the recaptchaSiteKey.
    // To get the token, integrate the recaptchaSiteKey with frontend. See,
    // https://cloud.google.com/recaptcha-enterprise/docs/instrument-web-pages#frontend_integration_score
    String token = "recaptcha-token";

    // recaptchaAction: The action name corresponding to the token.
    String recaptchaAction = "recaptcha-action";

    // Unique ID of the user, such as email, customer ID, etc.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    // User phone number
    String phoneNumber = "555-987-XXXX";

    // User email address
    String emailAddress = "john.doe@example.com";

    accountDefenderAssessment(projectId, recaptchaSiteKey, token, recaptchaAction, accountId, phoneNumber, emailAddress);
  }

  /**
   * This assessment detects account takeovers. See,
   * https://cloud.google.com/recaptcha-enterprise/docs/account-takeovers The input is the hashed
   * account id. Result tells if the action represents an account takeover. You can optionally
   * trigger a Multi-Factor Authentication based on the result.
   */
  public static void accountDefenderAssessment(
      String projectId,
      String recaptchaSiteKey,
      String token,
      String recaptchaAction,
      String accountId,
      String phoneNumber,
      String emailAddress)
      throws IOException {
    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {

      // Set the properties of the event to be tracked.
      Event.Builder eventBuilder =
          Event.newBuilder()
              .setSiteKey(recaptchaSiteKey)
              .setToken(token);

      // Set the account id, email address and phone number (of the user).
      eventBuilder.setUserInfo(
        UserInfo.newBuilder()
          .setAccountId(accountId)
          .addUserIds(UserId.newBuilder().setEmail(emailAddress))
          .addUserIds(UserId.newBuilder().setPhoneNumber(phoneNumber)));

      Event event = eventBuilder.build();

      // Build the assessment request.
      CreateAssessmentRequest createAssessmentRequest =
          CreateAssessmentRequest.newBuilder()
              .setParent(ProjectName.of(projectId).toString())
              .setAssessment(Assessment.newBuilder().setEvent(event).build())
              .build();

      Assessment response = client.createAssessment(createAssessmentRequest);

      // Check integrity of the response token.
      if (!checkTokenIntegrity(response.getTokenProperties(), recaptchaAction)) {
        return;
      }

      // Get the reason(s) and the reCAPTCHA risk score.
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
        System.out.println(reason);
      }
      float recaptchaScore = response.getRiskAnalysis().getScore();
      System.out.println("The reCAPTCHA score is: " + recaptchaScore);
      String assessmentName = response.getName();
      System.out.println(
          "Assessment name: " + assessmentName.substring(assessmentName.lastIndexOf("/") + 1));

      // Get the Account Defender result.
      com.google.recaptchaenterprise.v1.AccountDefenderAssessment accountDefenderAssessment =
          response.getAccountDefenderAssessment();
      System.out.println(accountDefenderAssessment);

      // Get Account Defender label.
      List<AccountDefenderLabel> defenderResult =
          response.getAccountDefenderAssessment().getLabelsList();
      // Based on the result, can you choose next steps.
      // If the 'defenderResult' field is empty, it indicates that Account Defender did not have
      // anything to add to the score.
      // Few result labels: ACCOUNT_DEFENDER_LABEL_UNSPECIFIED, PROFILE_MATCH,
      // SUSPICIOUS_LOGIN_ACTIVITY, SUSPICIOUS_ACCOUNT_CREATION, RELATED_ACCOUNTS_NUMBER_HIGH.
      // For more information on interpreting the assessment, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/account-defender#interpret-assessment-details
      System.out.println("Account Defender Assessment Result: " + defenderResult);
    }
  }

  private static boolean checkTokenIntegrity(
      TokenProperties tokenProperties, String recaptchaAction) {
    // Check if the token is valid.
    if (!tokenProperties.getValid()) {
      System.out.println(
          "The Account Defender Assessment call failed because the token was: "
              + tokenProperties.getInvalidReason().name());
      return false;
    }

    // Check if the expected action was executed.
    if (!tokenProperties.getAction().equals(recaptchaAction)) {
      System.out.printf(
          "The action attribute in the reCAPTCHA tag '%s' does not match "
              + "the action '%s' you are expecting to score",
          tokenProperties.getAction(), recaptchaAction);
      return false;
    }
    return true;
  }
}

Das Risikoergebnis der kritischen Nutzerereignisse interpretieren

Wenn Sie eine Bewertung mit aktiviertem Account Defender erstellen, gibt Account Defender accountDefenderAssessment als Teil der Bewertungsantwort zurück. Mit dem Wert von accountDefenderAssessment können Sie beurteilen, ob die Nutzeraktivität legitim oder betrügerisch ist. Außerdem wird eine Bewertungs-ID zurückgegeben, die Sie beim Annotieren von Nutzerereignissen verwenden müssen.

Das folgende Beispiel zeigt eine JSON-Antwort:

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "login",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.6,
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID/assessments/b6ac310000000000X",
  "accountDefenderAssessment": {
    labels: ["SUSPICIOUS_LOGIN_ACTIVITY"]
  }
}

Das Feld accountDefenderAssessment kann einen der folgenden Werte enthalten:

Wert Beschreibung
SUSPICIOUS_LOGIN_ACTIVITY Gibt an, dass die Anfrage ein hohes Risiko für Credential Stuffing oder Kontoübernahme darstellt.
SUSPICIOUS_ACCOUNT_CREATION Gibt an, dass die Anfrage ein hohes Risiko für die missbräuchliche Erstellung des Kontos darstellt.
PROFILE_MATCH

Gibt an, dass die Attribute des Nutzers mit den Attributen übereinstimmen, die zuvor für diesen Nutzer erkannt wurden. Dieser Wert gibt an, dass sich der Nutzer auf einem vertrauenswürdigen Gerät befindet, über das zuvor auf deine Website zugegriffen wurde.

PROFILE_MATCH wird nur in den folgenden Szenarien zurückgegeben:

  • Sie verwenden Multi-Faktor-Authentifizierung(MFA) oder 2-Faktor-Authentifizierung(2FA) und reCAPTCHA Enterprise Account Defender kennzeichnet Nutzerprofile als vertrauenswürdig, nachdem Nutzer die MFA- oder 2FA-Abfrage bestanden haben.
  • Sie annotieren Bewertungen als LEGITIMATE oder PASSED_TWO_FACTOR und reCAPTCHA Enterprise Account Defender markiert das entsprechende Nutzerprofil als vertrauenswürdig.
RELATED_ACCOUNTS_NUMBER_HIGH Gibt an, dass die Anfrage viele zugehörige Konten umfasst. Das bedeutet nicht unbedingt, dass das Konto defekt ist. Möglicherweise sind jedoch weitere Untersuchungen erforderlich.

Ereignisse mit Anmerkungen versehen, um Ihr websitespezifisches Modell zu optimieren

Um reCAPTCHA Enterprise Account Defender mehr Informationen zur Verfügung zu stellen und Ihr websitespezifisches Erkennungsmodell zu verbessern, müssen Sie die Ereignisse annotieren, die Sie durch das Erstellen von Bewertungen bewertet haben.

Zum Annotieren einer Bewertung senden Sie eine Anfrage mit der Bewertungs-ID an die Methode projects.assessments.annotate. Der Anfragetext enthält Labels mit zusätzlichen Informationen zu einem in der Bewertung beschriebenen Ereignis.

So annotieren Sie eine Bewertung:

  1. Bestimmen Sie je nach Anwendungsfall die Informationen und Labels, die in den JSON-Text der Anfrage aufgenommen werden sollen.

    In der folgenden Tabelle sind die Labels und Werte aufgeführt, mit denen Sie Ereignisse annotieren können:

    Label Beschreibung Beispiel für Anfrage
    reasons Erforderlich. Ein Label, das Ihre Bewertungen unterstützt.

    Geben Sie einige Sekunden oder Minuten nach dem Ereignis im Label reasons Echtzeitdetails an, da diese die Echtzeiterkennung beeinflussen.

    Eine Liste der möglichen Werte finden Sie unter Werte für Gründe.

    Beispiel: Vermerken Sie mit CORRECT_PASSWORD- oder INCORRECT_PASSWORD-Werten, ob das eingegebene Passwort korrekt ist, um Kontoübernahmen zu erkennen. Wenn Sie Ihre eigene MFA bereitgestellt haben, können Sie die folgenden Werte hinzufügen: INITIATED_TWO_FACTOR und PASSED_TWO_FACTOR oder FAILED_TWO_FACTOR. 

    
      {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Optional. Ein Label zur Angabe der Rechtmäßigkeit der Prüfungen.

    Geben Sie mit dem Label annotation Fakten zu Anmelde- und Registrierungsereignissen an, um Ihre Risikobewertungen zu validieren oder zu korrigieren.

    Mögliche Werte: LEGITIMATE oder FRAUDULENT.

    Sie können diese Informationen jederzeit oder als Teil eines Batchjobs senden. Wir empfehlen jedoch, diese Informationen einige Sekunden oder Minuten nach dem Ereignis zu senden, da sie die Echtzeiterkennung beeinflussen.

    		 
    
      {
       "annotation": "LEGITIMATE"
      }
    accountId

    Optional. Ein Label, um eine Konto-ID mit einem Ereignis zu verknüpfen.

    Wenn Sie eine Bewertung ohne Konto-ID erstellt haben, verwenden Sie dieses Label, um die Konto-ID eines Ereignisses anzugeben, sofern es verfügbar ist.

    		 
    
  {
   "accountId": "ACCOUNT_ID"
  }

  2. Erstellen Sie eine Anmerkungsanfrage mit den entsprechenden Labels.

    Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

    • ASSESSMENT_ID: Wert des Feldes name, das vom projects.assessments.create-Aufruf zurückgegeben wurde.
    • ANNOTATION: Optional. Ein Label, das angibt, ob die Bewertung legitim oder betrügerisch ist.
    • REASONS: Optional. Gründe, die die Anmerkung stützen. Eine Liste der möglichen Werte finden Sie unter Werte für Gründe.
    • ACCOUNT_ID: Optional. Die Kennung, die dem Nutzerkonto auf Ihrer Website eindeutig zugeordnet ist.

    Weitere Informationen finden Sie unter Labels für Annotationen.

    HTTP-Methode und URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

    JSON-Text der Anfrage: 

    {
  "annotation": ANNOTATION,
  "reasons": REASONS,
  "accountId": 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 "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"

    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/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

    Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.

Codebeispiel

Java

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei reCAPTCHA Enterprise zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Annotation;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Reason;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentResponse;
import com.google.recaptchaenterprise.v1.AssessmentName;
import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.util.UUID;

public class AnnotateAccountDefenderAssessment {

  public static void main(String[] args) throws IOException, NoSuchAlgorithmException {
    // TODO(developer): Replace these variables before running the sample.
    // projectID: GCloud Project id.
    String projectID = "project-id";

    // assessmentId: Value of the 'name' field returned from the CreateAssessment call.
    String assessmentId = "account-defender-assessment-id";

    // accountId: Set the accountId corresponding to the assessment id.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    annotateAssessment(projectID, assessmentId, accountId);
  }

  /**
   * Pre-requisite: Create an assessment before annotating. Annotate an assessment to provide
   * feedback on the correctness of recaptcha prediction.
   */
  public static void annotateAssessment(
      String projectID, String assessmentId, String accountId) throws IOException {

    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {
      // Build the annotation request.
      // For more info on when/how to annotate, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/annotate-assessment#when_to_annotate
      AnnotateAssessmentRequest annotateAssessmentRequest =
          AnnotateAssessmentRequest.newBuilder()
              .setName(AssessmentName.of(projectID, assessmentId).toString())
              .setAnnotation(Annotation.LEGITIMATE)
              .addReasons(Reason.PASSED_TWO_FACTOR)
              .setAccountId(accountId)
              .build();

      // Empty response is sent back.
      AnnotateAssessmentResponse response = client.annotateAssessment(annotateAssessmentRequest);
      System.out.println("Annotated response sent successfully ! " + response);
    }
  }
}

reCAPTCHA Enterprise Account Defender aktivieren

Nachdem Sie Ihre Webseiten für reCAPTCHA Enterprise Account Defender konfiguriert haben, können Sie reCAPTCHA Enterprise Account Defender aktivieren.

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

    Zur Seite „reCAPTCHA Enterprise“

  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. Klicken Sie auf Einstellungen.

  4. Klicken Sie im Bereich Account Defender auf Aktivieren.

  5. Klicken Sie im Dialogfeld Account Defender konfigurieren auf Aktivieren.

Es kann einige Stunden dauern, bis die Aktivierung von reCAPTCHA Enterprise Account Defender für unsere Systeme wirksam wird. Nachdem die Aktivierung der Funktion in unsere Systeme übernommen wurde, sollten Sie im Rahmen der Bewertungen Antworten zu Account Defender erhalten.

Nächste Schritte