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

Questo documento mostra come utilizzare l'account defender di reCAPTCHA Enterprise per rilevare e prevenire attività fraudolente relative all'account sui siti web.

reCAPTCHA Enterprise 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 uno specifico utente su un sito web in un determinato periodo di tempo. L'account defender di reCAPTCHA Enterprise aiuta a identificare questo tipo di abuso sottile creando un modello specifico per il tuo sito web in grado di rilevare una tendenza di comportamento sospetto o un cambiamento dell'attività. Utilizzando il modello specifico per il sito, reCAPTCHA Enterprise 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 dell'account defender di reCAPTCHA Enterprise e al modello specifico del sito, puoi intraprendere le seguenti azioni:

  • Limitare o disabilitare gli account fraudolenti.
  • Impedisci i tentativi di furto dell'account.
  • Mitigare le violazioni riuscite dell'account.
  • Concedi l'accesso solo alle richieste provenienti da account utente legittimi.
  • Semplifica l'accesso degli utenti da uno dei loro dispositivi attendibili.

Prima di iniziare

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

Configura le tue pagine web per l'account defender reCAPTCHA Enterprise

L'account defender di reCAPTCHA Enterprise richiede una comprensione completa delle attività dell'account per consentire un rilevamento efficace. Per iniziare a inviare le attività relative all'account al defender account reCAPTCHA Enterprise, nonché per creare e migliorare il modello specifico per il tuo sito, procedi come segue:

  1. Abilita la raccolta di dati di telemetria orizzontali.
  2. Generare report sulle azioni critiche degli utenti.
  3. Valutare gli eventi utente critici.
  4. Annota gli eventi utente per ottimizzare il modello specifico del sito.

Attiva la raccolta di dati di telemetria orizzontali

L'account defender di reCAPTCHA Enterprise richiede una visione completa delle azioni degli utenti, ad esempio se l'utente ha eseguito l'accesso o se esegue l'accesso. Per attivare la raccolta passiva di dati di telemetria orizzontali da parte di reCAPTCHA Enterprise, carica lo script JavaScript di reCAPTCHA Enterprise con la chiave di sito basata sul punteggio che hai creato in background di tutte le pagine web che fanno parte del flusso di lavoro dell'utente.

L'esempio seguente mostra come caricare lo script JavaScript di reCAPTCHA Enterprise in una pagina web.

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

Report sulle azioni critiche degli utenti

Per rilevare pattern di attività sospette e comprendere meglio i pattern di attività tipici sul tuo sito, un difensore dell'account reCAPTCHA Enterprise ha bisogno di informazioni sulle azioni critiche degli utenti. Pertanto, segnala le azioni utente critiche sulle pagine web chiamando grecaptcha.enterprise.execute() su queste azioni critiche dell'utente.

Ti consigliamo di segnalare tutte le azioni critiche degli utenti, poiché sono utili per raccogliere ulteriori indicatori. Per ogni azione utente che vuoi segnalare sostituisci il valore del parametro action di grecaptcha.enterprise.execute() con un nome che descriva l'azione utente.

Nella tabella seguente sono elencati i nomi delle azioni che puoi utilizzare quando segnali le azioni critiche degli utenti.

Nome azione Evento o azione dell'utente avviato dall'utente
LOGIN

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

L'esempio seguente mostra come chiamare grecaptcha.enterprise.execute() durante 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() per un'azione utente, viene generato un token. Per gli eventi critici degli utenti, come gli accessi riusciti e non riusciti, le registrazioni e le azioni degli utenti che hanno eseguito l'accesso, crea una valutazione per valutare i risultati della chiamata grecaptcha.enterprise.execute(). La valutazione fornisce un esito di rischio, che puoi utilizzare per prendere una decisione su come gestire attività potenzialmente fraudolente. Alcune delle azioni che puoi intraprendere sono bloccare le richieste sospette, richiedere accessi rischiosi e analizzare account che ti interessano.

L'account defender di reCAPTCHA Enterprise richiede di fornire un identificatore di account stabile per attribuire l'attività utente, come richieste di accesso, richieste di accesso e richieste di registrazione, a un account specifico. Questo aiuta il defender dell'account reCAPTCHA Enterprise a comprendere i pattern di attività utente e a creare un modello di attività per ogni account al fine di rilevare meglio il traffico anomalo e illecito.

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

Identificatori degli utenti

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 tra siti (identificatori che possono essere riutilizzati su più siti), reCAPTCHA Enterprise utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli tra siti, segnalando identificatori di account illeciti e sfruttando la conoscenza dei pattern di comportamento illecito tra siti relativi a questi identificatori.

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

Con hash 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 dell'account opaco specifico per il sito. Questo identificatore è ancora necessario per consentire al defender dell'account reCAPTCHA Enterprise di comprendere i pattern di attività utente e rilevare comportamenti anomali, ma non viene condiviso tra altri siti.

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

  • crittografia (consigliata): cripta l'identificatore dell'account utilizzando un metodo di crittografia deterministico che produca un testo crittografato stabile. Per istruzioni dettagliate, consulta Criptare i dati in modo deterministico. Quando scegli la crittografia simmetrica anziché l'hashing, non è necessario mantenere una mappatura tra gli identificatori utente e gli identificatori utente opachi corrispondenti. Decripta gli identificatori opachi restituiti da reCAPTCHA Enterprise per trasformarli in identificatori 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 solo unidirezionale, devi mantenere una mappatura tra gli hash generati e gli identificatori utente in modo da poter mappare gli identificatori dell'account sottoposti ad hashing che vengono restituiti agli account originali.

Oltre a fornire un identificatore di account stabile per tutte le richieste relative all'account, puoi fornire identificatori di account aggiuntivi, potenzialmente non stabili, per alcune richieste specifiche. Gli identificatori dell'account specifici del contesto forniti in aggiunta all'accountId aiutano il defender dell'account reCAPTCHA Enterprise a comprendere meglio l'attività utente e a rilevare i tentativi di acquisizione di account utente per proteggere gli account utente. Quando fornisci identificatori aggiuntivi, reCAPTCHA Enterprise utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli tra siti, segnalando identificatori di account illeciti e sfruttando la conoscenza dei pattern di comportamento illecito tra siti relativi 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 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 dell'account stabile scelto al parametro accountId nel metodo projects.assessments.create per tutte le richieste relative all'account. Se vuoi, fornisci identificatori di account aggiuntivi per le richieste pertinenti utilizzando il campo userIds nella valutazione.

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

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • 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 di un account utente sul 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 disponibile
  • 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 delle seguenti opzioni:

arricciatura

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

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 ed esegui questo comando: 

$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 a reCAPTCHA Enterprise, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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/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/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/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/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;
  }
}

Interpreta l'esito del rischio degli eventi utente critici

Quando crei una valutazione con l'account defender abilitato, account defender restituisce accountDefenderAssessment come parte della risposta alla valutazione. Il valore di accountDefenderAssessment consente di valutare se l'attività utente è legittima o fraudolenta. Restituisce anche un ID valutazione che devi utilizzare durante l'annotazione degli eventi utente.

L'esempio seguente è 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ò avere uno qualsiasi dei seguenti valori:

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

Indica che gli attributi dell'utente corrispondono agli attributi visualizzati in precedenza per questo utente specifico. Questo valore indica che l'utente utilizza un dispositivo attendibile già utilizzato 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 il difensore dell'account reCAPTCHA Enterprise contrassegna i profili utente come attendibili dopo che gli utenti hanno superato la verifica MFA o 2FA.
  • Puoi annotare le valutazioni come LEGITIMATE o PASSED_TWO_FACTOR e il difensore dell'account reCAPTCHA Enterprise contrassegna il profilo utente corrispondente come attendibile.
RELATED_ACCOUNTS_NUMBER_HIGH Indica che la richiesta ha un numero elevato di account correlati. Ciò non implica necessariamente che l'account sia errato, ma potrebbe richiedere ulteriori accertamenti.

Annota gli eventi per ottimizzare il modello specifico per il tuo sito

Per fornire ulteriori informazioni all'account defender di reCAPTCHA Enterprise e migliorare il modello di rilevamento specifico del sito, devi annotare gli eventi valutati creando delle valutazioni.

Puoi annotare una valutazione inviando una richiesta al metodo projects.assessments.annotate con l'ID valutazione. Nel corpo della richiesta sono incluse le etichette che forniscono ulteriori informazioni su un evento descritto nella valutazione.

Per annotare una valutazione:

  1. Determina le informazioni e le etichette da aggiungere nel corpo JSON della richiesta in base al caso d'uso.

    Nella tabella seguente sono elencati le etichette e i valori che puoi utilizzare per annotare gli eventi:

    Etichetta Descrizione Esempio di richiesta
    reasons obbligatorio. Un'etichetta a supporto delle valutazioni.

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

    Per l'elenco dei possibili valori, consulta i valori dei motivi.

    Esempio: per rilevare violazioni degli account, annota se la password inserita è corretta con i valori CORRECT_PASSWORD o INCORRECT_PASSWORD. Se hai eseguito il deployment della tua MFA, puoi aggiungere i valori seguenti: 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 valutazioni dei rischi nell'etichetta annotation.

    Valori possibili: LEGITIMATE o FRAUDULENT.

    Puoi inviare queste informazioni in qualsiasi momento o nell'ambito di un job batch. Tuttavia, consigliamo di inviare queste informazioni entro 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, quando è disponibile.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

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

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

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

    Per maggiori informazioni, consulta la pagina sulle 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 delle seguenti opzioni:

    arricciatura

    Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

    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 ed esegui questo comando: 

    $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 a reCAPTCHA Enterprise, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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/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);
    }
  }
}

Abilita account defender reCAPTCHA Enterprise

Dopo aver configurato le tue pagine web per l'account defender di reCAPTCHA Enterprise, puoi abilitare il difensore dell'account reCAPTCHA Enterprise.

  1. Nella console Google Cloud, vai alla pagina reCAPTCHA Enterprise.

    Vai a reCAPTCHA Enterprise

  2. Verifica che il nome del progetto venga visualizzato nel selettore di risorse nella parte superiore della pagina.

    Se non vedi il nome del progetto, fai clic sul selettore di risorse e seleziona il progetto.

  3. Fai clic su Impostazioni.

  4. Nel riquadro Account defender, fai clic su Attiva.

  5. Nella finestra di dialogo Configura account defender, fai clic su Abilita.

La propagazione dell'abilitazione per la protezione dell'account reCAPTCHA Enterprise ai nostri sistemi potrebbe richiedere alcune ore. Dopo che l'abilitazione delle funzionalità è stata propagata ai nostri sistemi, dovresti iniziare a ricevere risposte relative a difensore dell'account nell'ambito delle valutazioni.

Passaggi successivi