Activer reCAPTCHA Enterprise

Ce document explique comment utiliser Identity Platform avec reCAPTCHA Enterprise pour renforcer la sécurité de vos utilisateurs. Cette fonctionnalité rend votre application plus résistante au spam, aux utilisations abusives et aux autres activités frauduleuses.

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

Aperçu

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

Opération	Méthode
Connexion par e-mail et par mot de passe	`signInWithPassword`
Inscription par e-mail et par mot de passe	`signUpPassword`
Connexion au lien de l'adresse 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 Présentation de reCAPTCHA Enterprise.

Avant de commencer

Configurez la connexion aux e-mails pour les 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. Cela permet à Identity Platform de gérer les clés reCAPTCHA à votre place.

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

Utilisez 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.

Autorisez le compte de service à accéder à reCAPTCHA Enterprise:

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 projet
PROJECT_NUMBER: numéro de compte du projet

Activer reCAPTCHA Enterprise

reCAPTCHA propose deux modes pour protéger les utilisateurs:

Audit: lorsqu'elle est activée, Identity Platform crée une ou plusieurs clés reCAPTCHA Enterprise dans 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éterminer si vous devez activer l'application forcée de reCAPTCHA.
Application: lorsqu'elle est activée, Identity Platform crée une ou plusieurs clés reCAPTCHA Enterprise dans votre projet, qui sont utilisées pour évaluer le trafic vers les API Identity Platform. Les requêtes API qui ne contiennent pas de jeton reCAPTCHA sont refusées. Activez l'application forcée uniquement après avoir migré tous vos clients vers un SDK compatible avec reCAPTCHA Enterprise.

Pour activer reCAPTCHA Enterprise, procédez comme suit:

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

Activer l'intégration d'Identity Platform avec reCAPTCHA Enterprise pour un projet à l'aide du SDK Admin. La compatibilité de reCAPTCHA Enterprise est disponible avec les versions 11.7.0 et ultérieures du SDK Admin 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);
  });
}

Activer l'intégration d'Identity Platform avec 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

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:
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 des clés de site peut prendre plusieurs minutes. Pour vous assurer que vos flux 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

Installez la dernière version du SDK Web. La compatibilité avec reCAPTCHA Enterprise est disponible dans les versions 9.20.0 et ultérieures du SDK JavaScript. Une fois le SDK Web intégré à votre application, il récupère automatiquement votre configuration reCAPTCHA Enterprise 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 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

Installez la version 31.5.0 ou ultérieure du SDK Android. La prise en charge de reCAPTCHA Enterprise nécessite le niveau d'API 19 (KitKat) ou une version ultérieure et Android 4.4 ou une version ultérieure. Une fois le SDK Android intégré à votre application, il récupère automatiquement votre configuration reCAPTCHA Enterprise 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.1.1'
```

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

Installez la version 10.14.0 ou ultérieure du SDK iOS. Une fois le SDK iOS intégré à votre application, il récupère automatiquement votre configuration reCAPTCHA Enterprise et protège les fournisseurs que vous avez configurés.
Pour intégrer le SDK reCAPTCHA de iOS à votre application, consultez Préparer votre environnement.
Assurez-vous que -ObjC est répertorié dans vos indicateurs d'association. Accédez à Cible > Paramètres de compilation > Toutes > Association, puis vérifiez que Other 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 le 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. Si le provisionnement de la clé de site reCAPTCHA échoue ou si des 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 émises par Cloud Monitoring dans votre projet:

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

Suit les différents résultats renvoyés par reCAPTCHA Enterprise. Un verdict est généré en cas de présence d'un jeton. Vous pouvez filtrer sur les verdicts suivants:

PASSED: indique qu'une requête donnée est autorisée lorsque l'application forcée 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 qui n'est pas compatible avec reCAPTCHA.
KEYS_MISSING: indique qu'une requête donnée ne peut pas être validée en raison de l'impossibilité de récupérer ou de 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 entre les résultats et les échecs, consultez Activer reCAPTCHA Enterprise.

`identitytoolkit.googleapis.com/recaptcha/token_count`

Suit le nombre et l'état des jetons reCAPTCHA Enterprise reçus par le backend Identity Platform. Vous pouvez filtrer les données en fonction des é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 en double. 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. Les jetons manquants peuvent indiquer une application cliente obsolète.
UNCHECKED: indique que le jeton reCAPTCHA n'a pas été vérifié en raison de résultats de CLIENT_TYPE_MISSING ou de KEYS_MISSING.

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

`identitytoolkit.googleapis.com/recaptcha/risk_scores`

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

Utilisez ces métriques pour déterminer si vous pouvez activer l'application. Tenez compte des points suivants avant d'activer cette fonctionnalité:

Si la majorité des requêtes récentes disposent de jetons valides et que le ratio de PASSED à FAILED_AUDIT ou FAILED_ENFORCE de verdicts est acceptable pour votre cas d'utilisation, envisagez d'activer l'application forcée de jetons.
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'application d'Identity Platform à reCAPTCHA Enterprise interrompt les 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:

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

Accéder à l'explorateur de métriques
Dans Sélectionner une métrique, saisissez Identity Locataire. Si vous utilisez l'architecture mutualisée, vous pouvez afficher les métriques pour chaque locataire, ainsi que pour le 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 le trafic utilisateur acceptable, vous pouvez activer l'application forcée de reCAPTCHA pour protéger vos utilisateurs. Veillez à ne pas déranger 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 le SDK Admin à l'aide de la commande suivante:

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

Désactiver reCAPTCHA Enterprise

Pour désactiver reCAPTCHA Enterprise, utilisez le SDK Admin pour exécuter la commande suivante:

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

Dépannage

Les utilisateurs ne peuvent 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 une version mise à jour de votre application qui utilise le SDK client, désactivez immédiatement le mode application forcée. Sinon, demandez à vos utilisateurs de mettre à jour leur appli.

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

Pour une configuration plus permissive, ajustez les scores de 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 application forcée.