Configurare reCAPTCHA Express sui server delle applicazioni

reCAPTCHA Express può essere configurato su un server delle applicazioni quando non è fattibile un'integrazione lato client con reCAPTCHA JavaScript o l'SDK mobile. Ad esempio, la protezione degli endpoint API.

reCAPTCHA Express è una funzionalità che ti consente di creare valutazioni senza un'integrazione lato client o indicatori 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 pubblicare 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' Google Cloud ID progetto per un utilizzo successivo.

  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. Registra la chiave API per utilizzarla in un secondo momento.

Crea 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 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 sull'API relative ai tipi di chiavi e di integrazione, vedi Key e Integration type.

    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 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/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 rapida per utilizzarla in un secondo momento.

Creare un test

Per inviare una richiesta dal server delle applicazioni 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 dal dispositivo dell'utente correlato a questo evento.
  • HEADER_INFO: (Facoltativo). Le intestazioni HTTP che il client ha inviato al server delle applicazioni. È 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 saperne di più, 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 dal dispositivo dell'utente relativa a questo evento.
  • ACCOUNT_ID: (Facoltativo). Un identificatore univoco e permanente 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 di queste 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/",
    "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