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
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
Verify that billing is enabled for your Google Cloud project.
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 theserviceusage.services.enablepermission. Learn how to grant roles.Créez une clé API pour l'authentification :
Dans la console Google Cloud , accédez à la page Identifiants.
Cliquez sur Créer des identifiants, puis sélectionnez Clé API.
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.
In the Google Cloud console, activate Cloud Shell.
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 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 test basées sur des règles, cette valeur définit le seuil de test universel pour la clé lorsqu'un seuil de score personnalisé n'est pas défini. Cette fonctionnalité est disponible en version bêta.
- ACTION_SCORE_THRESHOLDS : pour les clés de validation basées sur des règles, cela spécifie l'action et le seuil de score correspondant (entre 0,0 et 1,0). 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, 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 ContentVous devriez recevoir une réponse JSON de ce type :
{ "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m", "displayName": "DISPLAY_NAME, "expressSettings": { } }- INTEGRATION_TYPE : type d'intégration.
Spécifiez
- 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 pour profiler les 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 pour le compte de l'utilisateur, tel qu'un nom de compte haché.
- Découvrez comment interpréter les scores de risque.
- Découvrez comment utiliser reCAPTCHA Express au niveau du WAF.
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, effectuez les remplacements suivants :
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 ContentVous 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.