Activer la protection contre la fraude à la facturation par l'opérateur via SMS pour l'authentification par SMS

Ce document explique comment utiliser reCAPTCHA 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 attaque par inflation artificielle du trafic).

Présentation

Si votre application s'appuie sur un flux par SMS pour l'authentification, vous pouvez activer la fonctionnalité de protection contre la fraude à la facturation par l'opérateur via SMS de reCAPTCHA dans le cadre de l'intégration d'Identity Platform à reCAPTCHA. Lorsqu'elle est activée, Identity Platform appelle la fonctionnalité de protection contre la fraude à la facturation par l'opérateur via SMS lorsqu'un utilisateur demande un SMS de validation à partir de votre application ou de votre site à l'aide des opérations phoneProvider suivantes:

Operation 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 avec un numéro de téléphone pour l'authentification MFA mfaSmsSignIn

reCAPTCHA fournit ensuite à Identity Platform un score de risque qui indique la probabilité que le numéro de téléphone de l'utilisateur soit utilisé pour commettre une fraude par SMS. Identity Platform compare ce score au seuil que vous avez défini dans la configuration de la protection contre la fraude à la facturation par l'opérateur via SMS, puis gère la requête en fonction de l'action que vous avez définie dans votre configuration.

Pour en savoir plus sur la fonctionnalité de protection contre la fraude à la facturation par l'opérateur via SMS de reCAPTCHA, consultez Détection et prévention de la fraude par SMS.

Avant de commencer

Avant d'activer la protection contre la fraude à la facturation par l'opérateur via SMS pour Identity Platform, effectuez les tâches suivantes:

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

La protection contre la fraude à la facturation par l'opérateur via SMS reCAPTCHA nécessite que vous ayez configuré l'application reCAPTCHA pour forcer l'authentification par téléphone. Cette application propose deux modes: audit et forcer.

Mode d'audit

Lorsque vous définissez l'application de l'authentification par téléphone en mode d'audit, Identity Platform utilise la protection contre la fraude à la facturation par l'opérateur via SMS reCAPTCHA pour la validation des applications. Si la demande de l'utilisateur passe l'évaluation de la fraude à la facturation par l'opérateur, Identity Platform envoie un message SMS contenant un code de validation sur le téléphone de l'utilisateur. Si l'évaluation de la fraude par péage échoue pour une requête et que vous utilisez le SDK client, des méthodes de validation de remplacement sont déclenchées pour terminer le flux d'authentification par téléphone. Les méthodes de remplacement acceptées dépendent de la plate-forme de votre application.

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

  • Le jeton reCAPTCHA est manquant.
  • Le jeton reCAPTCHA n'est pas valide ou a expiré.
  • Le score du jeton reCAPTCHA n'atteint pas le seuil.
  • reCAPTCHA n'est pas configuré correctement.

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

Web

Si l'évaluation initiale de la fraude aux péages échoue, le mode d'audit s'appuie sur reCAPTCHA v2 pour la validation. Vous devez donc configurer l'outil de vérification reCAPTCHA (RecaptchaVerifier) et le transmettre aux opérations d'authentification par téléphone suivantes:

  • verifyPhoneNumber
  • signInWithPhoneNumber
  • linkWithPhoneNumber
  • reauthenticateWithPhoneNumber
Sans l'outil de validation reCAPTCHA, Identity Platform ne peut pas lancer reCAPTCHA v2 et renvoie auth/argument-error. Pour en savoir plus sur la configuration de l'outil de vérification reCAPTCHA, consultez Configurer l'outil de vérification reCAPTCHA dans la documentation Firebase.

Android

Si l'évaluation initiale de la fraude liée aux péages échoue, le mode d'audit vérifie votre application par rapport à l'API Play Integrity. Si cette validation échoue, reCAPTCHA v2 est déclenché. reCAPTCHA v2 peut être déclenché dans les scénarios suivants:

  • Si les services Google Play ne sont pas installés sur l'appareil de l'utilisateur final.
  • Si l'application n'est pas distribuée via le Google Play Store (sur le SDK Authentication v21.2.0 ou version ultérieure).
  • Si le jeton SafetyNet obtenu n'était pas valide (sur les versions du SDK Authentication antérieures à la version 21.2.0).
Pour en savoir plus sur la configuration de la validation des applications Android, consultez Activer la validation des applications dans la documentation Firebase.

iOS

Si l'évaluation initiale de la fraude aux péages échoue, le mode d'audit s'appuie sur des notifications push silencieuses pour la validation. Cette méthode de validation implique d'envoyer un jeton à votre application sur l'appareil à l'origine de la demande à l'aide d'une notification push silencieuse. Si votre application reçoit la notification, le processus d'authentification du téléphone se poursuit. Si votre application ne reçoit pas la notification push, reCAPTCHA v2 est déclenché. reCAPTCHA v2 peut être déclenché si les notifications push silencieuses ne sont pas configurées correctement.

Pour en savoir plus sur la configuration de la validation des applications iOS, consultez la section Activer la validation des applications dans la documentation Firebase.

Mode d'application forcée

Lorsque vous définissez l'application de l'authentification par téléphone sur le mode "Enforcement" (Application), Identity Platform utilise la protection contre la fraude à la facturation par l'opérateur via SMS reCAPTCHA pour la validation de l'application. Si la requête de l'utilisateur passe l'évaluation de la fraude aux péages, Identity Platform envoie un message SMS contenant un code de validation sur le téléphone de l'utilisateur. Si l'évaluation de la fraude par péage échoue, Identity Platform bloque la requête et n'envoie pas de message SMS contenant un code de validation.

Aucune vérification de remplacement n'est requise en mode d'application, 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 activé si vous décidez de définir le mode reCAPTCHA de votre application sur AUDIT ou OFF.

Activer la protection reCAPTCHA contre la fraude à la facturation par l'opérateur via SMS

Pour activer la protection contre la fraude à la facturation par l'opérateur via SMS, procédez comme suit:

  1. Si vous ne l'avez pas déjà fait, activez l'API reCAPTCHA Enterprise dans votre projet.

  2. Activez la protection contre la fraude à la facturation par l'opérateur via SMS avec reCAPTCHA. Pour obtenir des instructions, consultez la section Avant de commencer de la page "Détection et prévention des fraudes par SMS" de la documentation reCAPTCHA.

  3. Pour activer la protection contre la fraude à la facturation par l'opérateur via SMS pour un projet, utilisez le SDK Admin pour appeler updateConfig comme suit:

      // Update the reCAPTCHA config to enable toll fraud protection
  const updateProjectConfigRequest = {
    recaptchaConfig: {
      phoneEnforcementState: 'ENFORCE_MODE',
      useSmsTollFraudProtection: 'true',
      tollFraudManagedRules: [{ startScore: START_SCORE,
        action: 'BLOCK' }],
    }
  }
  let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);

    Remplacez les éléments suivants :

    • ENFORCE_MODE: 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. Pour activer la protection contre la fraude à la facturation par l'opérateur via SMS, ce paramètre doit être défini sur AUDIT ou ENFORCE, et useSmsTollFraudProtection doit être défini sur true.

      Lorsque vous activez la protection contre la fraude à la facturation par l'opérateur via SMS pour la première fois, nous vous recommandons de définir l'état d'application 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 la section Modes d'application de l'authentification par téléphone reCAPTCHA.

    • START_SCORE: score d'évaluation de la fraude par péage le plus élevé qu'une requête peut avoir avant d'échouer. Vous pouvez définir ce score entre 0.0 et 1.0. Tout score supérieur au seuil que vous définissez sera considéré comme une fraude par SMS. Par exemple, si vous définissez un seuil de 0.3, reCAPTCHA échouera à toute requête avec un 0.4 ou plus. Par conséquent, plus le score est bas, plus les règles sont strictes.

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

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

  5. Si vous avez défini l'application de la règle en mode audit, nous vous recommandons de surveiller les métriques reCAPTCHA pour la protection contre la fraude par SMS afin de vous assurer que vos flux sont protégés.

Configurer le SDK client

Configurez le SDK client en fonction de la plate-forme de votre application.

Web

  1. 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 pour 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.

  2. Si nécessaire, vous pouvez forcer la récupération du signal reCAPTCHA comme suit:

    import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Authentication
const auth = getAuth();
initializeRecaptchaConfig(auth)
  .then(() => {
    console.log("Recaptcha Enterprise Config Initialization successful.")
  })
  .catch((error) => {
    console.error("Recaptcha Enterprise Config Initialization failed with " + error)
  });

Android

  1. Passez à la dernière version du SDK Android. La prise en charge de reCAPTCHA pour l'authentification par e-mail et mot de passe, ainsi que pour l'authentification par téléphone dans les applications Android, est disponible à partir de la version 23.1.0 du SDK Android.

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

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

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

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

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

  3. Si nécessaire, vous pouvez forcer la récupération du signal reCAPTCHA comme suit:

    • Kotlin:
    // Initialize Firebase Authentication
auth = Firebase.auth

auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
    if (task.isSuccessful) {
        Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
    } else {
        Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
    }
}
    • Java :
    // Initialize Firebase Authentication
auth = FirebaseAuth.getInstance();
auth.initializeRecaptchaConfig().addOnCompleteListener(
  this, new OnCompleteListener<void>() {
  @Override
  public void onComplete(@NonNull Task<void> task) {
    if (task.isSuccessful()) {
      Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
    } else {
      Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
    }
  }
});

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 active la protection pour les fournisseurs que vous avez configurés.

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

  3. Assurez-vous que -ObjC est répertorié dans vos indicateurs de l'éditeur de liens. Accédez à Cible > Paramètres de compilation > Tous > Association et vérifiez que Other Linker Flags affiche -ObjC.

  4. Si nécessaire, vous pouvez forcer la récupération du signal reCAPTCHA comme suit:

    • Swift:
    // Initialize Firebase Authentication
try await Auth.auth().initializeRecaptchaConfig()
    • Objective-C:
    // Initialize Firebase Authentication
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Authentication initialization finished
}];

Surveiller les métriques reCAPTCHA pour la protection contre la fraude à la facturation par l'opérateur via SMS

Avant de définir l'application de reCAPTCHA sur le mode forcé, nous vous recommandons d'utiliser le mode audit et de surveiller les métriques reCAPTCHA que votre projet émet pour vous assurer 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 avec l'API reCAPTCHA Enterprise. Ils peuvent également vous aider à affiner le seuil de score pour votre trafic utilisateur.

Assurez-vous que la fonctionnalité de protection contre la fraude par SMS fonctionne en examinant les métriques suivantes que votre projet envoie à Cloud Monitoring:

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

Appliquer la protection contre la fraude à la facturation par l'opérateur via SMS

Une fois que vous avez vérifié que votre application reçoit un trafic utilisateur acceptable, vous pouvez activer l'application reCAPTCHA pour protéger vos utilisateurs. Assurez-vous de ne pas perturber les utilisateurs existants, y compris ceux qui utilisent peut-être une ancienne version de votre application.

Pour activer l'application de reCAPTCHA pour les flux d'authentification par SMS sur un projet ou un locataire, exécutez la commande suivante à l'aide du SDK administrateur:

  const enforceRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }
  };

Désactiver la protection contre la fraude à la facturation par l'opérateur via SMS

Pour désactiver la protection contre la fraude par SMS, utilisez le SDK Admin pour exécuter la commande suivante:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'OFF',
      useSmsTollFraudProtection: 'false'
    }
  };

Pour désactiver la protection contre la fraude à la facturation par l'opérateur via SMS lorsque vous utilisez la protection contre les bots, consultez Désactiver la protection contre la fraude à la facturation par l'opérateur via SMS lorsque vous utilisez la protection contre les bots.

Utiliser la protection contre la fraude à la facturation par l'opérateur via SMS avec la protection contre les bots

Vous pouvez utiliser la protection contre la fraude à la facturation par l'opérateur via SMS simultanément avec la protection contre les bots. Pour les configurations qui utilisent les deux fonctionnalités de protection, tenez compte des points suivants:

  • Lorsque vous avez défini l'état d'application de l'authentification par téléphone sur "audit", Identity Platform transmet une requête lorsqu'elle répond à au moins l'une des évaluations. Nous vous encourageons à surveiller les métriques reCAPTCHA pour vous assurer que la protection contre la fraude à la facturation par l'opérateur via SMS et la protection contre les robots sont configurées avec des paramètres de score raisonnables.
  • Lorsque vous avez défini l'état d'application de l'authentification par téléphone sur "Enforcer", Identity Platform ne transmet une requête que lorsqu'elle répond aux deux évaluations. L'échec de la requête se termine sans recourir à une autre méthode de validation.

Pour activer les deux fonctionnalités, utilisez le SDK Admin pour exécuter la commande suivante:

  const enableBothRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: true,
      useSmsBotScore: true
    }
  };

Remplacez ENFORCE_MODE par le 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 la protection contre la fraude à la facturation par l'opérateur via SMS, ce paramètre doit être défini sur AUDIT ou ENFORCE. Lorsque vous activez la protection contre la fraude 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 la section Modes d'application de l'authentification par téléphone reCAPTCHA.

Désactiver la protection contre la fraude à la facturation par l'opérateur via SMS lorsque vous utilisez la protection contre les bots

Si vous utilisez à la fois la protection contre la fraude à la facturation par l'opérateur via SMS et la protection contre les bots, et que vous souhaitez désactiver la protection contre la fraude à la facturation par l'opérateur via SMS sans désactiver la protection contre les bots, utilisez le SDK Admin pour exécuter la commande suivante:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }
  };

Remplacez ENFORCE_MODE par le mode que vous avez précédemment défini 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 la section Modes d'application de l'authentification par téléphone reCAPTCHA.

Étape suivante