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

In diesem Dokument erfahren Sie, wie Sie mit reCAPTCHA Account Defense kontobezogene betrügerische Aktivitäten auf Websites erkennen und verhindern.

Mit reCAPTCHA können Sie wichtige Aktionen wie die Anmeldung und den Bezahlvorgang schützen. Es gibt jedoch viele subtile Formen von Kontomissbrauch, die durch die Beobachtung des Verhaltens eines bestimmten Nutzers auf einer Website über einen bestimmten Zeitraum hinweg erkannt werden können. reCAPTCHA Account Defender hilft dabei, diese Arten von subtilem Missbrauch zu erkennen, indem ein websitespezifisches Modell für Ihre Website erstellt wird, um einen Trend zu verdächtigem Verhalten oder eine Änderung der Aktivität zu erkennen. Mithilfe des websitespezifischen Modells hilft Ihnen reCAPTCHA Account Defender, Folgendes zu erkennen:

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

Auf Grundlage der Analyse von reCAPTCHA Account Defender und des Website-spezifischen Modells können Sie die folgenden Maßnahmen ergreifen:

  • Betrügerische Konten einschränken oder deaktivieren
  • Versuche zur Kontoübernahme verhindern
  • Erfolgreiche Kontoübernahmen eindämmen
  • Gewähren Sie nur Zugriff auf Anfragen, die von legitimen Nutzerkonten stammen.
  • Die Anmeldung für Nutzer, die sich über eines ihrer vertrauenswürdigen Geräte anmelden, wird vereinfacht.

Hinweis

  1. Umgebung für reCAPTCHA vorbereiten
  2. Erstellen Sie einen punktebasierten Websiteschlüssel.

Webseiten für reCAPTCHA Account Defense konfigurieren

Für reCAPTCHA Account Defense ist ein umfassendes Verständnis der Kontoaktivitäten erforderlich, um eine effektive Erkennung zu ermöglichen. So können Sie reCAPTCHA Account Defense mit kontobezogenen Aktivitäten füttern und Ihr Website-spezifisches Modell erstellen und verbessern:

  1. Erhebung horizontaler Telemetriedaten aktivieren
  2. Berichte zu wichtigen Nutzeraktionen
  3. Wichtige Nutzerereignisse bewerten
  4. Nutzerereignisse annotieren, um Ihr websitespezifisches Modell zu optimieren:

Erhebung horizontaler Telemetriedaten aktivieren

Für reCAPTCHA Account Defense ist eine vollständige Übersicht über Nutzeraktionen erforderlich, z. B. ob der Nutzer angemeldet ist oder sich gerade anmeldet. Wenn Sie die passive Erhebung horizontaler Telemetriedaten durch reCAPTCHA Account Defense aktivieren möchten, laden Sie das reCAPTCHA-JavaScript-Script mit dem punktebasierten Websiteschlüssel, den Sie im Hintergrund aller Webseiten erstellt haben, die Teil Ihres Nutzer-Workflows sind.

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

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

Berichte zu wichtigen Nutzeraktionen

Um verdächtige Aktivitätsmuster zu erkennen und ein besseres Modell typischer Aktivitätsmuster auf Ihrer Website zu erstellen, benötigt reCAPTCHA Account Defense Informationen zu wichtigen Nutzeraktionen. Melden Sie daher wichtige Nutzeraktionen auf den Webseiten, indem Sie grecaptcha.enterprise.execute() für diese wichtigen Nutzeraktionen aufrufen.

Wir empfehlen, alle wichtigen Nutzeraktionen zu melden, da dies die Erfassung zusätzlicher Signale unterstützt. Ersetzen Sie für jede Nutzeraktion, die Sie erfassen 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 beim Melden der kritischen Nutzeraktionen verwenden können.

Aktionsname Vom Nutzer initiiertes Ereignis oder Nutzeraktion
LOGIN

Melden Sie sich auf der Website an.
REGISTRATION Registrierung auf der Website.
SECURITY_QUESTION_CHANGE Antrag auf Änderung der Sicherheitsfrage
PASSWORD_RESET Fordern Sie das Zurücksetzen des Passworts an.
PHONE_NUMBER_UPDATE Anfrage zur Aktualisierung der Telefonnummer.
EMAIL_UPDATE Anfrage zum Aktualisieren der E‑Mail-Adresse.
ACCOUNT_UPDATE Sie möchten kontobezogene Informationen wie Kontaktdaten aktualisieren.
TRIGGER_MFA Eine Aktion, die eine MFA-Herausforderung auslöst.
REDEEM_CODE Code einlösen
LIST_PAYMENT_METHODS Rufen Sie die Liste der Zahlungsmethoden ab.

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

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

Wichtige 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 der angemeldeten Nutzer eine Bewertung, um die Ergebnisse des grecaptcha.enterprise.execute()-Aufrufs zu analysieren. Die Bewertung liefert Ihnen ein Risikourteil, das Sie als Grundlage für Ihre Entscheidung nutzen können, wie Sie mit potenziell betrügerischen Aktivitäten umgehen. Sie können beispielsweise verdächtige Anfragen blockieren, riskante Anmeldungen überprüfen und Konten untersuchen, die für Sie von Interesse sind.

Für reCAPTCHA Account Defense müssen Sie eine stabile Konto-ID angeben, damit die Bewertung erfolgen und die Nutzeraktivität (z. B. Anmelde-, angemeldete und Registrierungsanfragen) einem bestimmten Konto zugeordnet werden kann. So kann reCAPTCHA Account Defense Muster der Nutzeraktivität verarbeiten, um für jedes Konto ein Aktivitätsmodell zu erstellen und so anomaler und missbräuchlicher Traffic besser zu erkennen.

Wählen Sie eine stabile Konto-ID accountId aus, die vom Nutzer nicht oft 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, die sich auf denselben Nutzer beziehen, denselben Wert haben. Sie können Folgendes als Konto-ID angeben:

Nutzer-IDs

Wenn jedes Konto eindeutig mit einem stabilen Nutzernamen, einer E‑Mail-Adresse oder einer Telefonnummer verknüpft werden kann, können Sie diese als accountId verwenden. Wenn Sie solche websiteübergreifenden Kennungen (Kennungen, die auf mehreren Websites wiederverwendet werden können) angeben, verwendet reCAPTCHA diese Informationen, um den Schutz für Ihre Nutzerkonten auf Grundlage von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Konto-IDs gekennzeichnet und Informationen zu websiteübergreifenden Missbrauchsmustern im Zusammenhang mit diesen Kennungen verwendet.

Alternativ können Sie die accountId angeben, wenn Sie eine interne Nutzer-ID haben, die eindeutig jedem Konto zugeordnet ist.

Gehasht oder verschlüsselt

Wenn Sie keine interne Nutzer-ID haben, die eindeutig mit jedem Konto verknüpft ist, können Sie jede stabile ID in eine undurchsichtige, websitespezifische Konto-ID umwandeln. Diese Kennung ist weiterhin für reCAPTCHA Account Defender erforderlich, um Nutzeraktivitätsmuster zu verstehen und anomales Verhalten zu erkennen. Sie wird jedoch nicht auf anderen Websites geteilt.

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

  • Verschlüsselung (empfohlen): Verschlüsseln Sie die Konto-ID mit einer deterministischen Verschlüsselungsmethode, die einen stabilen Chiffretext erzeugt. Eine ausführliche Anleitung finden Sie unter Daten deterministisch verschlüsseln. Wenn Sie sich für die symmetrische Verschlüsselung anstelle des Hashings entscheiden, müssen Sie keine Zuordnung zwischen Ihren Nutzerkennungen und den entsprechenden undurchsichtigen Nutzerkennungen vornehmen. Entschlüsseln Sie die intransparenten Kennzeichnungen, die von reCAPTCHA zurückgegeben werden, um sie in die Nutzer-ID umzuwandeln.

  • Hashing: Wir empfehlen, die Konto-ID mit der SHA256-HMAC-Methode und einem benutzerdefinierten Salt Ihrer Wahl zu hashen. Da Hashes nur in eine Richtung funktionieren, müssen Sie eine Zuordnung zwischen den generierten Hashes und Ihren Nutzer-IDs beibehalten, damit Sie die zurückgegebenen gehashten Konto-IDs den ursprünglichen Konten zuordnen können.

Zusätzlich zur Angabe einer stabilen Konto-ID für alle kontobezogenen Anfragen können Sie für einige bestimmte Anfragen zusätzliche Konto-IDs angeben, die möglicherweise nicht stabil sind. Kontextspezifische Konto-IDs, die zusätzlich zu accountId bereitgestellt werden, helfen reCAPTCHA Account Defense, Nutzeraktivitäten besser zu analysieren und Versuche zur Kontoübernahme zu erkennen, um Ihre Nutzerkonten zu schützen. Wenn Sie zusätzliche Kennungen angeben, verwendet reCAPTCHA diese Informationen, um den Schutz Ihrer Nutzerkonten auf Grundlage von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Konto-IDs gekennzeichnet und websiteübergreifende Missbrauchsmuster im Zusammenhang mit diesen Kennungen verwendet. 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 einer Registrierungsanfrage angibt

Hängen Sie die ausgewählte stabile Konto-ID an den Parameter accountId in der Methode projects.assessments.create für alle kontobezogenen Anfragen an. Optional können Sie zusätzliche Konto-IDs für die entsprechenden Anfragen angeben, indem Sie das Feld userIds in der Überprüfung verwenden.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

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

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 eine JSON-Antwort ähnlich wie diese 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 Fraud Defense 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;
  }
}

Risikobewertung der kritischen Nutzerereignisse interpretieren

Wenn Sie eine Bewertung mit aktivierter Account Defense erstellen, gibt Account Defense accountDefenderAssessment als Teil der Bewertungsantwort zurück. Anhand des Werts 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-Beispielantwort:

{
  "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 haben:

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 Erstellung von Missbrauchskonten darstellt.
PROFILE_MATCH

Gibt an, dass die Attribute des Nutzers mit den Attributen übereinstimmen, die zuvor für diesen Nutzer beobachtet wurden. Dieser Wert ist ein Hinweis darauf, dass der Nutzer ein vertrauenswürdiges Gerät verwendet, mit dem zuvor auf Ihre Website zugegriffen wurde.

PROFILE_MATCH wird nur in den folgenden Szenarien zurückgegeben:

  • Sie verwenden die Multi-Faktor-Authentifizierung (MFA) oder die 2-Faktor-Authentifizierung (2FA) und reCAPTCHA Account Defense kennzeichnet Nutzerprofile als vertrauenswürdig, nachdem Nutzer die MFA- oder 2FA-Herausforderung bestanden haben.
  • Sie kennzeichnen Bewertungen als LEGITIMATE oder PASSED_TWO_FACTOR und reCAPTCHA Account Defense markiert das entsprechende Nutzerprofil als vertrauenswürdig.
RELATED_ACCOUNTS_NUMBER_HIGH Gibt an, dass die Anfrage eine hohe Anzahl verknüpfter Konten enthält. Das bedeutet nicht unbedingt, dass das Konto schlecht ist, aber möglicherweise sind weitere Untersuchungen erforderlich.

Ereignisse annotieren, um Ihr websitespezifisches Modell zu optimieren

Wenn Sie reCAPTCHA Account Defense weitere Informationen zur Verfügung stellen und Ihr websitespezifisches Erkennungsmodell verbessern möchten, müssen Sie die Ereignisse, die Sie bewertet haben, durch Erstellen von Bewertungen annotieren.

Sie merken eine Bewertung an, indem Sie eine Anfrage mit der Bewertungs-ID an die Methode projects.assessments.annotate senden. Im Text dieser Anfrage fügen Sie Labels ein, die zusätzliche Informationen zu einem im Gutachten beschriebenen Ereignis enthalten.

So fügen Sie einer Bewertung eine Anmerkung hinzu:

  1. Legen Sie die Informationen und Labels fest, die Sie je nach Anwendungsfall in den JSON-Anfragetext einfügen möchten.

    In der folgenden Tabelle sind die Labels und Werte aufgeführt, die Sie zum Annotieren von Ereignissen verwenden können:

    Label Beschreibung Beispielanfrage
    reasons Erforderlich. Ein Label zur Unterstützung Ihrer Analysen.

    Stellen Sie innerhalb von Sekunden oder Minuten nach dem Ereignis Echtzeit-Ereignisdetails im reasons-Label bereit, da sie die Echtzeiterkennung beeinflussen.

    Eine Liste der möglichen Werte finden Sie unter Werte für „reasons“.

    Beispiel: Um Kontoübernahmen zu erkennen, geben Sie mit den Werten CORRECT_PASSWORD oder INCORRECT_PASSWORD an, ob das eingegebene Passwort korrekt war. 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 von Bewertungen.

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

    Mögliche Werte: LEGITIMATE oder FRAUDULENT.

    Sie können diese Informationen jederzeit oder im Rahmen 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, mit dem eine Konto-ID einem Ereignis zugeordnet wird.

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

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. Erstellen Sie eine Annotate-Anfrage mit den entsprechenden Labels.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • ASSESSMENT_ID: Wert des Felds name, der 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 Ihre Anmerkung unterstützen. Eine Liste der möglichen Werte finden Sie unter Werte für „reasons“.
    • ACCOUNT_ID: Optional. Die Kennung, die eindeutig mit dem Nutzerkonto auf Ihrer Website verknüpft 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 Fraud Defense 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);
    }
  }
}

Risikobewertung für Kontoübernahmen verwenden und interpretieren

Die Funktion „Risikobewertung für Kontoübernahme“ (Account Takeover, ATO) fügt der Bewertung der Kontosicherheit eine numerische Risikobewertung und menschenlesbare Erklärungen hinzu. Mithilfe dieser Informationen können Sie die Bewertung besser nachvollziehen und Ihre nachfolgenden Aktionen oder Entscheidungen fundierter treffen.

Risikobewertung abrufen

Wenn Sie den Risikowert und die Gründe für die Erklärbarkeit erhalten möchten, senden Sie eine CreateAssessment-Anfrage und fügen Sie event.userInfo.accountId in Ihre Anfrage ein.

Risikobewertung und ‑details ansehen

Der Risikowert und die Gründe für die Erklärbarkeit befinden sich im accountDefenderAssessment.accountTakeoverVerdict-Objekt in der Bewertungsantwort.

  • Risikobewertung: accountDefenderAssessment.accountTakeoverVerdict.risk
  • Risikogründe: accountDefenderAssessment.accountTakeoverVerdict.riskReasons
  • Gründe für Vertrauen: accountDefenderAssessment.accountTakeoverVerdict.trustReasons

Das folgende Snippet zeigt ein Beispiel für die Felder in einer Antwort auf eine Bewertung:

  "accountDefenderAssessment": {
    "labels": ["PROFILE_MATCH"],
    "accountTakeoverVerdict": {
      "risk": 0.249,
      "riskReasons": [{"reason": "CLIENT_ACCESSED_MANY_ACCOUNTS"}],
      "trustReasons": [{"reason": "PROFILE_MATCH"}, {"reason": "ACCOUNT_HISTORY_REPUTABLE"}]
    }
  }

ATO-Risiko-Score interpretieren

Wenn Sie den Risikowert verwenden, legen Sie einen Schwellenwert fest, ab dem Schutzmaßnahmen ergriffen werden sollen.

Verwenden Sie den ATO-Risiko-Score als Alternative zum Label SUSPICIOUS_LOGIN_ACTIVITY. Verwenden Sie nicht sowohl die Risikobewertung als auch das Label, um die Durchsetzung für dieselbe Bewertung auszulösen. Sie können Ihre Erzwingungslogik entweder so konfigurieren, dass sie auf dem Überschreiten des Schwellenwerts durch den Risikoscore oder auf dem Vorhandensein des Labels basiert. Im Allgemeinen bietet der Risikoscore eine detailliertere Bewertung.

Wir empfehlen, die Leistung des Risikowerts mit einem geeigneten Schwellenwert für den Traffic Ihrer Plattform zu bewerten, bevor Sie ihn für die Durchsetzung verwenden.

Um auf den Risikowert zu reagieren, implementieren Sie eine Prüfung in Ihrem Backend, wie im folgenden Snippet gezeigt:

if (assessment.accountDefenderAssessment.accountTakeoverVerdict.risk > YOUR_CHOSEN_THRESHOLD) {
  // Treat as suspicious
  // Implement protective actions
}

Standardgrenzwerte für Risikobewertung

In der folgenden Tabelle finden Sie die Standard-Risikobewertungsgrenzwerte und die erwarteten Falsch-Positiv-Raten (FPR). Wählen Sie einen Schwellenwert basierend auf der akzeptablen Falsch-positiv-Rate aus. Die Leistung kann variieren. Sie müssen den Schwellenwert daher möglicherweise an die beobachtete Leistung anpassen.

Erwartete Falsch-Positiv-Rate Schwellenwert für Risikobewertung
0,1 % 1,0
0,25% 0,9
0,5 % 0,8
1 % 0,7
2 % 0,6
4 % 0,5
8 % 0,4
15 % 0,3
30 % 0,2
60 % 0,1
100 % 0,0

Schwellenwert anpassen

Wenn die beobachtete Falsch-Positiv-Rate zu hoch ist, erhöhen Sie den Grenzwert. Wenn der beobachtete Recall zu niedrig ist und Sie eine höhere Falsch-Positiv-Rate tolerieren können, senken Sie den Schwellenwert.

Zwischenwerte berechnen

Wenn Sie die Falsch-Positiv-Rate für einen Schwellenwert zwischen den Standardwerten schätzen möchten, verwenden Sie die lineare Interpolation. Das folgende Beispiel zeigt, wie die Falsch-Positiv-Rate für einen Schwellenwert von 0,85 berechnet wird:

FPR(T: 0.85) = (FPR(T: 0.8) + FPR(T: 0.9)) / 2 = (0.5% + 0.25%) / 2 = 0.375%

Wenn Sie einen Schwellenwert für eine bestimmte FPR ermitteln möchten, interpolieren Sie zwischen den Standardwerten. Das folgende Beispiel zeigt, wie Sie den Schwellenwert für eine FPR von 5 % ermitteln:

Threshold = 0.4 + (0.5 − 0.4) × (8% − 5%) / (8% − 4%)
Threshold = 0.4 + 0.1 × (3 / 4)
Threshold = 0.4 + 0.075 = 0.475

Bei einem Schwellenwert von 0,475 wird eine FPR von 5% geschätzt.

Gründe für Erklärbarkeit interpretieren

Die Gründe für die Erklärbarkeit geben Aufschluss über Faktoren, die den Risikoscore beeinflussen. Anhand dieser Gründe können Sie Ihre Entscheidungsfindung optimieren.

  • Risikogründe: geben Faktoren an, die mit einem höheren Risiko einer Kontoübernahme verbunden sind.
  • Vertrauensgründe: Hier werden Faktoren angegeben, die auf eine Legitimität hindeuten.

Sowohl Risiko- als auch Vertrauensgründe können für jeden Risikowert angezeigt werden.

Grund Typ Interpretation
PROFILE_MATCH Vertrauen Die Anfrage entspricht einem vertrauenswürdigen Profil, das mit diesem Konto verknüpft ist. Dies entspricht dem Label AccountDefenderLabel.PROFILE_MATCH.
ACCOUNT_HISTORY_REPUTABLE Vertrauen Die bisherigen Aktivitäten des Kontos sind seriös. Es ist unwahrscheinlich, dass das Konto in der Vergangenheit gehackt wurde.
CLIENT_HISTORICAL_BOT_ACTIVITY Risiko Der Client hat in der Vergangenheit botähnliche Zugriffe auf diese Website gesendet. Dieser Grund berücksichtigt die bisherige Reputation und gibt an, dass der Client bekanntermaßen Bots verwendet, auch wenn die aktuelle Anfrage von einem Menschen stammt.
ACCOUNT_IN_LARGE_RELATED_GROUP Risiko Das Konto gehört zu einer großen Gruppe ähnlicher Konten, was darauf hindeutet, dass es Teil eines betrügerischen Netzwerks sein könnte. Zugehörige Konten werden anhand ähnlicher Trafficmuster und Anfragecharakteristika ermittelt.
CLIENT_ACCESSED_MANY_ACCOUNTS Risiko Der Kunde hat auf dieser Website auf viele Konten zugegriffen.

Nächste Schritte