Configurer reCAPTCHA Express sur les serveurs d'applications

reCAPTCHA express peut être configuré sur un serveur d'applications lorsqu'une intégration côté client avec le SDK JavaScript ou mobile reCAPTCHA n'est pas possible, par exemple pour 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 n'utilise que des signaux de 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. Dans la Google Cloud console, sur la page de sélection du projet, sélectionnez ou créez un Google Cloud projet.

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous avez besoin du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    Accéder au sélecteur de projet

    Notez l'ID de votre Google Cloud projet, car vous en aurez besoin ultérieurement.

  2. Vérifiez que la facturation est activée pour votre Google Cloud projet.

  3. Activez l'API reCAPTCHA Enterprise.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer l'API

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

    1. Dans la Google Cloud console, 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, car vous en aurez besoin ultérieurement.

Créer une clé reCAPTCHA express

Pour implémenter reCAPTCHA express, créez une clé reCAPTCHA express.

  1. Dans la Google Cloud console, activez Cloud Shell.

    Activer Cloud Shell

    En bas de la fenêtre de la console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Google Cloud Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

  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 :

    • INTEGRATION_TYPE : type d'intégration. Spécifiez score.
    • 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 la requête, effectuez les remplacements suivants :

    • INTEGRATION_TYPE : type d'intégration. Spécifiez score.
    • DISPLAY_NAME : nom de la clé. Généralement un nom de site.
    • DEFAULT_SCORE_THRESHOLD : pour les clés de défi basées sur une règle, cette valeur définit le seuil de défi universel pour la clé lorsqu'aucun seuil de score personnalisé n'est défini. Cette fonctionnalité est disponible en version bêta.
    • ACTION_SCORE_THRESHOLDS : pour les clés de défi basées sur une règle, cette valeur spécifie l'action et le seuil de score correspondant entre 0,0 et 1,0. Par exemple, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Cette fonctionnalité est disponible en version bêta.

    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, et 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, et 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, car vous en aurez besoin ultérieurement.

Créer une évaluation

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

Avant d'utiliser les données de la requête, 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 à votre serveur d'applications. Il s'agit d'un tableau de chaînes contenant des 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 dans toutes les requêtes de la même session.
  • JA4_FINGERPRINT : facultatif. JA4 est une empreinte de certains champs du paquet TLS Client Hello. Pour en savoir plus, consultez la section JA4+™ Network Fingerprinting.
  • URI_NAME : facultatif. URI auquel l'utilisateur accède.
  • USER_AGENT : facultatif. Agent utilisateur présent dans la requête provenant 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"],
    "ja4": "JA4_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, et 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, et 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 de l'utilisateur présente un risque plus élevé et est probablement frauduleuse, tandis que 0.7 indique que l'interaction de l'utilisateur présente un faible risque et est probablement légitime.

En cas de manque de signaux, reCAPTCHA express renvoie 0.7 par défaut.

Étape suivante