Activer reCAPTCHA SMS defense pour l'authentification par SMS

Ce document explique comment utiliser reCAPTCHA SMS defense pour protéger vos flux Identity Platform par SMS, comme l'authentification par téléphone et multifacteur, contre la fraude à la facturation par l'opérateur via SMS (également appelée "attaques par inflation artificielle du trafic"). Cette intégration permet d'empêcher le trafic SMS non autorisé d'avoir un impact négatif sur vos utilisateurs et vos ressources.

Présentation

Si votre application s'appuie sur les SMS pour l'authentification, nous vous recommandons d'activer l'intégration de reCAPTCHA SMS defense. Une fois cette fonctionnalité activée, Firebase Authentication et Identity Platform invoquent automatiquement la fonctionnalité de protection reCAPTCHA par SMS chaque fois qu'un utilisateur final demande un message SMS de validation depuis votre application ou votre site à l'aide des opérations phoneProvider suivantes :

reCAPTCHA fournit ensuite à Firebase Authentication ou Identity Platform un score de risque qui indique la probabilité de fraude à la facturation par l'opérateur via SMS pour le numéro de téléphone de l'utilisateur. Ce score est ensuite comparé au seuil que vous avez configuré. Si le score de risque dépasse ce seuil, le message SMS n'est pas envoyé, ce qui bloque efficacement les tentatives de fraude.

Pour comprendre comment fonctionnent les scores de protection reCAPTCHA SMS, consultez Interpréter les scores.

Pour en savoir plus sur la fonctionnalité de protection reCAPTCHA par SMS, consultez Détecter et prévenir la fraude par SMS.

Modes d'application de l'authentification par téléphone reCAPTCHA

Vous pouvez configurer l'application de l'authentification par téléphone pour reCAPTCHA SMS Defense en mode audit ou application forcée.

Mode Audit

Lorsque vous définissez l'application de l'authentification par téléphone sur le mode audit, Identity Platform utilise la protection reCAPTCHA par SMS pour la validation des applications. Si la demande d'un utilisateur réussit l'évaluation concernant la fraude à la facturation par l'opérateur, un code de validation par SMS est envoyé. Si la demande d'un utilisateur échoue à l'évaluation concernant la fraude à la facturation par l'opérateur et que vous utilisez le SDK client, Identity Platform déclenche des méthodes de validation de secours pour terminer le flux d'authentification par téléphone. Les méthodes de secours acceptées dépendent de la plate-forme de votre application.

Le SDK client déclenche les méthodes de validation de secours dans les scénarios suivants :

• Le jeton reCAPTCHA est manquant.
• Le jeton reCAPTCHA n'est pas valide ou a expiré.
• Le jeton reCAPTCHA ne dépasse pas le seuil de score.
• reCAPTCHA n'est pas configuré correctement.

Assurez-vous que les méthodes de validation de secours pour la plate-forme de votre application sont configurées et prêtes à être déclenchées par le SDK client si nécessaire.

Mode application forcée

Lorsque vous définissez l'application de l'authentification par téléphone sur le mode "Appliquer", Identity Platform utilise la protection reCAPTCHA par SMS pour la validation de l'application. Si la demande d'un utilisateur réussit l'évaluation concernant la fraude à la facturation par l'opérateur, un code de validation par SMS est envoyé. Si la demande d'un utilisateur échoue à l'évaluation concernant la fraude à la facturation par l'opérateur, Identity Platform bloque la demande et n'envoie pas de message SMS contenant un code de validation.

Aucune validation de secours n'est requise en mode "Appliquer". Vous n'avez pas besoin de configurer de méthodes de validation supplémentaires pour votre application. Toutefois, nous vous recommandons de configurer un outil de vérification reCAPTCHA pour les applications Web afin de vous assurer que reCAPTCHA v2 est activé si vous décidez de passer au mode reCAPTCHA AUDIT ou OFF pour votre application.

Avant de commencer

Avant d'activer reCAPTCHA SMS defense pour Identity Platform, effectuez les tâches suivantes :

• Configurez les éléments suivants pour votre application ou votre site, le cas échéant :

  • Connexion par téléphone pour les utilisateurs
  • Authentification multifacteur pour votre application Web, Android ou iOS.

• Configurez Firebase Authentication pour votre application ou votre site, selon le cas :

  • Web : Configurer l'authentification par téléphone
  • iOS : Configurer l'authentification par téléphone
  • Android : Configurer l'authentification par téléphone

Activer reCAPTCHA SMS defense

1. Configurez l'authentification :

   1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

   2. Créez une identité de service :

      gcloud beta services identity create \
          --service=identitytoolkit.googleapis.com \
          --project=PROJECT_ID
      

      Remplacez PROJECT_ID par l'ID du projet.

   3. Attribuez le rôle roles/identitytoolkit.serviceAgent à l'identité de service que vous avez créée.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
       --role=roles/identitytoolkit.serviceAgent
   

   Remplacez les éléments suivants :

   • PROJECT_ID : ID du projet
   • PROJECT_NUMBER : numéro de compte du projet

2. Activez l'API reCAPTCHA Enterprise sur votre projet.

3. Activez reCAPTCHA SMS defense pour votre projet :

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

      Accéder à reCAPTCHA

   2. Vérifiez que le nom de votre projet s'affiche dans le sélecteur de ressources.

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

   3. Cliquez sur settings Paramètres.

   4. Dans le volet Protection contre les SMS, cliquez sur Configurer.

   5. Cliquez sur le bouton Activer, puis sur Enregistrer.

   Lorsque vous activez reCAPTCHA SMS defense, Account Defender est également activé, si ce n'est pas déjà le cas.

   L'activation de reCAPTCHA SMS defense peut prendre quelques minutes à se propager dans nos systèmes. Une fois la propagation effectuée, vous commencerez à recevoir des réponses liées à reCAPTCHA SMS defense dans les évaluations.

4. Pour configurer les paramètres de protection reCAPTCHA contre la fraude à la facturation par l'opérateur via SMS pour un projet Firebase Authentication ou Identity Platform, procédez comme suit :

   1. Dans l'URL suivante, remplacez PROJECT_ID, Recaptcha_MODE et START_SCORE :

      https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"emailPasswordEnforcementState":"OFF","phoneEnforcementState":"Recaptcha_MODE","useSmsTollFraudProtection":true,"tollFraudManagedRules":[{"action":"BLOCK","startScore":START_SCORE}]}}}
      

      • PROJECT_ID : identifiant du projet pour lequel Identity Platform est activé.

      • Recaptcha_MODE : mode que vous souhaitez définir pour l'application forcée de l'authentification par téléphone reCAPTCHA. Les valeurs valides sont OFF, AUDIT et ENFORCE. Pour activer reCAPTCHA SMS defense, ce paramètre doit être défini sur AUDIT ou ENFORCE, et useSmsTollFraudProtection doit être défini sur true.

        Lorsque vous activez reCAPTCHA SMS defense pour la première fois, utilisez le mode AUDIT pour vous assurer que la configuration de reCAPTCHA SMS defense fonctionne correctement. Le mode AUDIT est strictement réservé à la validation. Ce mode n'empêche pas le trafic SMS non autorisé. Vérifiez qu'aucune défaillance n'apparaît dans le tableau de bord Métriques. Après la validation, activez immédiatement le mode ENFORCE. Pour en savoir plus sur le fonctionnement des modes, consultez Modes d'application de l'authentification par téléphone reCAPTCHA.

      • START_SCORE : score d'évaluation de la fraude par numéros surtaxés le plus élevé qu'une requête peut avoir avant d'échouer. Vous pouvez définir ce score sur une valeur comprise entre 0.1 et 0.9. Nous vous recommandons de commencer par un seuil plus élevé, par exemple 0.8, puis de réduire progressivement le score. Les scores supérieurs au seuil que vous avez défini sont traités comme des fraudes par SMS. Si vous définissez un score de 1,0, la protection contre la fraude est désactivée. Si vous définissez un score de 0,0, tous les messages SMS sont bloqués. Plus le score est bas, plus les règles sont strictes. Si vous définissez un seuil de 0.3, par exemple, reCAPTCHA échoue toute requête avec un score de 0.4 ou plus.

   2. Saisissez l'URL dans une nouvelle fenêtre de navigateur dans laquelle vous êtes connecté à la console Google Cloud .

1. Si vous utilisez Identity Platform sur le Web ou Android, enregistrez votre application depuis la console Firebase :

   • Pour Android, enregistrez chaque nom de package Android qui utilise Identity Platform.

   • Pour le Web, ajoutez un domaine autorisé pour chaque domaine qui utilise reCAPTCHA :

     1. Dans la console Google Cloud , accédez à la page Identity Platform.

        Accéder à Identity Platform

     2. Accédez à Paramètres > Sécurité.

     3. Cliquez sur Ajouter un domaine.

     4. Saisissez le nom de domaine, puis cliquez sur Ajouter pour l'enregistrer.

   Le provisionnement des clés reCAPTCHA peut prendre plusieurs minutes.

2. Vérifiez votre configuration :

   • Récupérez les informations de configuration reCAPTCHA :

     {replace-your-project} avec votre projectId ou projectNumber. Exécutez l'API GetConfig dans le panneau latéral pour récupérer la configuration reCAPTCHA.

   • Vérifiez que reCAPTCHA SMS defense est correctement configuré :

     1. Si la configuration reCAPTCHA est correctement configurée, la réponse doit comporter les champs suivants avec les valeurs spécifiées :

        • recaptchaKeys : le champ ne doit pas être vide et doit être configuré pour au moins l'une des plates-formes suivantes : iOS, Web ou Android.
        • useSmsTollFraudProtection : la valeur de ce champ doit être définie sur true.
        • phoneEnforcementState : la valeur doit être définie sur ENFORCE ou AUDIT.
        • tollFraudManagedRules : dans ce champ, startScore doit être configuré avec le seuil de votre choix, qui doit être une valeur comprise entre 0 et 0,9.

        Sinon, configurez à nouveau reCAPTCHA SMS defense.

        Exemple de réponse

          {
            "recaptchaConfig": {
                "recaptchaKeys": [
                  {
                    "key": "projects/{your-project}/keys/{recaptcha-key}",
                    "type": "WEB"
                  },
                  {
                    "type": "IOS"
                  },
                  {
                    "type": "ANDROID"
                  }
                ],
                "phoneEnforcementState": "ENFORCE",
                "tollFraudManagedRules": [
                  {
                    "startScore": 0.8,
                    "action": "BLOCK"
                  }
                ],
                "useSmsTollFraudProtection": true
            }
          }
          ```
        

3. Vérifiez que les versions du SDK sont correctes.

   Web

   Passez à la dernière version du SDK Web.

   • La compatibilité de reCAPTCHA avec l'authentification par e-mail et mot de passe dans les applications Web est disponible dans les versions 9.20.0 et ultérieures du SDK JavaScript.
   • La compatibilité de reCAPTCHA avec l'authentification par téléphone dans les applications Web est disponible dans les versions 11 et ultérieures du SDK JavaScript.

   Une fois le SDK Web intégré à votre application, il récupère automatiquement votre configuration reCAPTCHA et active la protection pour les fournisseurs que vous avez configurés.

   Android

   1. Mettez à jour le SDK Android vers la dernière version. La compatibilité reCAPTCHA pour l'authentification par e-mail et mot de passe, ainsi que l'authentification par téléphone dans les applications Android, est disponible sur la version 23.1.0 et ultérieure du SDK Android.

      De plus, la compatibilité avec reCAPTCHA nécessite le niveau d'API 23 (Marshmallow) ou supérieur, et Android 6 ou version ultérieure.

      Une fois que vous avez intégré le SDK Android à votre application, il récupère automatiquement votre configuration reCAPTCHA et applique les seuils que vous avez définis pour les fournisseurs que vous avez configurés.

   2. Ajoutez la règle de compilation suivante à la section des dépendances du fichier build.gradle au niveau de l'application :

      implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
      

      Assurez-vous d'utiliser le SDK reCAPTCHA version 18.5.1 ou ultérieure.

   iOS

   1. Passez à la version 11.6.0 ou ultérieure du SDK iOS.

   Une fois que vous avez intégré le SDK iOS à votre application, il récupère automatiquement votre configuration reCAPTCHA et applique les seuils que vous avez définis pour les fournisseurs que vous avez configurés.

   1. Pour intégrer le SDK iOS reCAPTCHA à votre application, consultez Préparer votre environnement iOS.

   2. Pour vérifier que -ObjC est répertorié dans vos options de l'éditeur de liens, accédez à Cible > Paramètres de compilation > Tous > Liaison et vérifiez que Other Linker Flags affiche -ObjC.

Surveiller les métriques reCAPTCHA pour reCAPTCHA SMS defense

Surveillez les métriques reCAPTCHA émises par votre projet pour vérifier que vos flux d'authentification par SMS sont protégés. Par exemple, ces métriques peuvent vous aider à déterminer si vous avez correctement configuré l'intégration Identity Platform avec l'API reCAPTCHA Enterprise. Ils peuvent également vous aider à affiner le seuil de score pour votre trafic utilisateur.

Vérifiez que la fonctionnalité reCAPTCHA SMS Defense fonctionne en consultant les métriques suivantes que votre projet émet dans Cloud Monitoring :

• identitytoolkit.googleapis.com/recaptcha/verdict_count
• identitytoolkit.googleapis.com/recaptcha/token_count
• identitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores

Pour en savoir plus, consultez Surveiller les métriques reCAPTCHA.

Appliquer reCAPTCHA SMS defense

Après avoir vérifié que votre application reçoit un trafic utilisateur acceptable, activez le mode ENFORCE de reCAPTCHA pour bloquer activement les requêtes frauduleuses et protéger ainsi les utilisateurs.

Pour activer le mode ENFORCE pour les flux d'authentification par SMS sur un projet ou un locataire, utilisez Google APIs Explorer pour mettre à jour la configuration du projet en saisissant l'URL HTTP suivante dans une nouvelle fenêtre de navigateur dans laquelle vous êtes connecté à la console Google Cloud  :

   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"ENFORCE","useSmsTollFraudProtection":"true"}}}

Remplacez PROJECT_ID par l'ID du projet.

Utiliser reCAPTCHA SMS defense avec la protection contre les robots

Vous pouvez utiliser reCAPTCHA SMS defense en même temps que la protection contre les robots. Pour les configurations qui utilisent les deux fonctionnalités de protection, tenez compte des points suivants :

• Lorsque vous définissez l'état d'application de l'authentification par téléphone sur AUDIT, Identity Platform transmet une requête si elle satisfait au moins l'une des évaluations. Nous vous recommandons de surveiller les métriques reCAPTCHA pour vérifier que la protection reCAPTCHA par SMS et la protection contre les robots sont configurées avec des paramètres de score raisonnables.
• Lorsque vous définissez l'état d'application de l'authentification par téléphone sur ENFORCE, Identity Platform ne transmet une requête que si elle satisfait aux deux évaluations et que la requête échoue sans revenir à une autre méthode de validation.

Pour activer les deux fonctionnalités, utilisez Google APIs Explorer pour mettre à jour la configuration du projet :

        recaptchaConfig: {
          phoneEnforcementState:  'ENFORCE_MODE',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

Remplacez ENFORCE_MODE par le mode que vous souhaitez définir pour l'application de l'authentification par téléphone reCAPTCHA. Les valeurs valides sont OFF, AUDIT et ENFORCE. Lorsque vous activez la protection reCAPTCHA par SMS pour la première fois, nous vous recommandons de définir ce paramètre sur AUDIT et de vous assurer que vos flux d'authentification sont protégés avant de le définir sur ENFORCE. Pour en savoir plus sur le fonctionnement des modes, consultez Modes d'application de l'authentification par téléphone reCAPTCHA.

Désactiver reCAPTCHA SMS defense lorsque vous utilisez la protection contre les robots

Si vous utilisez à la fois reCAPTCHA SMS Defense et la protection contre les robots, et que vous souhaitez désactiver reCAPTCHA SMS Defense sans désactiver la protection contre les robots, utilisez l'Google APIs Explorer pour mettre à jour la configuration du projet :

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }

Remplacez ENFORCE_MODE par le mode que vous avez défini précédemment pour l'application de l'authentification par téléphone reCAPTCHA. Cette valeur doit être AUDIT ou ENFORCE. Pour en savoir plus sur le fonctionnement des modes, consultez Modes d'application de l'authentification par téléphone reCAPTCHA.

Désactiver reCAPTCHA SMS defense

Pour désactiver la protection reCAPTCHA par SMS, utilisez l'Google APIs Explorer pour mettre à jour la configuration du projet en saisissant l'URL HTTP suivante dans une nouvelle fenêtre de navigateur dans laquelle vous êtes connecté à la console Google Cloud  :

   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":"false"}}}

Remplacez PROJECT_ID par l'ID du projet.

Pour désactiver reCAPTCHA SMS defense lorsque vous utilisez la protection contre les robots, consultez Désactiver reCAPTCHA SMS defense lorsque vous utilisez la protection contre les robots.

Étapes suivantes

• En savoir plus sur la fonctionnalité de protection reCAPTCHA par SMS