Configurer reCAPTCHA Express sur les serveurs d'applications

Ce document explique comment configurer reCAPTCHA Express sur un serveur d'application dans un environnement où l'intégration du SDK JavaScript ou mobile reCAPTCHA n'est pas possible, par exemple pour protéger les points de terminaison d'API.

reCAPTCHA Express est une fonctionnalité qui vous permet de créer des évaluations sans les fonctionnalités côté client. reCAPTCHA Express n'utilise que des signaux backend pour générer un score de risque reCAPTCHA. Vous pouvez utiliser ce score de risque pour décider de diffuser la requête, de rediriger vers une page de défi ou de la consigner pour une analyse ultérieure.

Avant de commencer

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    Notez l'ID de votre projet Google Cloud pour l'utiliser ultérieurement.

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Enable the API

  4. Créez une clé API pour l'authentification:

    1. Dans la console Google Cloud, accédez à la page Identifiants.

      Accéder à "Identifiants"

    2. Cliquez sur  Créer des identifiants, puis sélectionnez Clé API.

    3. Notez la clé API pour une utilisation ultérieure.

Créer une clé reCAPTCHA express

Pour implémenter reCAPTCHA Express, créez une clé 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

    Pour créer des clés reCAPTCHA, utilisez la commande gcloud recaptcha keys create.

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • DISPLAY_NAME: nom de la clé. Généralement un nom de site.

    Exécutez la commande gcloud recaptcha keys create:

    Linux, macOS ou 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 réponse contient la clé reCAPTCHA nouvellement créée.

    REST

    Pour obtenir des informations de référence sur les types de clés et les types d'intégration, consultez les sections Clé et Type d'intégration.

    Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

    • DISPLAY_NAME: nom de la clé. Généralement un nom de site.

    Méthode HTTP et URL :

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    Corps JSON de la requête : 

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

    Pour envoyer votre requête, choisissez l'une des options suivantes :

    curl

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    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

    Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

    $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

    Vous devriez recevoir une réponse JSON de ce type :

    
{
  "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,
"expressSettings": {
}
}

Enregistrez votre clé express pour une utilisation ultérieure.

Créer une évaluation

Pour envoyer une requête de votre serveur d'application à reCAPTCHA, créez une évaluation à l'aide de la méthode projects.assessments.create.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • API_KEY: clé API que vous avez créée pour l'authentification.
  • EXPRESS_KEY: clé reCAPTCHA express que vous avez créée pour votre application.
  • USER_IP_ADDRESS: adresse IP de la requête de l'appareil de l'utilisateur associée à cet événement.
  • HEADER_INFO : facultatif. En-têtes HTTP envoyés par le client à votre serveur d'application. Il s'agit d'un tableau de chaînes contenant des en-têtes de requête au format "[clé:valeur]". Par exemple, `[clé:valeur, clé:valeur,...]`. Nous vous recommandons de partager autant d'en-têtes que possible dans l'ordre requis. Assurez-vous que l'ordre des en-têtes est cohérent dans toutes les requêtes d'une même session.
  • JA3_FINGERPRINT : facultatif. JA3 est une empreinte MD5 de certains champs du paquet ClientHello TLS. Pour en savoir plus, consultez JA3 : une méthode de profilage des clients SSL/TLS.
  • URI_NAME : facultatif. URI auquel l'utilisateur accède.
  • USER_AGENT : facultatif. User-agent présent dans la requête de l'appareil de l'utilisateur associée à cet événement.
  • ACCOUNT_ID : facultatif. Identifiant unique et persistant du compte de l'utilisateur, tel qu'un nom de compte haché.

Méthode HTTP et URL :

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

Corps JSON de la requête : 


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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Interprétation des scores

reCAPTCHA Express ne renvoie que deux scores: 0.3 et 0.7. 0.3 indique que l'interaction utilisateur présente un risque plus élevé et est probablement frauduleuse, tandis que 0.7 indique que l'interaction utilisateur présente un risque faible et est probablement légitime.

En l'absence de signaux, reCAPTCHA Express renvoie 0.7 par défaut.

Étape suivante