Configurare reCAPTCHA Express sui server delle applicazioni

Questo documento mostra come configurare reCAPTCHA Express su un server applicazioni in un ambiente in cui l'integrazione Non è possibile implementare JavaScript o SDK mobile, ad esempio per proteggere gli 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, quindi seleziona Chiave API.

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

Crea una chiave reCAPTCHA express

Per implementare reCAPTCHA Express, crea un reCAPTCHA tasto 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 la 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: 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": {
}
}

Registra la chiave express per utilizzarla in seguito.

Crea una valutazione

Per effettuare una richiesta a reCAPTCHA dal tuo server delle applicazioni, creare una valutazione utilizzando projects.assessments.create .

Prima di utilizzare i dati della richiesta, effettua 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 dal dispositivo dell'utente relativa a questo evento.
  • HEADER_INFO: facoltativo. Le intestazioni HTTP che il client ha inviato alla tua applicazione server web. 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 l'utente accede.
  • USER_AGENT: facoltativo. Lo user agent presente nella richiesta del dispositivo dell'utente relativa a questo evento.
  • ACCOUNT_ID: facoltativo. Un identificatore univoco e permanente dell'account dell'utente, ad esempio il nome di un account con hash.

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

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 dell'utente presenta un rischio maggiore e potrebbe essere fraudolenta, e 0.7 indica che l'interazione dell'utente comporta un basso rischio ed è probabile legittimi.

In assenza di indicatori, reCAPTCHA Express restituisce 0.7 per impostazione predefinita.

Passaggi successivi