Activer reCAPTCHA SMS defense pour l'authentification par SMS

Ce document explique comment utiliser reCAPTCHA SMS defense pour protéger vos flux Identity Platform basés sur les SMS, tels que 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'éviter que le trafic SMS non autorisé n'affecte négativement vos utilisateurs et vos ressources.

Présentation

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

Opération Méthode
S'inscrire ou se connecter avec un numéro de téléphone sendVerificationCode
Enregistrement d'un numéro de téléphone pour l'authentification multifacteur mfaSmsEnrollment
Connexion par numéro de téléphone pour l'authentification MFA mfaSmsSignIn

reCAPTCHA fournit ensuite à Firebase Authentication ou Identity Platform un score de risque qui indique la probabilité d'une fraude à la facturation par l'opérateur pour le numéro de téléphone de l'utilisateur. Ce score est ensuite comparé au seuil que vous avez configuré. 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 le score de risque dépasse le seuil que vous avez configuré, Identity Platform bloque la requête et n'envoie pas de SMS contenant un code de validation.

Lorsque reCAPTCHA SMS defense est activé, aucune validation de remplacement n'est requise et vous n'avez pas besoin de configurer de méthodes de validation supplémentaires pour votre application. Toutefois, nous vous recommandons de configurer le vérificateur reCAPTCHA pour les applications Web afin de vous assurer que reCAPTCHA v2 est disponible si vous décidez de désactiver reCAPTCHA SMS defense.

Pour comprendre le fonctionnement des scores de la protection par SMS reCAPTCHA, consultez Interpréter les scores.

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

Avant de commencer

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

Activer reCAPTCHA SMS defense

  1. Configurez l'authentification :

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

      Activer 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. \
    --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 apparaît dans le sélecteur de ressources.

      Si vous ne voyez pas le nom de votre projet, cliquez sur le sélecteur de ressources, puis sélectionnez votre projet.

    3. Cliquez sur Paramètres.

    4. Dans le volet SMS defense, 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à fait.

    La propagation de l'activation de reCAPTCHA SMS defense dans nos systèmes peut prendre quelques minutes. Une fois la propagation terminée, vous commencerez à recevoir des réponses liées à reCAPTCHA SMS defense dans le cadre des évaluations.

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

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

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

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

      • START_SCORE : seuil configurable qui détermine le score le plus élevé qu'une requête SMS peut avoir avant d'être signalée et bloquée en tant que fraude à la facturation par l'opérateur.

        Le seuil minimal est de 0.0. Le seuil maximal est de 0.9. Toute requête dont le score est supérieur au seuil est considérée comme frauduleuse. Par exemple, si vous définissez le seuil sur 0.3, reCAPTCHA bloquera toutes les requêtes dont le score de fraude est supérieur ou égal à 0.4.

        Pour augmenter le niveau de protection contre la fraude, définissez le seuil sur une valeur inférieure. Pour réduire le niveau de protection contre la fraude, définissez le seuil sur une valeur plus élevée. Ce paramètre permettra à davantage de requêtes avec des scores plus élevés de passer.

        Pour l'implémentation initiale, nous vous recommandons de commencer par un seuil plus élevé, tel que 0.8, puis de le réduire de manière itérative en fonction de votre tolérance au risque spécifique.

        Nous vous déconseillons de définir un seuil de 0.0 ou 1.0. Si vous définissez le seuil sur 0.0, tous les SMS seront bloqués, tandis que 1.0 désactivera complètement la protection contre la fraude, ce qui peut entraîner des échecs de diffusion des SMS dans les régions à haut risque.

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

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

  6. Vérifiez votre configuration :

    • Récupérez les détails de la configuration reCAPTCHA :

      {replace-your-project} par 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 de ces plates-formes : 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.
        • 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
    }
  }
  ```

  7. Assurez-vous que les versions du SDK sont correctes.

    Web

    Installez la dernière version du SDK Web.

    • La compatibilité de reCAPTCHA avec l'authentification par adresse 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 que vous avez intégré le SDK Web à votre application, le SDK récupère automatiquement votre configuration reCAPTCHA et active la protection pour les fournisseurs que vous avez configurés.

    Android

    1. Installez la dernière version du SDK Android. La compatibilité de reCAPTCHA avec l'authentification par adresse e-mail et mot de passe et 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'

      Veillez à utiliser la version 18.5.1 ou ultérieure du SDK reCAPTCHA.

    iOS

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

    Une fois que vous avez intégré le SDK iOS à votre application, le SDK 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 reCAPTCHA pour iOS à votre application, consultez Préparer votre environnement iOS.

    2. Pour vérifier que -ObjC figure dans vos options d'éditeur de liens, accédez à Target > Build Settings > All > Linking (Cible > Paramètres de compilation > Tout > Association), puis 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 d'Identity Platform à 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 vérifiant les métriques suivantes que votre projet envoie à Cloud Monitoring :

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

Utiliser reCAPTCHA SMS defense avec la protection contre les bots

Vous pouvez utiliser reCAPTCHA SMS defense en même temps que la protection contre les bots. Lorsque les deux sont activés et que phoneEnforcementState est défini sur ENFORCE, Identity Platform ne transmet une requête que si elle satisfait aux deux évaluations, et la requête échoue sans basculer vers 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',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

Désactiver reCAPTCHA SMS defense tout en utilisant la protection contre les bots

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

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

Définissez phoneEnforcementState sur ENFORCE et useSmsBotScore sur true pour que la protection contre les bots reste activée pour les flux d'authentification par téléphone.

Désactiver reCAPTCHA SMS defense

Pour désactiver toutes les protections reCAPTCHA pour les téléphones, y compris la protection reCAPTCHA pour les SMS, utilisez Google APIs Explorer pour mettre à jour la configuration du projet en saisissant l'URL HTTP suivante dans une nouvelle fenêtre de navigateur où 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.phoneEnforcementState,recaptchaConfig.useSmsTollFraudProtection,recaptchaConfig.useSmsBotScore","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":false,"useSmsBotScore":false}}}

Remplacez PROJECT_ID par l'ID du projet.

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

Étapes suivantes