Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Installer des clés universelles sur des pages Web

Ce document explique comment installer et intégrer une clé universelle à vos pages Web.

Avant de commencer

Installer des clés universelles sur votre site Web

Pour installer votre clé universelle et protéger vos pages Web, choisissez la configuration AutoExecute de Google Cloud Fraud Defense ou l'installation JavaScript standard :

Configuration AutoExecute

Fraud Defense AutoExecute peut vous aider à simplifier l'intégration JavaScript de votre interface utilisateur en interceptant les requêtes réseau sur vos pages Web. Vous n'avez ainsi plus besoin d'appeler manuellement grecaptcha.enterprise.execute() pour chaque action de l'interface utilisateur.

AutoExecute n'intercepte que les requêtes réseau asynchrones initiées avec l'API Fetch ou XMLHttpRequest, y compris les requêtes provenant de frameworks tels qu'AJAX qui utilisent ces API.
AutoExecute n'est pas compatible avec les ressources qui se chargent automatiquement au moment du chargement de la page. Appliquez plutôt AutoExecute aux requêtes réseau déclenchées par les actions de l'utilisateur sur la page, comme un bouton de connexion.
Pour éviter que les défis Fraud Defense n'entraînent des délais d'expiration du réseau, appliquez des délais d'expiration directement aux requêtes. Utilisez AbortSignal.timeout(n) pour l'API Fetch et la propriété XMLHttpRequest.timeout pour XMLHttpRequest.

Ajouter la balise de script à vos pages Web

Pour charger reCAPTCHA sur votre page Web, ajoutez l'API JavaScript avec votre clé universelle dans l'élément <head></head> de votre page Web :

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Fraud Defense utilise la langue du navigateur par défaut. Si vous souhaitez spécifier une autre langue, utilisez l'attribut hl=LANG dans votre script. Par exemple, pour utiliser le français, spécifiez les informations suivantes :

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Pour en savoir plus sur les langues acceptées, consultez les codes de langue pour Fraud Defense.

Configurer des points de terminaison protégés

Le script Fraud Defense s'intègre automatiquement aux actions réseau définies dans la configuration des règles de votre clé universelle. Cette section définit un mappage des chemins d'URL (path) aux noms d'action (action).

Si le script Fraud Defense détecte une requête réseau asynchrone vers un chemin mappé, il intercepte la requête, déclenche une évaluation des risques et peut afficher un test CAPTCHA à l'utilisateur avant que la requête d'origine ne se poursuive. Le jeton de réponse généré est automatiquement associé à l'en-tête X-Recaptcha-Token de la requête.

gcloud

Pour inspecter la configuration actuelle des règles pour votre clé universelle, utilisez la commande gcloud alpha recaptcha policies describe :

gcloud alpha recaptcha policies describe --key=KEY_ID

Pour mettre à jour la configuration de la règle avec vos points de terminaison protégés, créez un fichier YAML (par exemple, POLICY.yaml) définissant vos chemins et actions protégés :

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Mettez à jour la configuration de votre clé avec le fichier YAML à l'aide de la commande gcloud alpha recaptcha policies update :

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

API REST

Pour mettre à jour la configuration de la règle afin de définir des points de terminaison protégés à l'aide de l'API REST, utilisez la méthode projects.keys.updatePolicy.

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

PROJECT_ID : ID de votre projet Google Cloud
KEY_ID : ID de votre clé universelle

Méthode HTTP et URL :

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

Corps JSON de la requête :

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

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

curl -X PATCH \
     -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/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

Si la requête aboutit, elle renvoie la configuration de la règle mise à jour.

Le paramètre path accepte les modèles glob avec les règles suivantes :

Il doit commencer par / et ne peut pas être vide.
Il ne peut pas s'agir d'un /* ou d'un /** autonome, car cela peut avoir un impact négatif sur les performances en déclenchant Fraud Defense pour chaque requête envoyée à votre backend.
Les caractères génériques * (correspondant à un seul segment de chemin) et ** (correspondant à plusieurs segments de chemin) doivent occuper l'intégralité d'un segment de chemin (par exemple, /api/*/login ou /api/* sont valides, mais /api/login* ne l'est pas).
Le caractère générique ** ne doit occuper que le dernier segment de chemin (par exemple, /api/** est valide, mais /api/**/login ne l'est pas).

Requêtes tierces : si des outils tiers exécutés sur votre page (tels que des scripts d'analyse ou de partenaires) envoient des requêtes vers des chemins correspondant à vos points de terminaison protégés (par exemple, https://analytics.example.net/login correspondant à /login), AutoExecute les interceptera également. Cela peut entraîner une latence réseau supplémentaire, des métriques faussées ou des tests CAPTCHA inattendus. Pour éviter les conflits, assurez-vous que vos chemins protégés sont distincts (par exemple, /auth/v1/login) ou utilisez l'installation standard en cas de collision de chemins.
API multidomaines : si votre API de backend est hébergée sur un domaine différent de celui de votre site Web (par exemple, examplecdn.net au lieu de www.example.com), AutoExecute fonctionne automatiquement sans configuration de domaine supplémentaire.

Si la correspondance avec des domaines de destination spécifiques est importante pour votre intégration, envoyez une demande de fonctionnalité.

Dans votre backend, récupérez le jeton de réponse à partir de l'en-tête de requête X-Recaptcha-Token et créez une évaluation dans les deux minutes.

Installation standard

Nous vous recommandons d'ajouter la validation Fraud Defense sur une interaction utilisateur qui doit être validée. Par exemple, si vous souhaitez valider l'action d'envoi d'un formulaire, vous devez ajouter la validation Fraud Defense à l'action d'envoi.

En fonction de l'emplacement où vous souhaitez ajouter la validation Fraud Defense, choisissez l'option appropriée :

Ajouter une validation sur une interaction utilisateur
Ajouter Fraud Defense à un bouton HTML

Ajouter une validation à une interaction utilisateur

Pour charger reCAPTCHA sur votre page Web, ajoutez l'API JavaScript avec votre clé universelle dans l'élément <head></head> de votre page Web :
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense utilise la langue du navigateur par défaut. Si vous souhaitez spécifier une autre langue, utilisez l'attribut hl=LANG dans votre script. Par exemple, pour utiliser le français, spécifiez les informations suivantes :

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Pour en savoir plus sur les langues acceptées, consultez les codes de langue pour Fraud Defense.

Si vous souhaitez spécifier un emplacement pour le badge, utilisez badge=LOCATION comme paramètre de requête dans la balise de script. Exemple : https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Par défaut, l'emplacement est défini sur bottomright. inline et bottomleft sont d'autres valeurs possibles.
Pour ajouter la validation Fraud Defense à une interaction utilisateur, procédez comme suit :
1. Pour vous assurer que grecaptcha.enterprise.execute() s'exécute après le chargement de la bibliothèque Fraud Defense, utilisez grecaptcha.enterprise.ready().
2. Appelez grecaptcha.enterprise.execute() pour chaque interaction que vous souhaitez protéger avec votre clé universelle. Indiquez un nom explicite pour une interaction de l'utilisateur dans le paramètre action. Pour obtenir plus de conseils, consultez Actions.
  
  Conseil : Ajoutez l'appel execute aux actions sensibles telles que LOGIN, SIGNUP, PASSWORD_RESET ou PURCHASE.
  
  L'exemple suivant montre comment appeler grecaptcha.enterprise.execute() sur une action de connexion :
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>
```
  s
Une fois le jeton généré, envoyez le jeton reCAPTCHA à votre backend et créez une évaluation dans les deux minutes.

Important : Votre backend doit spécifier assessment.event.expected_action (ou expectedAction en JSON) dans CreateAssessmentRequest, et cette valeur doit correspondre à l'action configurée dans l'appel execute(). Par exemple, si vous configurez l'action de l'interface sur LOGIN, votre backend doit définir expected_action sur LOGIN lors de la création d'une évaluation pour cette requête. En cas d'incohérence, cela signifie qu'un pirate informatique tente de falsifier des actions.

Ajouter Fraud Defense sur un bouton HTML

Pour charger reCAPTCHA sur votre page Web, ajoutez l'API JavaScript avec votre clé universelle dans l'élément <head></head> de votre page Web :
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense utilise la langue du navigateur par défaut. Si vous souhaitez spécifier une autre langue, utilisez l'attribut hl=LANG dans votre script. Par exemple, pour utiliser le français, spécifiez les informations suivantes :

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Pour en savoir plus sur les langues acceptées, consultez les codes de langue pour Fraud Defense.
Pour ajouter Fraud Defense à un bouton HTML :
1. Définissez une fonction de rappel pour gérer le jeton.
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
Pour en savoir plus, consultez la section sur la méthode requestSubmit().
1. Ajoutez des attributs à votre bouton HTML.
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
Si vous souhaitez spécifier un emplacement pour le badge, utilisez l'attribut data-badge="LOCATION" sur l'élément qui comporte class="g-recaptcha". Par défaut, l'emplacement est défini sur bottomright. inline et bottomleft sont d'autres valeurs possibles.
1. Lorsque ce bouton est utilisé pour envoyer un formulaire sur votre site, le jeton de réponse est inclus dans le paramètre POST g-recaptcha-response.
Remarque : Si vous définissez le bouton g-recaptcha sur disabled, il est activé au chargement de Fraud Defense.
Une fois le jeton généré, envoyez le jeton reCAPTCHA à votre backend et créez une évaluation dans les deux minutes.

Important : Votre backend doit spécifier assessment.event.expected_action (ou expectedAction en JSON) dans CreateAssessmentRequest. Cette valeur doit correspondre à l'action configurée sur le bouton. Par exemple, si vous configurez l'action du bouton sur submit, votre backend doit définir expected_action sur submit lors de la création d'une évaluation pour cette requête. En cas d'incohérence, cela signifie qu'un pirate informatique tente de falsifier des actions.

Étapes suivantes

Pour déclencher des tests CAPTCHA en fonction de règles personnalisées, configurez des règles de questions d'authentification.
Pour évaluer le jeton de réponse reCAPTCHA, créez une évaluation.