Rilevare e prevenire attività fraudolente relative all'account sui siti web

Questo documento mostra come utilizzare reCAPTCHA Account Defense per rilevare e prevenire attività fraudolente correlate agli account sui siti web.

reCAPTCHA ti aiuta a proteggere le azioni critiche, come l'accesso e il pagamento. Tuttavia, esistono molte forme sottili di abuso dell'account che possono essere rilevate osservando il comportamento di un utente specifico su un sito web per un periodo di tempo. reCAPTCHA Account Defender aiuta a identificare questi tipi di abuso sottile creando un modello specifico per il tuo sito web per rilevare una tendenza di comportamento sospetto o un cambiamento nell'attività. Utilizzando il modello specifico per il sito, reCAPTCHA Account Defender ti aiuta a rilevare quanto segue:

  • Attività sospette
  • Account con comportamenti simili
  • Richieste provenienti da dispositivi contrassegnati come attendibili per utenti specifici

In base all'analisi di reCAPTCHA Account Defender e del modello specifico per il sito, puoi intraprendere le seguenti azioni:

  • Limitare o disattivare gli account fraudolenti.
  • Prevenire i tentativi di takeover dell'account.
  • Mitigare le violazioni degli account.
  • Concedi l'accesso solo alle richieste provenienti da account utente legittimi.
  • Ridurre le difficoltà per gli utenti che accedono da uno dei loro dispositivi attendibili.

Prima di iniziare

  1. Prepara l'ambiente per reCAPTCHA.
  2. Crea una chiave di sito basata sul punteggio.

Configura le tue pagine web per reCAPTCHA Account Defense

reCAPTCHA Account Defense richiede una comprensione completa delle attività dell'account per consentire un rilevamento efficace. Per iniziare a inviare attività correlate all'account a reCAPTCHA Account Defense e per creare e migliorare il modello specifico per il sito, procedi nel seguente modo:

  1. Abilita la raccolta di dati di telemetria orizzontali.
  2. Report sulle azioni utente critiche.
  3. Valuta gli eventi utente critici.
  4. Annota gli eventi utente per ottimizzare il modello specifico per il sito.

Abilita la raccolta di dati di telemetria orizzontali

reCAPTCHA Account Defense richiede una visione completa delle azioni dell'utente, ad esempio se l'utente ha eseguito l'accesso o sta per eseguirlo. Per attivare la raccolta passiva dei dati di telemetria orizzontale da parte di reCAPTCHA Account Defense, carica lo script JavaScript reCAPTCHA con la chiave del sito basata sul punteggio che hai creato in background di tutte le pagine web che fanno parte del flusso di lavoro dell'utente.

Il seguente esempio mostra come caricare lo script JavaScript di reCAPTCHA in una pagina web.

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

Report sulle azioni utente critiche

Per rilevare pattern di attività sospette e creare un modello migliore di pattern di attività tipici sul tuo sito, reCAPTCHA Account Defense ha bisogno delle informazioni sulle azioni utente critiche. Pertanto, segnala le azioni critiche degli utenti sulle pagine web chiamando grecaptcha.enterprise.execute() su queste azioni critiche degli utenti.

Ti consigliamo di segnalare tutte le azioni utente critiche perché ciò contribuisce alla raccolta di ulteriori segnali. Per ogni azione dell'utente di cui vuoi generare un report, sostituisci il valore del parametro action di grecaptcha.enterprise.execute() con un nome di azione che descriva l'azione dell'utente.

La seguente tabella elenca i nomi delle azioni che puoi utilizzare quando segnali le azioni utente critiche.

Nome azione Evento avviato dall'utente o azione utente
LOGIN

Accedi al sito web.
REGISTRATION Registrazione sul sito web.
SECURITY_QUESTION_CHANGE Richiesta di modifica della domanda di sicurezza.
PASSWORD_RESET Richiedi la reimpostazione della password.
PHONE_NUMBER_UPDATE Richiedi l'aggiornamento del numero di telefono.
EMAIL_UPDATE Richiesta di aggiornamento dell'indirizzo email.
ACCOUNT_UPDATE Richiesta di aggiornamento delle informazioni relative all'account, ad esempio i dati di contatto.
TRIGGER_MFA Un'azione che attiva una verifica MFA.
REDEEM_CODE Richiedi l'utilizzo del codice.
LIST_PAYMENT_METHODS Recupera l'elenco dei metodi di pagamento.

Il seguente esempio mostra come chiamare grecaptcha.enterprise.execute() in un aggiornamento del numero di telefono:

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

Valutare gli eventi utente critici

Quando chiami grecaptcha.enterprise.execute() su un'azione utente, viene generato un token. Per gli eventi utente critici, come accessi, registrazioni e azioni degli utenti autenticati riusciti e non riusciti, crea una valutazione per valutare i risultati della chiamata grecaptcha.enterprise.execute(). La valutazione fornisce un giudizio sul rischio, che puoi utilizzare per decidere come gestire attività potenzialmente fraudolente. Alcune delle azioni che puoi intraprendere sono il blocco di richieste sospette, la verifica di accessi rischiosi e l'indagine sugli account di interesse.

reCAPTCHA Account Defense richiede di fornire un identificatore di account stabile per eseguire la valutazione e attribuire l'attività utente, ad esempio richieste di accesso, richieste di accesso e richieste di registrazione, a un account specifico. In questo modo, reCAPTCHA Account Defense elabora i pattern di attività utente per creare un modello di attività per ogni account, in modo da rilevare meglio il traffico anomalo e illecito.

Scegli un identificatore di account stabile accountId che non venga modificato spesso dall'utente e forniscilo alla valutazione nel metodo projects.assessments.create. Questo identificatore di account stabile deve avere lo stesso valore per tutti gli eventi correlati allo stesso utente. Puoi fornire i seguenti elementi come identificatore dell'account:

Identificatori utente

Se ogni account può essere associato in modo univoco a un nome utente, un indirizzo email o un numero di telefono stabile, puoi utilizzarlo come accountId. Quando fornisci questi identificatori cross-site (identificatori che possono essere riutilizzati su più siti), reCAPTCHA utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli cross-site contrassegnando gli identificatori di account illeciti e utilizzando la conoscenza dei pattern di abuso cross-site correlati a questi identificatori.

In alternativa, se hai un ID utente interno associato in modo univoco a ogni account, puoi fornirlo come accountId.

Sottoposto ad hashing o criptato

Se non disponi di un ID utente interno associato in modo univoco a ogni account, puoi trasformare qualsiasi identificatore stabile in un identificatore di account opaco specifico per il sito. Questo identificatore è ancora necessario a reCAPTCHA Account Defender per comprendere i pattern di attività utente e rilevare comportamenti anomali, ma non viene condiviso con altri siti.

Scegli un identificatore di account stabile e rendilo opaco prima di inviarlo a reCAPTCHA utilizzando la crittografia o l'hashing:

  • crittografia (consigliata): cripta l'identificatore dell'account utilizzando un metodo di crittografia deterministico che produce un testo cifrato stabile. Per istruzioni dettagliate, consulta Criptare i dati in modo deterministico. Quando scegli la crittografia simmetrica anziché l'hashing, non devi mantenere una mappatura tra i tuoi identificatori utente e gli identificatori utente opachi corrispondenti. Decripta gli identificatori opachi restituiti da reCAPTCHA per trasformarli nell'identificatore utente.

  • hashing: ti consigliamo di eseguire l'hashing dell'identificatore dell'account utilizzando il metodo SHA256-HMAC con un sale personalizzato a tua scelta. Poiché gli hash sono unidirezionali, devi mantenere una mappatura tra gli hash generati e gli identificatori utente in modo da poter mappare l'identificatore dell'account sottoposto ad hashing che vengono restituiti agli account originali.

Oltre a fornire un identificatore di account stabile per tutte le richieste correlate all'account, puoi fornire identificatori di account aggiuntivi, potenzialmente non stabili, per alcune richieste specifiche. Gli identificatori dell'account specifici per il contesto forniti in aggiunta alla guida accountId reCAPTCHA Account defense analizza meglio l'attività utente e rileva i tentativi di takeover dell'account per proteggere gli account utente. Quando fornisci identificatori aggiuntivi, reCAPTCHA utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli cross-site contrassegnando gli identificatori di account abusivi e utilizzando la conoscenza di pattern di abuso cross-site correlati a questi identificatori. Ad esempio, puoi fornire quanto segue:

  • Il nome utente, l'indirizzo email o il numero di telefono utilizzato come handle di accesso per le richieste di accesso

  • L'indirizzo email o il numero di telefono verificato per una richiesta di autenticazione a più fattori

  • Un indirizzo email o un numero di telefono (principale o secondario) fornito dall'utente durante una richiesta di aggiornamento dell'account

  • Gli indirizzi email e i numeri di telefono forniti dall'utente durante una richiesta di registrazione

Aggiungi l'identificatore di account stabile scelto al parametro accountId nel metodo projects.assessments.create per tutte le richieste relative all'account. (Facoltativo) Fornisci identificatori di account aggiuntivi per le richieste pertinenti utilizzando il campo userIds nella valutazione.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • TOKEN: token restituito dalla chiamata grecaptcha.enterprise.execute()
  • KEY_ID: chiave reCAPTCHA associata al sito
  • ACCOUNT_ID: l'identificatore associato in modo univoco all'account utente per un account utente al tuo sito web
  • EMAIL_ADDRESS: (Facoltativo) Un indirizzo email associato a questa richiesta, se presente
  • PHONE_NUMBER: (Facoltativo) Un numero di telefono associato a questa richiesta, se presente
  • USERNAME: (Facoltativo) Un nome utente associato a questa richiesta, se presente

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Esempio di codice

Java

Per eseguire l'autenticazione in reCAPTCHA, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


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

Interpretare il verdetto sul rischio degli eventi utente critici

Quando crei una valutazione con Account Defender abilitato, Account Defender restituisce accountDefenderAssessment come parte della risposta di valutazione. Il valore di accountDefenderAssessment ti aiuta a valutare se l'attività utente è legittima o fraudolenta. Restituisce anche un ID valutazione che devi utilizzare per annotare gli eventi utente.

Il seguente esempio è una risposta JSON di esempio:

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

Il campo accountDefenderAssessment può contenere uno qualsiasi dei seguenti valori:

Valore Descrizione
SUSPICIOUS_LOGIN_ACTIVITY Indica che la richiesta rappresenta un rischio elevato di credential stuffing o takeover dell'account.
SUSPICIOUS_ACCOUNT_CREATION Indica che la richiesta rappresenta un rischio elevato di creazione di account illeciti.
PROFILE_MATCH

Indica che gli attributi dell'utente corrispondono a quelli rilevati in precedenza per questo utente specifico. Questo valore indica che l'utente utilizza un dispositivo attendibile già usato in precedenza per accedere al tuo sito web.

PROFILE_MATCH viene restituito solo nei seguenti scenari:

  • Utilizzi l'autenticazione a più fattori (MFA) o a due fattori (2FA) e reCAPTCHA Account Defense contrassegna i profili utente come attendibili dopo che gli utenti superano la verifica MFA o 2FA.
  • Annoti le valutazioni come LEGITIMATE o PASSED_TWO_FACTOR e reCAPTCHA Account Defense contrassegna il profilo utente corrispondente come attendibile.
RELATED_ACCOUNTS_NUMBER_HIGH Indica che la richiesta ha un numero elevato di account correlati. Non implica necessariamente che l'account sia dannoso, ma potrebbe richiedere ulteriori accertamenti.

Annotare gli eventi per ottimizzare il modello specifico per il sito

Per fornire maggiori informazioni a reCAPTCHA Account Defense e migliorare il modello di rilevamento specifico per il sito, devi annotare gli eventi che hai valutato creando valutazioni.

Per annotare una valutazione, invia una richiesta al metodo projects.assessments.annotate con l'ID valutazione. Nel corpo della richiesta, includi etichette che forniscono informazioni aggiuntive su un evento descritto nella valutazione.

Per annotare un test:

  1. Determina le informazioni e le etichette da aggiungere nel corpo JSON della richiesta a seconda del caso d'uso.

    La tabella seguente elenca le etichette e i valori che puoi utilizzare per annotare gli eventi:

    Etichetta Descrizione Esempio di richiesta
    reasons Obbligatorio. Un'etichetta per supportare le tue valutazioni.

    Fornisci i dettagli degli eventi in tempo reale nell'etichetta reasons in pochi secondi o minuti dopo l'evento perché influiscono sul rilevamento in tempo reale.

    Per l'elenco dei valori possibili, vedi Valori dei motivi.

    Esempio: per rilevare le compromissioni dell'account, annota se la password inserita era corretta con i valori CORRECT_PASSWORD o INCORRECT_PASSWORD. Se hai implementato la tua autenticazione a più fattori, puoi aggiungere i seguenti valori: INITIATED_TWO_FACTOR e PASSED_TWO_FACTOR o FAILED_TWO_FACTOR. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Facoltativo. Un'etichetta per indicare la legittimità delle valutazioni.

    Fornisci informazioni sugli eventi di accesso e registrazione per convalidare o correggere le tue valutazioni del rischio nell'etichetta annotation.

    Valori possibili: LEGITIMATE o FRAUDULENT.

    Puoi inviare queste informazioni in qualsiasi momento o nell'ambito di un job batch. Tuttavia, ti consigliamo di inviare queste informazioni pochi secondi o minuti dopo l'evento, perché influiscono sul rilevamento in tempo reale.

    		 
          {
       "annotation": "LEGITIMATE"
      }
    accountId

    Facoltativo. Un'etichetta per associare un ID account a un evento.

    Se hai creato una valutazione senza un ID account, utilizza questa etichetta per fornire l'ID account di un evento ogni volta che è disponibile.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. Crea una richiesta di annotazione con le etichette appropriate.

    Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

    • ASSESSMENT_ID: valore del campo name restituito dalla chiamata projects.assessments.create.
    • ANNOTATION: (Facoltativo) Un'etichetta per indicare se la valutazione è legittima o fraudolenta.
    • REASONS: (Facoltativo) Motivi a sostegno dell'annotazione. Per l'elenco dei valori possibili, vedi valori dei motivi.
    • ACCOUNT_ID: (facoltativo) l'identificatore associato in modo univoco all'account utente sul tuo sito web.

    Per saperne di più, consulta Etichette per le annotazioni.

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

    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

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

    $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

    Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.

Esempio di codice

Java

Per eseguire l'autenticazione in reCAPTCHA, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


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

Utilizzare e interpretare il punteggio di rischio di takeover dell'account

La funzionalità di punteggio di rischio di compromissione dell'account (ATO) aggiunge un punteggio di rischio numerico e spiegazioni leggibili alla valutazione della protezione dell'account. Questi approfondimenti ti aiutano a comprendere la valutazione e a prendere decisioni o intraprendere azioni successive.

Ottenere il punteggio di rischio

Per ricevere il punteggio di rischio e i motivi di spiegabilità, invia una CreateAssessment richiesta e includi event.userInfo.accountId nella richiesta.

Leggi il punteggio di rischio e i dettagli

Il punteggio di rischio e i motivi di spiegabilità si trovano nell'oggetto accountDefenderAssessment.accountTakeoverVerdict nella risposta alla valutazione.

  • Punteggio di rischio: accountDefenderAssessment.accountTakeoverVerdict.risk
  • Motivi del rischio: accountDefenderAssessment.accountTakeoverVerdict.riskReasons
  • Motivi di attendibilità: accountDefenderAssessment.accountTakeoverVerdict.trustReasons

Il seguente snippet mostra un esempio dei campi in una risposta al test:

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

Interpretare il punteggio di rischio ATO

Quando utilizzi il punteggio di rischio, stabilisci una soglia per determinare quando intraprendere azioni protettive.

Utilizza il punteggio di rischio ATO come alternativa all'etichetta SUSPICIOUS_LOGIN_ACTIVITY. Non utilizzare sia il punteggio di rischio che l'etichetta per attivare l'applicazione della norma nella stessa valutazione. Puoi configurare la logica di applicazione in base al superamento della soglia del punteggio di rischio o alla presenza dell'etichetta. In genere, il punteggio di rischio offre una valutazione più granulare.

Ti consigliamo di valutare il rendimento del punteggio di rischio con una soglia appropriata sul traffico della tua piattaforma prima di utilizzarlo per l'applicazione.

Per agire in base al punteggio di rischio, implementa un controllo nel backend come mostrato nel seguente snippet:

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

Soglie standard del punteggio di rischio

La tabella seguente fornisce le soglie standard del punteggio di rischio e i relativi tassi di falsi positivi (FPR) previsti. Scegli una soglia in base al tasso di falsi positivi accettabile. Il rendimento può variare, quindi potrebbe essere necessario regolare la soglia in base al rendimento osservato.

Tasso di falsi positivi previsto Soglia del punteggio di rischio
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

Modificare la soglia

Se il tasso di falsi positivi osservato è troppo alto, aumenta la soglia. Se il richiamo osservato è troppo basso e puoi tollerare un FPR più alto, diminuisci la soglia.

Calcolare i valori intermedi

Per stimare il tasso di falsi positivi per una soglia compresa tra i valori standard, utilizza l'interpolazione lineare. Il seguente esempio mostra come calcolare il tasso di falsi positivi per una soglia di 0,85:

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

Per trovare una soglia per un FPR specifico, esegui l'interpolazione tra i valori standard. Il seguente esempio mostra come trovare la soglia per un FPR del 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

Si stima che una soglia di 0,475 produca un FPR del 5%.

Interpretare i motivi della spiegabilità

I motivi di spiegabilità forniscono informazioni sui fattori che influenzano il punteggio di rischio. Utilizza questi motivi per perfezionare il processo decisionale.

  • Motivi di rischio: indicano i fattori associati a un rischio più elevato di takeover dell'account.
  • Motivi di affidabilità: indicano i fattori che suggeriscono la legittimità.

Per un determinato punteggio di rischio possono essere visualizzati sia i motivi di rischio che quelli di affidabilità.

Motivo Tipo Interpretazione
PROFILE_MATCH Attendibile La richiesta corrisponde a un profilo attendibile associato a questo account. Equivale all'etichetta AccountDefenderLabel.PROFILE_MATCH.
ACCOUNT_HISTORY_REPUTABLE Attendibile L'attività storica dell'account è affidabile. È improbabile che l'account sia stato compromesso in passato.
CLIENT_HISTORICAL_BOT_ACTIVITY Rischio In passato è stato osservato che il client inviava traffico simile a quello dei bot a questo sito. Questo motivo incorpora la reputazione storica e indica che il client è noto per l'utilizzo di bot, anche se la richiesta attuale è effettuata da un utente.
ACCOUNT_IN_LARGE_RELATED_GROUP Rischio L'account fa parte di un ampio gruppo di account correlati, il che indica che potrebbe far parte di una rete fraudolenta. Gli account correlati vengono identificati in base a pattern di traffico e caratteristiche delle richieste simili.
CLIENT_ACCESSED_MANY_ACCOUNTS Rischio È stato osservato che il client accede a molti account su questo sito.

Passaggi successivi