Détecter et empêcher les activités frauduleuses liées aux comptes sur les sites Web

Account Defense vous aide à détecter et à prévenir les activités frauduleuses sur les comptes sur les sites Web. Account Defense surveille les schémas d'activité des utilisateurs et crée un modèle comportemental spécifique au site pour vous aider à identifier l'utilisation abusive d'identifiants et à protéger les comptes utilisateur contre les attaques automatisées.

Fraud Defense vous aide à protéger les actions critiques, telles que la connexion et le paiement. Cependant, il existe de nombreuses formes subtiles d'utilisation abusive de compte qui peuvent être détectées en observant le comportement d'un utilisateur spécifique sur un site Web pendant une période donnée. Account Defense, une fonctionnalité de Fraud Defense, permet d'identifier ces types d'abus subtils en créant un modèle spécifique à votre site Web pour détecter une tendance de comportement suspect ou un changement d'activité. En utilisant le modèle spécifique à votre site, Account Defense vous aide à détecter les éléments suivants :

  • Activités suspectes
  • Comptes avec des comportements similaires
  • Requêtes provenant d'appareils marqués comme fiables pour des utilisateurs spécifiques

En fonction de l'analyse d'Account Defense et du modèle spécifique au site, vous pouvez effectuer les actions suivantes :

  • Limiter ou désactiver les comptes frauduleux.
  • Empêchez les tentatives de prise de contrôle de compte.
  • Limiter les prises de contrôle de compte réussies.
  • N'accordez l'accès qu'aux requêtes provenant de comptes utilisateur légitimes.
  • Simplifiez la connexion des utilisateurs depuis l'un de leurs appareils vérifiés.

Avant de commencer

  1. Préparer votre environnement pour Google Cloud Fraud Defense
  2. Créez une clé de site basée sur un score.

Configurer vos pages Web pour Account defense

Account Defense nécessite une compréhension complète des activités du compte pour permettre une détection efficace. Pour commencer à transmettre les activités liées au compte à Account defense, et pour créer et améliorer votre modèle spécifique au site, procédez comme suit :

  1. Activer la collecte de données de télémétrie horizontale.
  2. Créer des rapports sur les actions utilisateur critiques
  3. Évaluez les événements utilisateur critiques.
  4. Annotez les événements utilisateur pour régler votre modèle spécifique au site.

Activer la collecte de données de télémétrie horizontale

Account Defense nécessite une vue complète des actions de l'utilisateur, par exemple si l'utilisateur est connecté ou sur le point de se connecter. Pour activer la collecte passive des données de télémétrie horizontales par Account Defense, chargez le script JavaScript reCAPTCHA avec la clé de site basée sur un score que vous avez créée en arrière-plan de toutes les pages Web faisant partie de votre workflow utilisateur.

L'exemple suivant montre comment charger le script JavaScript reCAPTCHA dans une page Web.

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

Créer des rapports sur les actions utilisateur critiques

Pour détecter les schémas d'activité suspects et créer un meilleur modèle des schémas d'activité types sur votre site, Account Defense a besoin d'informations sur les actions critiques des utilisateurs. Par conséquent, signalez les actions critiques des utilisateurs sur les pages Web en appelant grecaptcha.enterprise.execute() sur ces actions critiques.

Nous vous recommandons de signaler toutes les actions critiques des utilisateurs, car cela permet de collecter des signaux supplémentaires. Pour chaque action utilisateur que vous souhaitez signaler, remplacez la valeur du paramètre action de grecaptcha.enterprise.execute() par un nom d'action qui décrit l'action utilisateur.

Le tableau suivant liste les noms d'actions que vous pouvez utiliser lorsque vous signalez les actions utilisateur critiques.

Nom de l'action Événement déclenché par l'utilisateur ou action de l'utilisateur
LOGIN

Connectez-vous au site Web.
REGISTRATION Inscription sur le site Web.
SECURITY_QUESTION_CHANGE Demandez à modifier la question secrète.
PASSWORD_RESET Demandez à réinitialiser le mot de passe.
PHONE_NUMBER_UPDATE Demande de modification du numéro de téléphone.
EMAIL_UPDATE Demande de modification de l'adresse e-mail.
ACCOUNT_UPDATE Demander à modifier les informations liées au compte, telles que les coordonnées.
TRIGGER_MFA Action qui déclenche une demande de validation MFA.
REDEEM_CODE Demander à utiliser un code.
LIST_PAYMENT_METHODS Récupérez la liste des modes de paiement.

L'exemple suivant montre comment appeler grecaptcha.enterprise.execute() lors de la mise à jour d'un numéro de téléphone :

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

Évaluer les événements utilisateur critiques

Lorsque vous appelez grecaptcha.enterprise.execute() lors d'une action utilisateur, un jeton est généré. Pour les événements utilisateur critiques, tels que les connexions réussies et échouées, les inscriptions et les actions des utilisateurs connectés, créez une évaluation pour évaluer les résultats de l'appel grecaptcha.enterprise.execute(). L'évaluation vous fournit un verdict de risque, que vous pouvez utiliser pour prendre une décision sur la manière de gérer les activités potentiellement frauduleuses. Vous pouvez par exemple bloquer les requêtes suspectes, demander une validation pour les connexions risquées et examiner les comptes qui vous intéressent.

Account Defense nécessite que vous fournissiez un identifiant de compte stable pour effectuer l'évaluation et attribuer l'activité de l'utilisateur (par exemple, les demandes de connexion, les demandes de connexion et les demandes d'inscription) à un compte spécifique. Cela permet à Account Defense de traiter les schémas d'activité des utilisateurs afin de créer un modèle d'activité pour chaque compte, et ainsi mieux détecter le trafic anormal et abusif.

Choisissez un identifiant de compte stable accountId qui n'est pas souvent modifié par l'utilisateur et fournissez-le à l'évaluation dans la méthode projects.assessments.create. Cet identifiant de compte stable doit avoir la même valeur pour tous les événements liés au même utilisateur. Vous pouvez fournir les éléments suivants comme identifiant de compte :

Identifiants utilisateur

Si chaque compte peut être associé de manière unique à un nom d'utilisateur, une adresse e-mail ou un numéro de téléphone stables, vous pouvez l'utiliser comme accountId. Lorsque vous fournissez de tels identifiants intersites (identifiants pouvant être réutilisés sur plusieurs sites), Fraud Defense utilise ces informations pour améliorer la protection de vos comptes utilisateur en fonction de modèles intersites. Pour ce faire, il signale les identifiants de compte abusifs et utilise les connaissances des schémas d'utilisation abusive intersites liés à ces identifiants.

Si vous disposez d'un ID utilisateur interne associé de manière unique à chaque compte, vous pouvez également le fournir en tant que accountId.

Hachées ou chiffrées

Si vous ne disposez pas d'un ID utilisateur interne associé de manière unique à chaque compte, vous pouvez transformer n'importe quel identifiant stable en identifiant de compte opaque spécifique au site. Cet identifiant est toujours nécessaire pour que Fraud Defense Account Defender comprenne les schémas d'activité des utilisateurs et détecte les comportements anormaux, mais il n'est pas partagé avec d'autres sites.

Choisissez un identifiant de compte stable et rendez-le opaque avant de l'envoyer à Fraud Defense en utilisant le chiffrement ou le hachage :

  • Chiffrement (recommandé) : chiffrez l'identifiant du compte à l'aide d'une méthode de chiffrement déterministe qui produit un texte chiffré stable. Pour obtenir des instructions détaillées, consultez Chiffrer des données de manière déterministe. Lorsque vous choisissez le chiffrement symétrique plutôt que le hachage, vous n'avez pas besoin de conserver un mappage entre vos identifiants utilisateur et les identifiants utilisateur opaques correspondants. Déchiffrez les identifiants opaques renvoyés par Fraud Defense pour les transformer en identifiant utilisateur.

  • Hachage : nous vous recommandons de hacher l'identifiant du compte à l'aide de la méthode SHA256-HMAC avec un salage personnalisé de votre choix. Étant donné que les hachages sont unidirectionnels, vous devez conserver un mappage entre les hachages générés et vos identifiants utilisateur afin de pouvoir mapper l'identifiant de compte haché renvoyé aux comptes d'origine.

En plus de fournir un identifiant de compte stable pour toutes les requêtes liées au compte, vous pouvez fournir des identifiants de compte supplémentaires, potentiellement non stables, pour certaines requêtes spécifiques. Les identifiants de compte spécifiques au contexte fournis en plus de accountId aident Account defense à mieux analyser l'activité des utilisateurs et à détecter les tentatives de prise de contrôle de compte afin de protéger les comptes de vos utilisateurs. Lorsque vous fournissez des identifiants supplémentaires, Google Cloud Fraud Defense utilise ces informations pour améliorer la protection de vos comptes utilisateur en fonction de modèles intersites. Pour ce faire, il signale les identifiants de compte abusifs et utilise les connaissances sur les schémas d'utilisation abusive intersites liés à ces identifiants. Par exemple, vous pouvez fournir les éléments suivants :

  • Nom d'utilisateur, adresse e-mail ou numéro de téléphone utilisé comme identifiant de connexion pour les demandes de connexion

  • Adresse e-mail ou numéro de téléphone validé pour une demande d'authentification multifacteur

  • Adresse e-mail ou numéro de téléphone (principal ou secondaire) fourni par l'utilisateur lors d'une demande de mise à jour de compte

  • Adresses e-mail et numéros de téléphone fournis par l'utilisateur lors d'une demande d'inscription

Ajoutez l'identifiant de compte stable choisi au paramètre accountId dans la méthode projects.assessments.create pour toutes les requêtes liées au compte. Vous pouvez également fournir des identifiants de compte supplémentaires pour les requêtes concernées en utilisant le champ userIds dans l'évaluation.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • TOKEN : jeton renvoyé par l'appel grecaptcha.enterprise.execute()
  • KEY_ID : clé reCAPTCHA associée au site
  • ACCOUNT_ID : identifiant associé de manière unique au compte utilisateur de votre site Web
  • EMAIL_ADDRESS : facultatif. Adresse e-mail associée à cette requête, le cas échéant
  • PHONE_NUMBER : facultatif. Numéro de téléphone associé à cette requête, le cas échéant.
  • USERNAME : facultatif. Nom d'utilisateur associé à cette requête, le cas échéant

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Exemple de code

Java

Pour vous authentifier auprès de Fraud Defense, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 


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;
  }
}

Interpréter le verdict de risque des événements utilisateur critiques

Lorsque vous créez une évaluation avec Account Defense activé, Account Defense renvoie accountDefenderAssessment dans la réponse à l'évaluation. La valeur de accountDefenderAssessment vous aide à évaluer si l'activité de l'utilisateur est légitime ou frauduleuse. Elle renvoie également un ID d'évaluation que vous devez utiliser lors de l'annotation des événements utilisateur.

Voici un exemple de réponse JSON :

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

Le champ accountDefenderAssessment peut présenter l'une des valeurs suivantes :

Valeur Description
SUSPICIOUS_LOGIN_ACTIVITY Indique que la requête présente un risque élevé de bourrage d'identifiants ou de prise de contrôle de compte.
SUSPICIOUS_ACCOUNT_CREATION Indique que la requête présente un risque élevé de création de compte abusive.
PROFILE_MATCH

Indique que les attributs de l'utilisateur correspondent aux attributs qui ont été vus précédemment pour cet utilisateur particulier. Cette valeur indique que l'utilisateur se trouve sur un appareil de confiance qui a déjà été utilisé pour accéder à votre site Web.

PROFILE_MATCH n'est renvoyé que dans les cas suivants :
RELATED_ACCOUNTS_NUMBER_HIGH Indique que la demande comporte un grand nombre de comptes associés. Cela ne signifie pas nécessairement que le compte est mauvais, mais cela peut nécessiter une investigation plus approfondie.

Annoter des événements pour affiner votre modèle spécifique au site

Pour fournir plus d'informations à Account defense et améliorer votre modèle de détection spécifique au site, vous devez annoter les événements que vous avez évalués en créant des évaluations.

Pour annoter une évaluation, envoyez une requête à la méthode projects.assessments.annotate avec l'ID de l'évaluation. Dans le corps de cette requête, vous incluez des libellés fournissant des informations supplémentaires sur un événement décrit dans l'évaluation.

Pour annoter une évaluation, procédez comme suit :

  1. Déterminez les informations et les étiquettes à ajouter dans le corps JSON de la requête en fonction de votre cas d'utilisation.

    Le tableau suivant liste les libellés et les valeurs que vous pouvez utiliser pour annoter des événements :

    Libellé Description Exemple de requête
    reasons Obligatoire. Une étiquette pour étayer vos évaluations.

    Fournissez des détails sur les événements en temps réel dans le libellé reasons quelques secondes ou minutes après l'événement, car ils influencent la détection en temps réel.

    Pour obtenir la liste des valeurs possibles, consultez Valeurs des motifs.

    Exemple : Pour détecter les prises de contrôle de compte, indiquez si le mot de passe saisi était correct avec les valeurs CORRECT_PASSWORD ou INCORRECT_PASSWORD. Si vous avez déployé votre propre MFA, vous pouvez ajouter les valeurs suivantes : INITIATED_TWO_FACTOR et PASSED_TWO_FACTOR ou FAILED_TWO_FACTOR. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Facultatif. Libellé indiquant la légitimité des évaluations.

    Fournissez des informations sur les événements de connexion et d'inscription pour valider ou corriger vos évaluations des risques dans l'étiquette annotation.

    Valeurs possibles : LEGITIMATE ou FRAUDULENT.

    Vous pouvez envoyer ces informations à tout moment ou dans le cadre d'un job par lot. Toutefois, nous vous recommandons d'envoyer ces informations quelques secondes ou minutes après l'événement, car elles influencent la détection en temps réel.

    		 
          {
       "annotation": "LEGITIMATE"
      }
    accountId

    Facultatif. Libellé permettant d'associer un ID de compte à un événement.

    Si vous avez créé une évaluation sans ID de compte, utilisez ce libellé pour fournir l'ID de compte d'un événement chaque fois qu'il est disponible.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. Créez une requête d'annotation avec les étiquettes appropriées.

    Avant d'utiliser les données de requête, effectuez les remplacements suivants :

    • ASSESSMENT_ID : valeur du champ name renvoyée par l'appel projects.assessments.create.
    • ANNOTATION : facultatif. Une étiquette indiquant si l'évaluation est légitime ou frauduleuse.
    • REASONS : facultatif. Raisons qui étayent votre annotation. Pour obtenir la liste des valeurs possibles, consultez Valeurs des motifs.
    • ACCOUNT_ID : (facultatif) identifiant associé de manière unique au compte utilisateur sur votre site Web.

    Pour en savoir plus, consultez Libellés pour les annotations.

    Méthode HTTP et URL : 

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

    Corps JSON de la requête : 

    {
  "annotation": ANNOTATION,
  "reasons": REASONS,
  "accountId": ACCOUNT_ID
}

    Pour envoyer votre requête, choisissez l'une des options suivantes :

    curl

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    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

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    $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

    Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.

Exemple de code

Java

Pour vous authentifier auprès de Fraud Defense, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 


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);
    }
  }
}

Utiliser et interpréter le score de risque de prise de contrôle de compte

La fonctionnalité de score de risque de prise de contrôle de compte (ATO) ajoute un score de risque numérique et des explications lisibles par l'humain à l'évaluation Account Defense. Ces insights vous aident à comprendre l'évaluation et à prendre des décisions ou des mesures ultérieures.

Obtenir le score de risque

Pour recevoir le score de risque et les motifs d'explicabilité, envoyez une requête CreateAssessment et incluez event.userInfo.accountId dans votre requête.

Lire le score de risque et les détails

Le score de risque et les raisons de l'explicabilité se trouvent dans l'objet accountDefenderAssessment.accountTakeoverVerdict de la réponse d'évaluation.

  • Score de risque : accountDefenderAssessment.accountTakeoverVerdict.risk
  • Motifs du risque : accountDefenderAssessment.accountTakeoverVerdict.riskReasons
  • Motifs de confiance : accountDefenderAssessment.accountTakeoverVerdict.trustReasons

L'extrait de code suivant montre un exemple de champs dans une réponse d'évaluation :

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

Interpréter le score de risque de prise de contrôle de compte

Lorsque vous utilisez le score de risque, établissez un seuil pour déterminer quand prendre des mesures de protection.

Utilisez le score de risque de piratage de compte comme alternative au libellé SUSPICIOUS_LOGIN_ACTIVITY. N'utilisez pas à la fois le score de risque et l'étiquette pour déclencher l'application de mesures sur la même évaluation. Vous pouvez configurer votre logique d'application en fonction du score de risque dépassant votre seuil ou de la présence de l'étiquette. En général, le score de risque offre une évaluation plus précise.

Nous vous recommandons d'évaluer les performances du score de risque avec un seuil approprié sur le trafic de votre plate-forme avant de l'utiliser pour l'application forcée.

Pour agir sur le score de risque, implémentez une vérification dans votre backend, comme indiqué dans l'extrait suivant :

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

Seuils de score de risque standards

Le tableau suivant indique les seuils de score de risque standards et les taux de faux positifs (TFP) attendus. Choisissez un seuil en fonction de votre taux de faux positifs acceptable. Les performances peuvent varier. Vous devrez donc peut-être ajuster votre seuil en fonction des performances observées.

Tolérance au risque Seuil recommandé Taux maximal de faux positifs
Faible 0,5 4 %
Moyenne 0,7 1 %
Élevée 0,9 0,25 %

Interpréter les raisons de l'explicabilité

Les raisons de l'explicabilité fournissent des insights sur les facteurs qui influencent le score de risque. Utilisez ces raisons pour affiner votre prise de décision.

  • Motifs de risque : indiquent les facteurs associés à un risque plus élevé de prise de contrôle de compte.
  • Raisons de faire confiance : indiquez les facteurs qui suggèrent la légitimité.

Les raisons de risque et de confiance peuvent apparaître pour n'importe quel score de risque.

Motif Type Interprétation
PROFILE_MATCH Confiance La demande correspond à un profil de confiance associé à ce compte. Cela équivaut au libellé AccountDefenderLabel.PROFILE_MATCH.
ACCOUNT_HISTORY_REPUTABLE Confiance L'historique d'activité du compte est fiable. Il est peu probable que le compte ait été compromis par le passé.
CLIENT_HISTORICAL_BOT_ACTIVITY Risque Le client a déjà envoyé du trafic de type bot vers ce site par le passé. Cette raison intègre la réputation historique et indique que le client est connu pour utiliser des bots, même si la requête actuelle est effectuée par un humain.
ACCOUNT_IN_LARGE_RELATED_GROUP Risque Le compte fait partie d'un grand groupe de comptes associés, ce qui indique qu'il peut faire partie d'un réseau frauduleux. Les comptes associés sont identifiés en fonction de leurs caractéristiques de trafic et de requête similaires.
CLIENT_ACCESSED_MANY_ACCOUNTS Risque Le client a été observé en train d'accéder à de nombreux comptes sur ce site.
DISPOSABLE_EMAIL_DOMAIN Risque L'adresse e-mail fournie appartient à un fournisseur connu ou suspecté de domaines de messagerie temporaires et jetables (à usage unique).

Ajuster le seuil de risque de prise de contrôle de compte

Après avoir évalué les performances du score de risque de prise de contrôle de compte sur votre trafic, vous devrez peut-être ajuster votre seuil pour atteindre un taux de faux positifs (FPR) et un rappel acceptables. Vous pouvez ajuster votre seuil en fonction des performances observées ou calculer des valeurs intermédiaires pour cibler un taux de faux positifs spécifique.

Ajuster votre seuil

Si le taux de faux positifs observé est trop élevé, augmentez le seuil. Si le rappel observé est trop faible et que vous pouvez tolérer un taux de faux positifs plus élevé, diminuez le seuil.

Calculer les valeurs intermédiaires

Pour estimer le taux de faux positifs pour un seuil compris entre les valeurs standards, utilisez l'interpolation linéaire. L'exemple suivant montre comment calculer le taux de faux positifs pour un seuil de 0,85 :

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

Pour trouver un seuil pour un taux de faux positifs spécifique, interpolez entre les valeurs standards. L'exemple suivant montre comment trouver le seuil pour un taux de faux positifs de 5 % :

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

Un seuil de 0,475 est estimé pour générer un TFP de 5 %.

Étapes suivantes