Kontobezogene betrügerische Aktivitäten in mobilen Apps erkennen und verhindern

Mit Account Defense können Sie betrügerische Kontoaktivitäten in mobilen Anwendungen erkennen und verhindern. Account Defense überwacht die Aktivitätsmuster von Nutzern und erstellt ein websitespezifisches Verhaltensmodell, mit dem Sie den Missbrauch von Anmeldedaten erkennen und Nutzerkonten vor automatisierten Angriffen schützen können.

Mit Fraud Defense können Sie kritische Aktionen wie Anmeldung und Bezahlung schützen. Es gibt jedoch viele subtile Formen des Kontomissbrauchs, die sich erkennen lassen, wenn das Verhalten eines bestimmten Nutzers in einer mobilen App über einen gewissen Zeitraum beobachtet wird. Account Defense, eine Funktion von Fraud Defense, hilft Ihnen, diese Art von subtilem Missbrauch zu erkennen, indem ein websitespezifisches Modell für Ihre mobile Anwendung erstellt wird, um einen Trend zu verdächtigem Verhalten oder eine Änderung der Aktivität zu erkennen. Mithilfe des websitespezifischen Modells hilft Ihnen Account Defense, 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

Basierend auf der Analyse von Account Defense und dem websitespezifischen Modell können Sie die folgenden Maßnahmen ergreifen:

  • Betrügerische Konten einschränken oder deaktivieren
  • Kontoübernahmeversuche verhindern
  • Maßnahmen gegen erfolgreiche Kontoübernahmen ergreifen
  • Gewähren Sie nur Anfragen von legitimen Nutzerkonten Zugriff.
  • Nutzer, die sich von einem ihrer vertrauenswürdigen Geräte aus anmelden, können sich einfacher anmelden.

Hinweis

  1. Account Defense für mobile Anwendungen ist verfügbar, nachdem Sie Ihrem Projekt ein Rechnungskonto hinzugefügt und so eine automatische Sicherheitsüberprüfung ausgelöst haben. Fügen Sie Ihrem Projekt ein Rechnungskonto hinzu, um Ihre mobile Anwendung für diese Funktion einzurichten.
  2. Umgebung für Google Cloud Fraud Defense vorbereiten
  3. Erstellen Sie einen punktzahlbasierten Schlüssel.

Mobile Anwendung für Account Defense konfigurieren

Für Account Defense ist ein umfassendes Verständnis der Kontoaktivitäten erforderlich, um eine effektive Erkennung zu ermöglichen. So senden Sie kontobezogene Aktivitäten an Account Defense und erstellen und verbessern Ihr websitespezifisches Modell:

  1. Fraud Defense in Ihre mobile Anwendung einbinden

  2. Berichte zu kritischen Nutzeraktionen
  3. Kritische Nutzerereignisse bewerten:
  4. Nutzerereignisse annotieren, um Ihr websitespezifisches Modell zu optimieren

Berichte zu kritischen Nutzeraktionen erstellen

Damit Account Defense verdächtige Aktivitätsmuster erkennen und ein besseres Modell typischer Aktivitätsmuster auf Ihrer Website erstellen kann, benötigt es Informationen zu kritischen Nutzeraktionen. Rufen Sie für jede Aktion Ihrer App, die mit Fraud Defense geschützt ist, die Methode execute() mit RecaptchaAction auf. Weitere Informationen zu execute() und RecaptchaAction finden Sie hier:

Die reCAPTCHA-Bibliothek bietet eine Reihe integrierter Aktionen. Bei Bedarf können Sie benutzerdefinierte Aktionen erstellen.

In der folgenden Tabelle sind die Aktionsnamen aufgeführt, die Sie beim Melden kritischer Nutzeraktionen verwenden können.

Aktionsname Vom Nutzer initiiertes Ereignis oder Nutzeraktion
LOGIN

Melde dich in der App an.
SIGNUP

Registrieren Sie sich in der App.

Kritische Nutzerereignisse bewerten

Wenn Sie execute() für eine Nutzeraktion aufrufen, wird ein Token generiert. Erstellen Sie für kritische Nutzerereignisse wie erfolgreiche und fehlgeschlagene Anmeldungen, Registrierungen und Aktionen der angemeldeten Nutzer eine Bewertung, um die Ergebnisse des execute()-Aufrufs zu bewerten. Die Bewertung liefert Ihnen ein Risikourteil, anhand dessen Sie entscheiden können, wie Sie mit potenziell betrügerischen Aktivitäten umgehen. Sie können unter anderem verdächtige Anfragen blockieren, riskante Anmeldungen prüfen und relevante Konten untersuchen.

Für Account Defense müssen Sie eine stabile Konto-ID angeben, um die Bewertung vorzunehmen und Nutzeraktivitäten wie Anmeldeanfragen, Anfragen im angemeldeten Zustand und Registrierungsanfragen einem bestimmten Konto zuzuordnen. So kann Account Defense Muster von Nutzeraktivitäten verarbeiten, um ein Aktivitätsmodell für jedes Konto zu erstellen und so anomalen und missbräuchlichen Traffic besser zu erkennen.

Wählen Sie eine stabile Konto-ID accountId aus, die vom Nutzer nicht oft geändert wird, und geben Sie sie in der Methode projects.assessments.create für die Bewertung an. Diese stabile Kontokennung 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 Fraud Defense diese Informationen, um den Schutz Ihrer Nutzerkonten basierend auf websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Kontokennungen gekennzeichnet und Erkenntnisse zu websiteübergreifenden Missbrauchsmustern im Zusammenhang mit diesen Kennungen genutzt.

Wenn Sie eine interne Nutzer-ID haben, die jedem Konto eindeutig zugeordnet ist, können Sie diese alternativ als accountId angeben.

Gehasht oder verschlüsselt

Wenn Sie keine interne Nutzer-ID haben, die jedem Konto eindeutig zugeordnet ist, können Sie jede stabile Kennung in eine undurchsichtige, websitespezifische Kontokennung umwandeln. Diese Kennung wird weiterhin für Fraud Defense Account Defender benötigt, um Muster von Nutzeraktivitäten zu verstehen und ungewöhnliches Verhalten zu erkennen. Sie wird jedoch nicht an andere Websites weitergegeben.

Wählen Sie eine beliebige stabile Konto-ID aus und machen Sie sie unkenntlich, bevor Sie sie an Fraud Defense senden, indem Sie sie verschlüsseln oder hashen:

  • Verschlüsselung (empfohlen): Verschlüsseln Sie die Konto-ID 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 anstelle von Hash-Technologie entscheiden, müssen Sie keine Zuordnung zwischen Ihren Nutzer-IDs und den entsprechenden intransparenten Nutzer-IDs verwalten. Entschlüsseln Sie die von Fraud Defense zurückgegebenen intransparenten Kennungen, 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 zu einer stabilen Konto-ID für alle kontobezogenen Anfragen können Sie für einige spezifische Anfragen zusätzliche Konto-IDs angeben, die möglicherweise nicht stabil sind. Kontextspezifische Konto-IDs, die zusätzlich zur accountId bereitgestellt werden, helfen 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 Google Cloud Fraud Defense diese Informationen, um den Schutz Ihrer Nutzerkonten anhand von websiteübergreifenden Modellen zu verbessern. Dazu werden missbräuchliche Kontokennungen gekennzeichnet und Erkenntnisse zu websiteübergreifenden Missbrauchsmustern 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 vom Nutzer bei einer Anfrage zur Kontoaktualisierung angegeben wurde

  • Die E-Mail-Adressen und Telefonnummern, die der Nutzer bei einer Registrierungsanfrage angibt

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

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID in Google Cloud
  • TOKEN: vom Aufruf execute() zurückgegebenes Token
  • KEY_ID: reCAPTCHA-Schlüssel, der mit der App verknüpft ist
  • ACCOUNT_ID: die Kennung, die eindeutig mit dem Nutzerkonto für ein Nutzerkonto in Ihrer App verknüpft ist
  • EMAIL_ADDRESS: Optional. Eine mit dieser Anfrage verknüpfte E-Mail-Adresse, 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,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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 die 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 aktiviertem 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,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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 missbräuchliche Erstellung von Konten darstellt.
PROFILE_MATCH

Gibt an, dass die Attribute des Nutzers mit den Attributen übereinstimmen, die zuvor für diesen bestimmten Nutzer erkannt wurden. Dieser Wert ist ein Indikator dafür, dass sich der Nutzer auf einem vertrauenswürdigen Gerät befindet, das zuvor für den Zugriff auf Ihre mobile Anwendung verwendet wurde.

PROFILE_MATCH wird nur in den folgenden Szenarien zurückgegeben:

Ereignisse annotieren, um Ihr standortspezifisches Modell zu optimieren

Wenn Sie Account Defense weitere Informationen zur Verfügung stellen und Ihr standortspezifisches Erkennungsmodell verbessern möchten, müssen Sie die von Ihnen bewerteten Ereignisse mit Anmerkungen versehen, indem Sie Bewertungen erstellen.

Sie können eine Bewertung mit Anmerkungen versehen, indem Sie eine Anfrage mit der Bewertungs-ID an die Methode projects.assessments.annotate senden. Im Text dieser Anfrage fügen Sie Labels mit zusätzlichen Informationen zu einem in der Bewertung beschriebenen Ereignis ein.

So fügen Sie einer Bewertung Anmerkungen hinzu:

  1. Legen Sie die Informationen und Labels fest, die je nach Anwendungsfall im JSON-Anfragetext hinzugefügt werden sollen.

    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 Bewertungen.

    Geben Sie im Label reasons innerhalb weniger Sekunden oder Minuten nach dem Ereignis Echtzeit-Ereignisdetails an, da sie die Echtzeiterkennung beeinflussen.

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

    Beispiel: Wenn Sie Kontoübernahmen erkennen möchten, fügen Sie eine Annotation hinzu, ob das eingegebene Passwort mit den Werten CORRECT_PASSWORD oder INCORRECT_PASSWORD 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, das die Legitimität von Bewertungen angibt.

    Geben Sie Fakten zu Anmelde- und Registrierungsereignissen an, um Ihre Risikobewertungen im Label annotation 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 innerhalb weniger Sekunden oder Minuten nach dem Ereignis zu senden, da sie die Echtzeiterkennung beeinflussen.

    		 
          {
       "annotation": "LEGITIMATE"
      }
    accountId

    Optional. Ein Label, mit dem eine Konto-ID mit einem Ereignis verknüpft wird.

    Wenn Sie eine Bewertung ohne Konto-ID erstellt haben, können Sie mit diesem Label die Konto-ID eines Ereignisses angeben, sofern verfügbar.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. Erstellen Sie eine Annotationsanfrage mit den entsprechenden Labels.

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • ASSESSMENT_ID: Wert des Felds name, der vom Aufruf projects.assessments.create zurückgegeben wird.
    • ANNOTATION: Optional. Ein Label, das angibt, ob die Bewertung legitim oder betrügerisch ist.
    • REASONS: Optional. Gründe, die Ihre Annotation untermauern. Eine Liste der möglichen Werte finden Sie unter Werte für Gründe.
    • ACCOUNT_ID: Optional. Die Kennung, die eindeutig mit dem Nutzerkonto in Ihrer App 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 die 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übernahmen“ fügt der Account Defense-Bewertung eine numerische Risikobewertung und menschenlesbare Erläuterungen hinzu. Diese Informationen helfen Ihnen, die Bewertung zu verstehen und Ihre nachfolgenden Aktionen oder Entscheidungen zu 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 lesen

Der Risikowert und die Erklärbarkeitsgründe befinden sich im Objekt accountDefenderAssessment.accountTakeoverVerdict in der Antwort auf die Bewertung.

  • 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 Bewertungsantwort:

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

ATO-Risikobewertung interpretieren

Wenn Sie die Risikobewertung verwenden, legen Sie einen Schwellenwert fest, um zu bestimmen, wann Schutzmaßnahmen ergriffen werden sollen.

Verwenden Sie den ATO-Risikowert als Alternative zum Label SUSPICIOUS_LOGIN_ACTIVITY. Verwenden Sie nicht sowohl die Risikobewertung als auch das Label, um eine Maßnahme für dieselbe Bewertung auszulösen. Sie können die Erzwingungslogik entweder so konfigurieren, dass sie ausgelöst wird, wenn die Risikobewertung Ihren Schwellenwert überschreitet, oder wenn das Label vorhanden ist. Im Allgemeinen bietet der Risikowert eine detailliertere Bewertung.

Wir empfehlen, die Leistung der Risikobewertung mit einem geeigneten Schwellenwert für den Traffic Ihrer Plattform zu bewerten, bevor Sie sie für Maßnahmen verwenden.

Wenn Sie auf die Risikobewertung reagieren möchten, 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 die Risikobewertung

In der folgenden Tabelle sind die Standardgrenzwerte für die Risikobewertung und die erwarteten falsch-positiven Raten (FPR) aufgeführt. Wählen Sie einen Schwellenwert basierend auf Ihrer akzeptablen FPR aus. Die Leistung kann variieren. Daher müssen Sie den Grenzwert möglicherweise an die beobachtete Leistung anpassen.

Risikotoleranz Empfohlener Schwellenwert Maximale Rate falsch positiver Ergebnisse
Niedrig 0,5 4 %
Mittel 0,7 1 %
Hoch 0,9 0,25 %

Gründe für die Erklärbarkeit interpretieren

Die Erklärbarkeitsgründe geben Aufschluss über die Faktoren, die die Risikobewertung beeinflussen. Nutzen Sie diese Gründe, um Ihre Entscheidungsfindung zu optimieren.

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

Für jeden Risikowert können sowohl Risiko- als auch Vertrauensgründe 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-ähnlichen Traffic an diese Website gesendet. Dieser Grund bezieht sich auf die bisherige Bewertung 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 von verknüpften Konten, was darauf hindeutet, dass es Teil eines betrügerischen Netzwerks sein könnte. Ähnliche Konten werden anhand ähnlicher Trafficmuster und Anfrageeigenschaften identifiziert.
CLIENT_ACCESSED_MANY_ACCOUNTS Risiko Der Client hat auf viele Konten auf dieser Website zugegriffen.
DISPOSABLE_EMAIL_DOMAIN Risiko Die angegebene E‑Mail-Adresse gehört zu einem bekannten oder mutmaßlichen Anbieter von temporären Wegwerf-E‑Mail-Domains (einmalige Verwendung).

Risikoschwellenwert für Kontoübernahmen anpassen

Nachdem Sie die Leistung der Risikobewertung für die Kontoübernahme für Ihren Traffic bewertet haben, müssen Sie möglicherweise den Schwellenwert anpassen, um die gewünschte falsch-positive Rate (FPR) und den gewünschten Recall zu erreichen. Sie können den Schwellenwert anhand der beobachteten Leistung anpassen oder Zwischenwerte berechnen, um eine bestimmte FPR zu erreichen.

Schwellenwert anpassen

Wenn die beobachtete FPR zu hoch ist, erhöhen Sie den Schwellenwert. Wenn der beobachtete Recall zu niedrig ist und Sie eine höhere FPR tolerieren können, verringern Sie den Schwellenwert.

Zwischenwerte berechnen

Verwenden Sie die lineare Interpolation, um die Falsch-Positiv-Rate für einen Schwellenwert zwischen den Standardwerten zu schätzen. Im folgenden Beispiel wird gezeigt, wie die FPR 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. Im folgenden Beispiel wird gezeigt, 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 % erwartet.

Nächste Schritte