Configurare reCAPTCHA Express sui server delle applicazioni

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

reCAPTCHA express è una funzionalità che ti consente di creare valutazioni senza un'integrazione lato client o segnali lato client. reCAPTCHA express utilizza solo i segnali 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. Nella Google Cloud console, nella pagina di selezione del progetto, seleziona o crea un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    Vai al selettore di progetti

    Prendi nota dell'ID progetto per utilizzarlo in un secondo momento. Google Cloud

  2. Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.

  3. Abilita l'API reCAPTCHA Enterprise.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

  4. Crea una chiave API per l'autenticazione:

    1. Nella Google Cloud console, 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 una chiave reCAPTCHA express.

  1. Nella Google Cloud console, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della Google Cloud console viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già inclusa e installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  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:

    • INTEGRATION_TYPE: tipo di integrazione. Specifica score.
    • DISPLAY_NAME: 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 ai tipi di integrazione, consulta la sezione Tipo di chiave e Tipo di integrazione.

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

    • INTEGRATION_TYPE: tipo di integrazione. Specifica score.
    • DISPLAY_NAME: nome della chiave. In genere, il nome di un sito.
    • DEFAULT_SCORE_THRESHOLD: per le chiavi di verifica basate su policy, definisce la soglia di verifica universale per la chiave quando non è definita una soglia di punteggio personalizzata. Questa funzionalità è in anteprima.
    • ACTION_SCORE_THRESHOLDS: per le chiavi di verifica basate su policy, specifica l'azione e il punteggio di soglia corrispondente compreso tra 0,0 e 1,0. Ad esempio, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Questa funzionalità è in anteprima.

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

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

Creare un test

Per inviare una richiesta dal server delle applicazioni a reCAPTCHA, crea un test utilizzando il metodo projects.assessments.create.

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

  • 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. 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 nella stessa sessione.
  • JA3_FINGERPRINT: (facoltativo) JA3 è un'impronta digitale MD5 di determinati campi del pacchetto TLS client hello. Per saperne di più, consulta JA3 - A method for profiling SSL/TLS Clients.
  • URI_NAME: (facoltativo) L'URI a cui l'utente sta accedendo.
  • USER_AGENT: (facoltativo) Lo user agent presente nella richiesta dal dispositivo dell'utente correlato a questo evento.
  • ACCOUNT_ID: (facoltativo) Un identificatore univoco e persistente per l'account dell'utente, ad esempio un nome 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 di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, e 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, e 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 dell'utente presenta un rischio maggiore e probabilmente è fraudolenta, mentre 0.7 indica che l'interazione dell'utente presenta un rischio basso e probabilmente è legittima.

Se mancano i segnali, reCAPTCHA express restituisce 0.7 per impostazione predefinita.

Passaggi successivi