Configurare reCAPTCHA Express sui server delle applicazioni

Questo documento mostra come configurare reCAPTCHA Express su un server di applicazioni in un ambiente in cui non è possibile integrare l'SDK mobile o JavaScript di reCAPTCHA, ad esempio per la protezione degli endpoint API.

reCAPTCHA Express è una funzionalità che ti consente di creare valutazioni senza le funzionalità lato client. reCAPTCHA Express utilizza solo indicatori di backend per generare un punteggio di rischio reCAPTCHA. Puoi utilizzare questo punteggio di rischio per decidere se soddisfare la richiesta, reindirizzare a una pagina di verifica o registrarla per un'analisi successiva.

Prima di iniziare

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    Registra l'ID progetto Google Cloud per utilizzarlo in un secondo momento.

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Enable the API

  4. Crea una chiave API per l'autenticazione:

    1. Nella console Google Cloud, vai alla pagina Credenziali.

      Vai a credenziali

    2. Fai clic su Crea credenziali e poi seleziona Chiave API.

    3. Prendi nota della chiave API per utilizzarla in un secondo momento.

Creare una chiave reCAPTCHA Express

Per implementare reCAPTCHA Express, crea una chiave reCAPTCHA Express.

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. gcloud

    Per creare le chiavi reCAPTCHA, utilizza il comando gcloud recaptcha keys create.

    Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

    • DISPLAY_NAME: il nome della chiave. In genere, il nome di un sito.

    Esegui il comando gcloud recaptcha keys create:

    Linux, macOS o Cloud Shell

    gcloud recaptcha keys create \
--express \
--display-name=DISPLAY_NAME

    Windows (PowerShell)

    gcloud recaptcha keys create `
--express `
--display-name=DISPLAY_NAME

    Windows (cmd.exe)

    gcloud recaptcha keys create ^
--express ^
--display-name=DISPLAY_NAME

    La risposta contiene la chiave reCAPTCHA appena creata.

    REST

    Per informazioni di riferimento dell'API sui tipi di token e sui tipi di integrazione, consulta Token e Tipo di integrazione.

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

    • DISPLAY_NAME: il nome della chiave. In genere, il nome di un sito.

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

    Per inviare la richiesta, scegli una delle seguenti 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/keys"

    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/keys" | Select-Object -Expand Content

    Dovresti ricevere una risposta JSON simile alla seguente:

    
{
  "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,
"expressSettings": {
}
}

Prendi nota della chiave Express per utilizzarla in un secondo momento.

Creare una valutazione

Per inviare una richiesta dal server dell'applicazione a reCAPTCHA, crea una valutazione utilizzando il metodo projects.assessments.create.

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

  • API_KEY: la chiave API che hai creato per l'autenticazione.
  • EXPRESS_KEY: la chiave reCAPTCHA Express che hai creato per la tua applicazione.
  • USER_IP_ADDRESS: l'indirizzo IP nella richiesta del dispositivo dell'utente relativa a questo evento.
  • HEADER_INFO: facoltativo. Le intestazioni HTTP inviate dal client al tuo server di applicazioni. Si tratta di un array di stringhe che contiene le intestazioni delle richieste nel formato `[key:value]`. Ad esempio, `[key:value, key:value,...]`. Ti consigliamo di condividere il maggior numero possibile di intestazioni nell'ordine richiesto. Assicurati che l'ordine delle intestazioni sia coerente in tutte le richieste della stessa sessione.
  • JA3_FINGERPRINT: facoltativo. JA3 è un'impronta MD5 di determinati campi del pacchetto ClientHello TLS. Per ulteriori informazioni, consulta JA3 - A method for profiling SSL/TLS Clients.
  • URI_NAME: facoltativo. L'URI a cui accede l'utente.
  • USER_AGENT: facoltativo. Lo user agent presente nella richiesta del dispositivo dell'utente relativa a questo evento.
  • ACCOUNT_ID: facoltativo. Un identificatore univoco e persistente per l'account dell'utente, ad esempio un nome account sottoposto ad hashing.

Metodo HTTP e URL: 

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

Corpo JSON della richiesta: 


{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

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

$headers = @{  }

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?key=API_KEY" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "firewallPolicyEvaluation": false,
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

Interpreta i punteggi

reCAPTCHA Express restituisce solo due punteggi: 0.3 e 0.7. 0.3 indica che l'interazione utente presenta un rischio maggiore ed è probabilmente fraudolenta, mentre 0.7 indica che l'interazione utente presenta un rischio basso ed è probabilmente legittima.

Se non sono presenti indicatori, reCAPTCHA Express restituisce 0.7 per impostazione predefinita.

Passaggi successivi