Configurer reCAPTCHA Express sur les serveurs d'applications

Vous pouvez configurer reCAPTCHA Express sur un serveur d'application lorsqu'une intégration côté client avec le SDK reCAPTCHA JavaScript ou mobile n'est pas possible. Par exemple, la protection des points de terminaison d'API.

reCAPTCHA Express est une fonctionnalité qui vous permet de créer des évaluations sans intégration ni signaux côté client. reCAPTCHA Express utilise uniquement des signaux de backend pour générer un score de risque reCAPTCHA. Vous pouvez utiliser ce score de risque pour décider de traiter la requête, de rediriger l'utilisateur vers une page de validation 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": {
}
}

Notez 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 provenant de l'appareil de l'utilisateur associée à cet événement.
  • HEADER_INFO : facultatif. En-têtes HTTP que le client a envoyés au serveur de votre application. Il s'agit d'un tableau de chaînes contenant les en-têtes de requête au format `[key:value]`. Par exemple, `[key:value, key:value,...]`. 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 pour toutes les requêtes d'une même session.
  • JA3_FINGERPRINT : facultatif. JA3 est une empreinte MD5 de certains champs du paquet TLS ClientHello. 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é à 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/",
    "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.

Si les signaux sont insuffisants, reCAPTCHA Express renvoie 0.7 par défaut.

Étapes suivantes