Activer reCAPTCHA Enterprise

Ce document explique comment utiliser l'intégration d'Identity Platform à reCAPTCHA Enterprise pour améliorer la sécurité de vos utilisateurs. Cette fonctionnalité rend votre application plus résistante contre le spam, les utilisations abusives et d'autres activités frauduleuses.

L'intégration d'Identity Platform à reCAPTCHA Enterprise crée une évaluation reCAPTCHA Enterprise en votre nom afin de valider les requêtes des utilisateurs. Pour en savoir plus sur les tarifs, consultez les tarifs de reCAPTCHA Enterprise.

Important :Cette fonctionnalité n'est compatible qu'avec les connexions et les inscriptions par e-mail et mot de passe, les réinitialisations de mots de passe et les connexions par lien de messagerie. Si un utilisateur légitime est bloqué, consultez la section Dépannage pour connaître la procédure de résolution.

Présentation

Lorsque vous configurez l'intégration d'Identity Platform avec reCAPTCHA Enterprise, Identity Platform provisionne des clés de site reCAPTCHA Enterprise basées sur des scores dans votre projet, en votre nom. Lorsqu'un utilisateur accède à votre application ou à votre site en effectuant l'une des opérations suivantes, le SDK client charge reCAPTCHA Enterprise:

Opération	Méthode
Connexion avec l'adresse e-mail et le mot de passe	signInWithPassword
Inscription avec une adresse e-mail et un mot de passe	signUpPassword
Envoyer un lien par e-mail pour se connecter	getOobCode
Réinitialisation du mot de passe	getOobCode

reCAPTCHA fournit ensuite à Identity Platform des signaux de risque qui évaluent le risque de la requête en fonction de votre configuration et de votre tolérance au risque.

Pour en savoir plus, consultez Présentation de reCAPTCHA Enterprise.

Important : Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• reCAPTCHA Enterprise
• Identity Platform

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

Configurez la connexion par e-mail des utilisateurs.

Créer un compte de service

Avant d'activer reCAPTCHA Enterprise, vous devez créer un compte de service pour chaque projet qui utilisera reCAPTCHA, et accorder à chaque compte de service l'accès à reCAPTCHA Enterprise. Identity Platform peut ainsi gérer les clés reCAPTCHA en votre nom.

Pour créer un compte de service, procédez comme suit :

1. Utilisez la Google Cloud CLI pour créer un compte de service:

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

   Remplacez PROJECT_ID par l'ID du projet.

2. Accordez au compte de service l'accès à reCAPTCHA Enterprise:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/identitytoolkit.serviceAgent
   

   Remplacez les éléments suivants :

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

Activer reCAPTCHA Enterprise

reCAPTCHA propose deux modes qui vous aident à protéger les utilisateurs:

• Audit: lorsque cette option est activée, Identity Platform crée une ou plusieurs clés reCAPTCHA Enterprise dans votre projet, qui permettent d'évaluer le trafic vers les API Identity Platform sans bloquer les requêtes. Utilisez les métriques émises pendant le mode audit pour déterminer si vous devez activer l'application de reCAPTCHA.
• Mise en application: lorsque cette option est activée, Identity Platform crée une ou plusieurs clés reCAPTCHA Enterprise dans votre projet, qui permettent d'évaluer le trafic vers les API Identity Platform. Les requêtes API qui n'incluent pas de jeton reCAPTCHA sont refusées. N'activez l'application forcée qu'après avoir migré tous vos clients vers un SDK compatible avec reCAPTCHA Enterprise.

Important :Ne modifiez pas et ne supprimez pas les clés reCAPTCHA Enterprise nommées "Clé pour l'intégration d'Identity Platform à reCAPTCHA Enterprise", sauf si reCAPTCHA est désactivé. Cela empêche Identity Platform d'appliquer la protection reCAPTCHA. De plus, les SDK Identity Platform ne peuvent pas générer de jetons à partir de clés reCAPTCHA que vous générez vous-même.

Pour activer reCAPTCHA Enterprise, procédez comme suit:

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

2. Activez l'intégration d'Identity Platform à reCAPTCHA Enterprise pour un projet utilisant le SDK administrateur. La compatibilité de reCAPTCHA Enterprise est disponible sur les versions 11.7.0 et ultérieures du SDK administrateur Node.js.

   Exemple :

   // Get project config
   const getProjectConfig = () => {
     getAuth().projectConfigManager().getProjectConfig()
     .then((response) => {
       console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error getting project config:', error);
     });
   }
   
   // Update project config with reCAPTCHA config
   const updateConfigRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         action: 'BLOCK'
       }]
     }
   };
   const updateProjectConfigWithRecaptcha = () => {
     getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
       console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error updating project config:', error);
     });
   }
   

3. Activez l'intégration d'Identity Platform à reCAPTCHA Enterprise pour un locataire à l'aide du SDK Admin. Exemple :

   // Update tenant with reCAPTCHA config
   const updateTenantRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         action: 'BLOCK'
       }]
     }
   };
   const updateTenantWithRecaptchaConfig = () => {
     getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
     .then((response) => {
       console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error updating the tenant:', error);
     });
   }
   

   Remplacez les éléments suivants :

   • TENANT_ID: ID du locataire
   Remarque :Identity Platform n'est pas compatible avec l'architecture mutualisée avec reCAPTCHA Enterprise sur les plates-formes mobiles.

4. Si vous utilisez Identity Platform sur les plates-formes Apple ou Android, vous devez enregistrer votre application à partir de la console Firebase:

   • Pour les plates-formes Apple, enregistrez chaque ID de bundle qui utilise Identity Platform.
   • Pour Android, enregistrez chaque nom de package Android qui utilise Identity Platform.

5. Si vous utilisez Identity Platform sur le Web, vous devez ajouter un domaine autorisé pour chaque domaine utilisant reCAPTCHA. Pour ajouter des domaines autorisés, procédez comme suit:

   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 du domaine, puis cliquez sur Ajouter pour l'enregistrer.

   Le provisionnement de la clé de site peut prendre plusieurs minutes. Pour vous assurer que vos flux sont protégés, vérifiez les metrics.

Configurer le SDK client

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

Web

1. Installez la dernière version du SDK Web. La compatibilité avec reCAPTCHA Enterprise est disponible à partir de la version 9.20.0 du SDK JavaScript. Une fois que vous avez intégré le SDK Web à votre application, il récupère automatiquement votre configuration reCAPTCHA Enterprise et protège les fournisseurs que vous avez configurés.

2. Pour réduire le nombre d'appels réseau effectués par le SDK et améliorer la collecte des signaux reCAPTCHA, nous vous recommandons de le configurer explicitement comme suit:

   import { initializeRecaptchaConfig } from '@firebase/auth';
   
   // Initialize Firebase Auth
   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 au SDK Android 31.5.0 ou version ultérieure. La compatibilité avec reCAPTCHA Enterprise nécessite le niveau d'API 19 (KitKat) ou supérieur, et Android 4.4 ou version ultérieure. Une fois que vous avez intégré le SDK Android à votre application, il récupère automatiquement votre configuration reCAPTCHA Enterprise et protège 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.4.0'
   

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

3. Pour réduire le nombre d'appels réseau effectués par le SDK et améliorer l'efficacité de la collecte des signaux reCAPTCHA, nous vous recommandons de le configurer explicitement comme suit:

   • Kotlin:

   // Initialize Firebase Auth
   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 Auth
   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 au SDK iOS version 10.14.0 ou ultérieure. Une fois que vous avez intégré le SDK iOS à votre application, il récupère automatiquement votre configuration reCAPTCHA Enterprise et protège les fournisseurs que vous avez configurés.

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

3. Assurez-vous que -ObjC est répertorié dans les indicateurs de votre éditeur de liens. Accédez à Target > Build Settings > All > Linking (Cible > Paramètres de compilation > Tout > Association) et vérifiez que Other Linker Flags affiche -ObjC.

4. Pour réduire le nombre d'appels réseau effectués par le SDK et améliorer l'efficacité de la collecte des signaux reCAPTCHA, nous vous recommandons de la configurer explicitement, comme suit:

   • Swift:

   // Initialize Firebase Auth
   try await Auth.auth().initializeRecaptchaConfig()
   

   • Objective-C:

   // Initialize Firebase Auth
   [[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
     // Firebase Auth initialization finished
   }];
   

Métriques reCAPTCHA Enterprise

Après avoir activé reCAPTCHA Enterprise, surveillez les métriques reCAPTCHA émises par votre projet pour vous assurer que les flux d'authentification sont protégés. En cas d'échec du provisionnement des clés de site reCAPTCHA ou si les comptes de service requis n'ont pas été créés, l'authentification reCAPTCHA échoue.

Assurez-vous que l'authentification reCAPTCHA fonctionne en examinant les métriques suivantes que votre projet émet à Cloud Monitoring:

identitytoolkit.googleapis.com/recaptcha/verdict_count

Effectue le suivi des différentes évaluations renvoyées par reCAPTCHA Enterprise. Une évaluation est générée si un jeton est présent. Vous pouvez filtrer les évaluations suivantes:

• PASSED: indique qu'une requête donnée est autorisée lorsque l'application est activée.
• FAILED_AUDIT: indique qu'une requête donnée est refusée lorsque le mode d'audit reCAPTCHA est activé.
• FAILED_ENFORCE: indique qu'une requête donnée est refusée lorsque le mode d'application de reCAPTCHA est activé.
• CLIENT_TYPE_MISSING: indique qu'il manque un type de client pour une requête donnée lorsque l'application de reCAPTCHA est activée. Cela se produit généralement si une requête a été envoyée à l'aide d'une version obsolète du SDK client non compatible avec reCAPTCHA.
• KEYS_MISSING: indique qu'une requête donnée ne peut pas être validée, car il est impossible de récupérer ou de générer des clés reCAPTCHA valides lorsque l'application forcée de reCAPTCHA est activée.

Pour modifier vos plages de scores afin de changer le ratio entre les évaluations réussies et les échecs, consultez Activer reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

Effectue le suivi du nombre et de l'état des jetons reCAPTCHA Enterprise reçus par le backend Identity Platform. Vous pouvez filtrer les états suivants:

• VALID: indique que le jeton reCAPTCHA transmis est valide.
• EXPIRED: indique que le jeton reCAPTCHA transmis a expiré. Un jeton arrivé à expiration peut indiquer des problèmes ou une utilisation abusive du réseau client.
• DUPLICATE: indique que le jeton reCAPTCHA transmis est un doublon. Un jeton en double peut indiquer des problèmes ou une utilisation abusive du réseau client.
• INVALID: indique que le jeton reCAPTCHA transmis n'est pas valide. Un jeton non valide peut indiquer une utilisation abusive.
• MISSING: indique que le jeton reCAPTCHA n'existe pas dans la requête donnée. Des jetons manquants peuvent indiquer une application cliente obsolète.
• UNCHECKED: indique que le jeton reCAPTCHA n'a pas été vérifié en raison des évaluations CLIENT_TYPE_MISSING ou KEYS_MISSING.

Si votre application a bien été déployée auprès des utilisateurs, vous verrez le trafic avec des jetons valides. Le nombre de jetons valides est probablement proportionnel au nombre d'utilisateurs de votre application mise à jour.

identitytoolkit.googleapis.com/recaptcha/risk_scores

Effectue le suivi de la distribution du score reCAPTCHA. Cela peut vous aider à définir les plages de scores optimales pour votre configuration.

Ces métriques vous permettent de déterminer si vous pouvez activer l'application forcée. Tenez compte des points suivants avant d'activer l'application forcée:

• Si la majorité des requêtes récentes contiennent des jetons valides et que le ratio entre les évaluations PASSED et FAILED_AUDIT ou FAILED_ENFORCE est acceptable pour votre cas d'utilisation, envisagez d'activer l'application forcée.
• Si la majorité des requêtes récentes proviennent probablement de clients obsolètes, envisagez d'attendre que davantage d'utilisateurs mettent à jour leur application avant d'activer l'application forcée. L'intégration d'Identity Platform avec reCAPTCHA Enterprise entraîne l'interruption des versions précédentes de l'application qui ne sont pas intégrées à reCAPTCHA Enterprise.

Pour afficher ces métriques, procédez comme suit:

1. Dans Google Cloud Console, accédez à la page Explorateur de métriques.

   Accéder à l'explorateur de métriques

2. Dans le champ Sélectionner une métrique, saisissez Identity Toolkit Tenant. Si vous utilisez l'architecture mutualisée, vous pouvez afficher les métriques de chaque locataire, ainsi que du projet parent, en laissant tenant_name vide.

Activer l'application des règles

Après avoir vérifié que votre application reçoit du trafic utilisateur acceptable, vous pouvez activer l'application de reCAPTCHA pour protéger vos utilisateurs. Veillez à 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 un projet ou un locataire, exécutez la commande suivante à l'aide du SDK administrateur:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

Désactiver reCAPTCHA Enterprise

Pour désactiver reCAPTCHA Enterprise, exécutez la commande suivante à l'aide du SDK Admin:

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

Remplacer les évaluations reCAPTCHA Enterprise avec Cloud Functions

En plus de configurer des seuils de score, vous pouvez remplacer une évaluation reCAPTCHA Enterprise pour un jeton donné à l'aide d'une fonction de blocage personnalisée Cloud Functions. Cela est utile dans les cas où le score reCAPTCHA pour un utilisateur donné peut être faible, mais que l'utilisateur est fiable ou a été validé par d'autres moyens, et est donc autorisé à se connecter.

Pour en savoir plus sur la configuration des fonctions de blocage avec reCAPTCHA Enterprise, consultez la page Étendre Firebase Authentication avec le blocage des fonctions Cloud.

Dépannage

Les utilisateurs ne peuvent pas se connecter, s'inscrire ou réinitialiser leur mot de passe

Les utilisateurs se servent peut-être d'une version obsolète de l'application. Si vous n'avez pas fourni de version mise à jour de votre application qui utilise le SDK client, désactivez immédiatement le mode d'application. Sinon, demandez à vos utilisateurs de mettre à jour leur application.

Il se peut également que des utilisateurs soient bloqués en fonction de votre configuration actuelle. Essayez d'exécuter les commandes suivantes :

• Envisagez une configuration plus permissive en ajustant les scores des clés reCAPTCHA.
• Demandez à l'utilisateur d'essayer un autre appareil, navigateur ou réseau.
• Revenez au mode audit et surveillez les métriques avant de réactiver le mode forcé.