Configurare reCAPTCHA Express sui server delle applicazioni

reCAPTCHA Express può essere configurato su un server delle applicazioni quando un'integrazione lato client con reCAPTCHA JavaScript o l'SDK 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 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. Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Vai al selettore di progetti

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

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

  3. Abilita l'API reCAPTCHA Enterprise.

    Ruoli richiesti per abilitare le API

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

    Abilitare l'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. 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. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud 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à installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  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:

    • INTEGRATION_TYPE: il tipo di integrazione. Specifica score.
    • 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 chiave e di integrazione, vedi Key e Integration type.

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

    • INTEGRATION_TYPE: il tipo di integrazione. Specifica score.
    • DISPLAY_NAME: il 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 viene definita una soglia di punteggio personalizzata. Questa funzionalità è in anteprima.
    • ACTION_SCORE_THRESHOLDS: per le chiavi di verifica basate su criteri, 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": {
}
}

Registra la chiave rapida per utilizzarla in un secondo momento.

Creare un test

Per effettuare 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 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. È un array di stringhe che contiene le intestazioni della richiesta 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 fingerprint MD5 di determinati campi del pacchetto TLS ClientHello. 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