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.

    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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    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

  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: 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 chiavi e di integrazione, vedi Chiave e Tipo di integrazione.

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

    • INTEGRATION_TYPE: 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 è 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, ed esegui questo comando: 

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

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

    $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