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.
Présentation
Lorsque vous configurez l'intégration d'Identity Platform à reCAPTCHA, Identity Platform provisionne pour vous des clés de site reCAPTCHA basées sur des scores dans votre projet. Lorsqu'un utilisateur accède à votre application ou à votre site à l'aide de l'une des opérations suivantes, le SDK client charge reCAPTCHA:
Opération | 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.
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 accorder à chaque compte de service l'accès à reCAPTCHA. Cela permet à Identity Platform de gérer les clés reCAPTCHA en votre nom.
Pour créer un compte de service, procédez comme suit :
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.Accordez au compte de service l'accès à reCAPTCHA:
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 projetPROJECT_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 une ou plusieurs clés reCAPTCHA dans votre projet afin d'évaluer le trafic vers les API Identity Platform sans bloquer les requêtes. Déterminez si vous devez activer l'application de reCAPTCHA à l'aide des métriques émises en mode audit.
- Application: lorsque cette option est activée, Identity Platform crée une ou plusieurs clés reCAPTCHA dans votre projet, lesquelles 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 qu'après avoir migré tous vos clients vers un SDK compatible avec reCAPTCHA.
Pour activer reCAPTCHA, procédez comme suit:
- Si vous ne l'avez pas déjà fait, activez l'API reCAPTCHA sur votre projet.
Activez l'intégration d'Identity Platform à reCAPTCHA pour un projet à l'aide du SDK Admin. La compatibilité de reCAPTCHA est disponible sur 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); }); }
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
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.
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:
Dans la console Google Cloud, accédez à la page "Identity Platform".
Accédez à Settings > Security (Paramètres > Sécurité).
Cliquez sur Ajouter un domaine.
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 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
Installez la dernière version du SDK Web. La prise en charge de reCAPTCHA est disponible avec le SDK JavaScript 9.20.0 et versions ultérieures. Une fois que vous avez intégré le SDK Web à votre application, celui-ci récupère automatiquement votre configuration reCAPTCHA et protège les fournisseurs que vous avez configurés.
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 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
Passez au SDK Android version 31.5.0 ou ultérieure. 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, il récupère automatiquement votre configuration reCAPTCHA et protège les fournisseurs que vous avez configurés.
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.4.0'
Veillez à utiliser le SDK reCAPTCHA version 18.4.0 ou ultérieure.
Pour réduire le nombre d'appels réseau effectués par le SDK et pour rendre la collecte des signaux reCAPTCHA 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
Passez à la version 10.14.0 ou ultérieure du SDK iOS. Une fois que vous avez intégré le SDK iOS à votre application, celui-ci récupère automatiquement votre configuration reCAPTCHA et protège les fournisseurs que vous avez configurés.
Pour intégrer le SDK iOS reCAPTCHA à votre application, consultez Préparer votre environnement.
Assurez-vous que
-ObjC
est répertorié dans vos indicateurs d'éditeur de liens. Accédez à Target > Build Settings > All > Linking, puis vérifiez queOther Linker Flags
affiche-ObjC
.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()
- 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 que votre projet émet 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 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 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 à une requête donnée 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 n'est pas 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 reCAPTCHA est activée.
Pour modifier vos plages de scores afin de changer le ratio d'évaluations ayant réussi/échec, 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 double. 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 évaluationsCLIENT_TYPE_MISSING
ouKEYS_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 des 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:
- Si la majorité des requêtes récentes comportent des jetons valides et que le ratio entre les évaluations
PASSED
etFAILED_AUDIT
ouFAILED_ENFORCE
est acceptable pour votre cas d'utilisation, envisagez d'activer l'application. - 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. 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:
Dans Google Cloud Console, accédez à la page Explorateur de métriques.
Dans Sélectionner une métrique, saisissez Locataire Identity Toolkit. Si vous utilisez l'architecture mutualisée, vous pouvez afficher les métriques de chaque locataire, ainsi que du projet parent, en laissant le champ
tenant_name
vide.
Activer l'application des règles
Après avoir vérifié que votre application reçoit un 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, utilisez le SDK Admin pour exécuter les opérations 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 Cloud Functions
En plus de configurer des seuils de score, vous pouvez ignorer une évaluation reCAPTCHA pour un jeton donné à l'aide d'une fonction de blocage Cloud Functions personnalisée. Cela est utile dans les cas où un score reCAPTCHA pour une connexion utilisateur donnée peut être faible, mais que l'utilisateur est approuvé 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, consultez la page Étendre Firebase Authentication avec des fonctions de blocage Cloud Functions.
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ésactivez 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 clés 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.