Activer reCAPTCHA Enterprise

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

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

Important :Cette fonctionnalité ne prend en charge que les connexions et les inscriptions par e-mail et mot de passe. les réinitialisations de mots de passe et les connexions par lien d'e-mail. 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 à reCAPTCHA, Identity Platform provisionne les clés de site reCAPTCHA basées sur des scores dans votre projet en votre nom. Lorsqu'un utilisateur accède à votre application ou à votre site en utilisant l'une des opérations suivantes : le SDK client charge reCAPTCHA:

Operation	Méthode
Connexion avec une adresse e-mail et un mot de passe	signInWithPassword
Inscription par e-mail et mot de passe	signUpPassword
Envoyer un lien de connexion par e-mail	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 la page 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 pour les utilisateurs.

Créer un compte de service

Avant d'activer reCAPTCHA, vous devez créer un compte de service pour chaque projet qui utilisera reCAPTCHA et accordera à chaque compte de service l'accès à reCAPTCHA. 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:

   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

reCAPTCHA vous propose deux modes pour vous aider à protéger les utilisateurs:

• Audit: lorsque cette option est activée, Identity Platform crée un ou plusieurs reCAPTCHA clés de votre projet qui sont utilisées pour évaluer le trafic vers les API Identity Platform sans bloquer de requêtes. Utilisez les métriques émises en mode audit pour déterminez si vous devez activer l'application de reCAPTCHA.
• Application: lorsque cette option est activée, Identity Platform crée un ou plusieurs reCAPTCHA clés de votre projet qui sont utilisées pour é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 avec Compatibilité avec reCAPTCHA.

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

Pour activer reCAPTCHA, procédez comme suit:

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

2. Activer l'intégration d'Identity Platform à reCAPTCHA pour un projet à l'aide du SDK Admin. reCAPTCHA La prise en charge est disponible avec le SDK Admin Node.js 11.7.0 et versions ultérieures.

   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. Activer l'intégration d'Identity Platform à reCAPTCHA 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. sur les plates-formes mobiles.

4. Si vous utilisez Identity Platform sur les plates-formes Apple ou Android, vous devez vous enregistrer depuis 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 qui utilise reCAPTCHA. Pour ajouter des domaines autorisés, effectuer les opérations suivantes:

   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 enregistrer le domaine.

   Le provisionnement de la clé de site peut prendre plusieurs minutes. Pour vous assurer que votre les flux de données sont protégés, vérifiez les métriques.

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 est disponible avec le SDK JavaScript 9.20.0 et versions ultérieures. Une fois le SDK Web intégré à votre application, celle-ci récupère automatiquement votre configuration reCAPTCHA 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 Collecte des signaux reCAPTCHA (nous vous recommandons de la 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 à la version 31.5.0 ou ultérieure du SDK Android. La compatibilité avec reCAPTCHA nécessite le niveau d'API 19 (KitKat) ou supérieur, ainsi qu'Android 4.4 ou version ultérieure. Une fois le SDK Android intégré à votre application, celle-ci récupère automatiquement votre configuration reCAPTCHA et protège les fournisseurs que vous avez configurés.

2. Ajoutez la règle de compilation suivante à la section des dépendances de votre application Fichier build.gradle:

   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 effectuer le reCAPTCHA la collecte des signaux est plus efficace, nous vous recommandons de la 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 à la version 10.14.0 ou ultérieure du SDK iOS. Une fois que vous avez intégré le SDK iOS à votre application, celle-ci récupère automatiquement votre configuration reCAPTCHA et protège 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 d'éditeur de liens. Accédez à 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 effectuer le reCAPTCHA collecte des signaux, nous vous recommandons de la configurer explicitement, comme suit:

   • Swift:

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

   • Objectif C:

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

Métriques reCAPTCHA

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

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

identitytoolkit.googleapis.com/recaptcha/verdict_count

Suit les différents résultats renvoyés par reCAPTCHA. 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 reCAPTCHA le mode audit est activé.
• FAILED_ENFORCE: indique qu'une requête donnée est refusée lorsque reCAPTCHA le mode application forcée est activé.
• CLIENT_TYPE_MISSING: indique qu'une requête donnée comporte un client manquant. lorsque l'application 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 qui ne possède pas Compatibilité avec reCAPTCHA.
• KEYS_MISSING: indique qu'une requête donnée ne peut pas être vérifiée en raison de la incapacité à récupérer ou à générer des clés reCAPTCHA valides lorsque L'application de reCAPTCHA est activée.

Pour modifier vos plages de scores afin de changer le ratio d'évaluations ayant réussi et échoué, procédez comme suit : consultez Activer reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

Suit le nombre et l'état des jetons reCAPTCHA 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 expiré peut indiquer des problèmes liés au réseau du client ou une utilisation abusive.
• DUPLICATE: indique que le jeton reCAPTCHA transmis est un dupliquer. Un jeton en double peut indiquer des problèmes liés au réseau du client ou une utilisation abusive.
• INVALID: indique que le jeton reCAPTCHA transmis n'est pas valide. Un jeton non valide peut indiquer un abus.
• MISSING: indique que le jeton reCAPTCHA n'existe pas dans la requête donnée. L'absence de jetons peut 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 du 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

Suit la répartition des scores reCAPTCHA. Cela peut vous aider à définir les plages de score 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:

• Si la majorité des requêtes récentes comportent des jetons valides et que le ratio de PASSED à FAILED_AUDIT ou FAILED_ENFORCE est acceptable pour votre entreprise. Dans ce cas, pensez à activer son application.
• Si la majorité des demandes récentes proviennent probablement de clients obsolètes, envisagez d'attendre que d'autres utilisateurs mettent à jour leur application avant d'activer l'application. L'intégration d'Identity Platform à reCAPTCHA entraîne le plantage des versions d'application précédentes qui ne sont pas intégrées à reCAPTCHA.

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 Sélectionner une métrique, saisissez Locataire Identity Toolkit. Si vous utilisez une architecture mutualisée, vous pouvez afficher les métriques de chaque locataire, ainsi que le projet parent, en laissant tenant_name vide.

Activer l'application des règles

Après avoir vérifié que votre application reçoit un trafic utilisateur acceptable, procédez comme suit : vous pouvez activer l'application de reCAPTCHA pour protéger vos utilisateurs. Veillez à ne pas perturber les utilisateurs existants, y compris ceux qui utilisent un l'ancienne version de votre application.

Pour activer l'application de reCAPTCHA pour un projet ou un locataire, utilisez le SDK Admin pour exécuter les tâches suivantes:

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

Désactiver reCAPTCHA

Pour désactiver reCAPTCHA, utilisez le SDK Admin pour exécuter les commandes suivantes:

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

Remplacer les évaluations reCAPTCHA avec des fonctions Cloud Run

En plus de configurer des seuils de score, vous pouvez ignorer Évaluation reCAPTCHA pour un jeton donné à l'aide d'une fonction de blocage personnalisée des fonctions Cloud Run. Cette fonctionnalité est utile lorsqu'un score reCAPTCHA pour un utilisateur donné Le nombre de connexions peut être long, mais l'utilisateur est considéré comme fiable ou a été validé via d'autres signifie et est donc autorisé à terminer la connexion.

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

Dépannage

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

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

Les utilisateurs peuvent également être bloqués en fonction de votre configuration actuelle. Essayez d'exécuter les commandes suivantes :

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