Intégrer Google Cloud Armor pour les applications mobiles

Ce document explique comment intégrer les fonctionnalités WAF de reCAPTCHA Enterprise à Google Cloud Armor dans les applications mobiles.

Pour terminer l'intégration, vous devez implémenter une ou plusieurs fonctionnalités de reCAPTCHA Enterprise pour WAF et configurer des stratégies de sécurité Google Cloud Armor. Toutefois, vous ne pouvez mettre en œuvre que des jetons d'action reCAPTCHA pour l'intégration à Google Cloud Armor dans les applications mobiles.

Avant de commencer

1. Activez l'API reCAPTCHA Enterprise.

   Activer l'API

2. Identifiez les actions que vous souhaitez protéger.

Implémenter des jetons d'action reCAPTCHA

reCAPTCHA Enterprise doit être exécuté sur votre application mobile pour générer des jetons d'action. Une fois que reCAPTCHA Enterprise a généré un jeton d'action, vous l'associez à un en-tête de requête prédéfini chaque fois que vous devez protéger une action utilisateur, telle que checkout. Par défaut, les jetons d'action sont valides pendant 30 minutes, mais cette durée peut varier en fonction du trafic. Vous devez associer le jeton d'action à un en-tête de requête prédéfini avant l'expiration du jeton, afin que Google Cloud Armor puisse évaluer les attributs du jeton.

Pour implémenter un jeton d'action reCAPTCHA, procédez comme suit :

1. Créez une clé de jeton d'action pour votre application mobile.

   Console

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

      Accéder à la page reCAPTCHA Enterprise

   2. Vérifiez que le nom de votre projet s'affiche dans le sélecteur de projet en haut de la page.

      Si le nom de votre nouveau projet n'apparaît pas, cliquez sur le sélecteur de projet, puis sélectionnez votre projet.

   3. Cliquez sur Créer une clé.

      
   4. Dans le champ Nom à afficher, saisissez un nom à afficher pour la clé.
   5. Selon le type d'application pour lequel vous souhaitez créer des clés reCAPTCHA pour WAF, effectuez l'action appropriée:
   Remarque:La création de clés reCAPTCHA pour WAF dans les applications mobiles n'est possible que pour l'intégration avec Google Cloud Armor. Pour cette intégration, vous ne pouvez créer que des clés de jeton d'action pour les applications mobiles.

   Créer des clés reCAPTCHA pour WAF pour les applications iOS

   Nous vous recommandons de créer une clé reCAPTCHA par application iOS.

   1. Dans le menu Sélectionner un type de plate-forme, sélectionnez Application iOS.
      
   1. Dans la section Liste des ID de bundle iOS, cliquez sur Ajouter un ID de bundle iOS.

   2. Dans le champ ID du bundle, saisissez le nom de votre ID de bundle iOS.

   3. Facultatif: Pour ajouter un ID de bundle supplémentaire, cliquez sur Ajouter un ID de bundle iOS, puis saisissez le nom de votre ID de bundle iOS dans le champ ID du bundle.

   4. (Facultatif) Indiquez les paramètres Apple Developer.

      Nous vous recommandons de fournir ces données, car elles permettent à reCAPTCHA Enterprise de fournir des scores de risque plus précis pour votre trafic.

      Saisissez les informations suivantes :

      • Clé privée (.p8): générée dans l'Apple Developer Center sous Certificates, Identifiers & Profiles (Certificats, identifiants et profils).
      • Identifiant de clé: identifiant de clé de développeur Apple (chaîne de 10 caractères).
      • ID d'équipe: ID d'équipe Apple (chaîne de 10 caractères) propriétaire du profil de provisionnement utilisé pour créer votre application.
   5. Développez Validation de l'ID de bundle et type de clé.
      1. Pour créer une clé reCAPTCHA pour WAF, procédez comme suit :
         1. Activez l'option Pare-feu d'application Web (WAF).
         2. Dans le menu Service, sélectionnez Cloud Armor.
         3. Dans le menu Feature (Fonctionnalité), sélectionnez Action Token (Jeton d'action).
      2. Pour protéger la clé reCAPTCHA de vos ID de bundle, assurez-vous que l'option Désactiver la validation de l'ID de bundle est désactivée.

      3. Pour votre environnement hors production, si vous souhaitez spécifier un score que la clé doit renvoyer lorsque des évaluations sont créées pour celui-ci, procédez comme suit:

         1. Cliquez sur le bouton Il s'agit d'une clé de test.
         2. Dans le champ Score, spécifiez un score compris entre 0 et 1.0.
   6. Cliquez sur Créer une clé.

   La nouvelle clé est répertoriée sur la page Clés reCAPTCHA.

   Créer des clés reCAPTCHA pour WAF pour les applications Android

   1. Dans le menu Sélectionner un type de plate-forme, sélectionnez Application Android.
      
   2. Dans la section Liste de packages Android, cliquez sur Ajouter un package Android.

   3. Dans le champ Package Android, saisissez le nom de votre package Android.

      
   4. Facultatif : pour ajouter un package supplémentaire, cliquez sur Ajouter un package Android et saisissez le nom d'un autre package Android dans le champ Package Android.
   5. Développez Validation du nom de package, distribution d'applications et clés de test.
   1. Pour créer une clé reCAPTCHA pour WAF, procédez comme suit :
      1. Activez l'option Pare-feu d'application Web (WAF).
      2. Dans le menu Service, sélectionnez Cloud Armor.
      3. Dans le menu Feature (Fonctionnalité), sélectionnez Action Token (Jeton d'action).
   2. Pour forcer l'utilisation de la clé reCAPTCHA dans votre application, désactivez l'option Désactiver la validation du nom des packages.
   3. Si vous souhaitez créer une clé pour une application disponible sur d'autres plates-formes de téléchargement d'applications en plus du Google Play Store, activez l'option Prendre en charge les applications distribuées en dehors du Google Play Store.

   4. Pour votre environnement hors production, si vous souhaitez spécifier un score que la clé doit renvoyer lorsque des évaluations sont créées pour celui-ci, procédez comme suit:

      1. Cliquez sur le bouton Il s'agit d'une clé de test.
      2. Dans le champ Score, spécifiez un score compris entre 0 et 1.0.
   6. Cliquez sur Créer une clé.

   La nouvelle clé est répertoriée sur la page Clés reCAPTCHA.

   gcloud (iOS)

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

   Remarque:La création de clés reCAPTCHA pour WAF dans les applications mobiles n'est possible que pour l'intégration avec Google Cloud Armor. Pour cette intégration, vous ne pouvez créer que des clés de jeton d'action pour les applications mobiles.

   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.
   • BUNDLE_IDs : ID de bundle iOS des applications autorisées à utiliser la clé. Spécifiez plusieurs ID de bundle sous la forme d'une liste d'éléments séparés par une virgule.
   • WAF_FEATURE: nom de la fonctionnalité WAF. Spécifiez action-token.
   • WAF_SERVICE: nom du fournisseur de services WAF. Spécifiez CA pour Google Cloud Armor.

   Exécutez la commande gcloud recaptcha keys create:

   Linux, macOS ou Cloud Shell

   
   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --ios --bundle-ids=BUNDLE_IDs \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --ios --bundle-ids=BUNDLE_IDs `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --ios --bundle-ids=BUNDLE_IDs ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   

   La réponse contient la clé reCAPTCHA que vous venez de créer.

   gcloud (Android)

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

   Remarque:La création de clés reCAPTCHA pour WAF dans les applications mobiles n'est possible que pour l'intégration avec Google Cloud Armor. Pour cette intégration, vous ne pouvez créer que des clés de jeton d'action pour les applications mobiles.

   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.
   • PACKAGE_NAMES: noms de package Android des applications autorisées à utiliser la clé. Spécifiez plusieurs noms de packages sous la forme d'une liste d'éléments séparés par une virgule.
   • WAF_FEATURE: nom de la fonctionnalité WAF. Spécifiez action-token.
   • WAF_SERVICE: nom du fournisseur de services WAF. Spécifiez CA pour Google Cloud Armor.

   Exécutez la commande gcloud recaptcha keys create:

   Linux, macOS ou Cloud Shell

   
   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --android --package-names=PACKAGE_NAMES \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --android --package-names=PACKAGE_NAMES `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --android --package-names=PACKAGE_NAMES ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   La réponse contient la clé reCAPTCHA que vous venez de créer.

   REST (iOS)

   Remarque:La création de clés reCAPTCHA pour WAF dans les applications mobiles n'est possible que pour l'intégration avec Google Cloud Armor. Pour cette intégration, vous ne pouvez créer que des clés de jeton d'action pour les applications mobiles.

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

   • DISPLAY_NAME: nom de la clé. Généralement un nom d'application.
   • BUNDLE_IDs : ID de bundle iOS des applications autorisées à utiliser la clé. Spécifiez plusieurs ID de bundle sous la forme d'une liste d'éléments séparés par une virgule.
   • WAF_FEATURE: nom de la fonctionnalité WAF. Spécifiez action-token.
   • WAF_SERVICE: nom du fournisseur de services WAF. Spécifiez CA pour Google Cloud Armor.

   Méthode HTTP et URL :

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

   Corps JSON de la requête :

   {
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
    "allowedBundleIds": "BUNDLE_IDS"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

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

   curl

   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 gcloud auth list pour vérifier 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 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

   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 gcloud auth list pour vérifier 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 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/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT",
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
       "allowAllBundleIds": false,
       "allowedBundleIds": [
           BUNDLE_IDS
       ]
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

   REST (Android)

   Remarque:La création de clés reCAPTCHA pour WAF dans les applications mobiles n'est possible que pour l'intégration avec Google Cloud Armor. Pour cette intégration, vous ne pouvez créer que des clés de jeton d'action pour les applications mobiles.

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

   • DISPLAY_NAME: nom de la clé. Généralement un nom d'application.
   • PACKAGE_NAMES: noms de package Android des applications autorisées à utiliser la clé. Spécifiez plusieurs noms de packages sous la forme d'une liste d'éléments séparés par une virgule.
   • WAF_FEATURE: nom de la fonctionnalité WAF. Spécifiez action-token.
   • WAF_SERVICE: nom du fournisseur de services WAF. Spécifiez CA pour Google Cloud Armor.

   Méthode HTTP et URL :

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

   Corps JSON de la requête :

   {
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
     "allowedPackageNames":"PACKAGE_NAMES"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

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

   curl

   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 gcloud auth list pour vérifier 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 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

   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 gcloud auth list pour vérifier 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 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/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy",
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
         "allowAllPackageNames": false,
         "allowedPackageNames": [
             PACKAGE_NAMES
         ],
         "supportNonGoogleAppStoreDistribution": false
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

2. Intégrez le SDK mobile reCAPTCHA Enterprise à vos applications mobiles avec la clé de jeton d'action que vous avez créée. Pour obtenir des instructions, consultez le document correspondant au type de votre application mobile.

   • Pour Android, consultez Intégrer des clés WAF aux applications Android.
   • Pour iOS, consultez Intégrer des clés WAF aux applications iOS.

3. Après avoir reçu le jeton de reCAPTCHA Enterprise, associez-le à un en-tête de requête prédéfini au format suivant :

   X-Recaptcha-Token: value-of-your-action-token
   

   L'exemple de code suivant montre comment associer le jeton:

   Android

   Exemple de code en Java

   
   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   //
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of the
   // HTTP request.
   
   public static void sendRequestToServerWithRceToken(
       String serverUrl, String rceToken) throws JSONException, IOException {
    URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl));
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    connection.setRequestProperty("X-Recaptcha-Token", rceToken);
   
    try {
       String requestBody = "['']";
       sendRequest(connection, requestBody, "AccessWithRceToken", "GET");
    } finally {
       connection.disconnect();
    }
   }
   
   private static void sendRequest(
       HttpURLConnection connection, String requestString, String requestName, String action)
       throws IOException {
    connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS);
    connection.setReadTimeout(HTTP_READ_TIMEOUT_MS);
    connection.setRequestProperty("Content-type", CONTENT_TYPE);
    connection.setRequestProperty(
       "Content-Length", Integer.toString(Utf8.encodedLength(requestString)));
    connection.setRequestMethod(action);
    connection.setDoOutput(true);
    connection.connect();
    try (OutputStream postStream = connection.getOutputStream()) {
       postStream.write(requestString.getBytes(UTF_8));
    }
   
    int responseCode = connection.getResponseCode();
    String response = connection.getResponseMessage();
    if (responseCode != HttpURLConnection.HTTP_OK) {
       throw new IOException(
          String.format(
             "Failed to complete request.\nResponse code:%s\nError Detail:\n%s",
             responseCode, response));
    }
   }
   
   

   iOS

   Exemple de code en Swift

   
   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of
   // the HTTP request.
   
    public static func accessWafServer(rceToken: String, serverUrl: String)
       async throws -> String
    {
       let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl)
       var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET")
       request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token")
   
       let data = try await HttpHelper.getDataFromServer(request)
   
       return String(decoding: data, as: UTF8.self)
    }
   
   

Configurer les stratégies de sécurité Google Cloud Armor

Après avoir implémenté les fonctionnalités de reCAPTCHA Enterprise pour WAF, vous devez configurer des stratégies de sécurité Google Cloud Armor qui évaluent les jetons reCAPTCHA Enterprise pour la gestion des bots.

Pour savoir comment configurer des stratégies de sécurité Google Cloud Armor et utiliser les clés de jeton d'action avec vos stratégies de sécurité, consultez la section Configurer des règles pour la gestion des bots.

Étapes suivantes

• Configurez des règles de gestion des bots.