Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Intégrer Identity Platform à l'API reCAPTCHA Enterprise

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

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

Présentation

Lorsque vous configurez l'intégration d'Identity Platform à l'API reCAPTCHA Enterprise, vous activez la fonctionnalité de protection par défaut de reCAPTCHA : la protection contre les bots reCAPTCHA. Avec la protection contre les bots, Identity Platform provisionne des clés reCAPTCHA basées sur un score dans votre projet en votre nom. Lorsqu'un utilisateur accède à votre application ou à votre site à l'aide de l'une des opérations suivantes, le SDK client charge reCAPTCHA lorsque le fournisseur correspondant est activé.

Fournisseur	Opération	Méthode
`passwordProvider`	Connexion avec une adresse e-mail et un mot de passe	`signInWithPassword`
	Inscription avec une adresse e-mail et un mot de passe	`signUpPassword`
	Connexion par lien envoyé par e-mail	`getOobCode`
	Réinitialisation du mot de passe	`getOobCode`
`phoneProvider`	Inscription ou connexion avec un numéro de téléphone	`sendVerificationCode`
	Enregistrement d'un numéro de téléphone pour l'authentification multifacteur	`mfaSmsEnrollment`
	Connexion par numéro de téléphone pour l'authentification multifacteur	`mfaSmsSignIn`

reCAPTCHA fournit ensuite à Identity Platform des scores 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.

Avant de commencer

En fonction du type de flux d'authentification que vous souhaitez protéger avec reCAPTCHA, assurez-vous d'avoir configuré les éléments suivants :

Pour les flux d'authentification par adresse e-mail et mot de passe, assurez-vous d'avoir configuré la connexion par adresse e-mail pour les utilisateurs.
Pour les flux d'authentification par SMS, assurez-vous d'avoir intégré au moins l'un des éléments suivants :
- Connexion par téléphone pour les utilisateurs
- Authentification multifacteur pour votre application Web, Android ou iOS.

Créer un compte de service

L'intégration d'Identity Platform à l'API reCAPTCHA Enterprise nécessite un compte de service Identity Platform pour chaque projet qui utilisera reCAPTCHA. Cela permet à Identity Platform de gérer les clés reCAPTCHA en votre nom. Si vous avez déjà créé un compte de service, accordez-lui l'accès à reCAPTCHA.

Si vous n'avez pas encore créé de compte de service ou si vous avez d'autres projets que vous souhaitez protéger avec reCAPTCHA, 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. \
    --role=roles/identitytoolkit.serviceAgent

Remplacez les éléments suivants :

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

Comportement de la protection contre les bots reCAPTCHA par fournisseur

Le comportement de la protection contre les bots reCAPTCHA dépend du fournisseur d'identité que vous configurez :

Fournisseur d'adresse e-mail/mot de passe

Pour les flux d'authentification par adresse e-mail et mot de passe, la protection contre les bots reCAPTCHA est compatible avec deux modes : audit et application.

Mode d'audit

Lorsque vous définissez l'application de l'adresse e-mail et du mot de passe sur le mode d'audit, Identity Platform crée une ou plusieurs clés reCAPTCHA dans votre projet, qui sont utilisées pour évaluer le trafic vers les API Identity Platform sans bloquer les requêtes. Utilisez les métriques émises en mode audit pour déterminer si vous devez activer l'application de reCAPTCHA.

Mode forcé

Lorsque vous définissez l'application de l'adresse e-mail et du mot de passe sur le mode d'application, Identity Platform crée une ou plusieurs clés reCAPTCHA dans 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 qu'après avoir migré tous vos clients vers un SDK compatible avec reCAPTCHA.

Opérateur téléphonique

Lorsque vous activez la protection contre les bots pour les flux d'authentification par téléphone en définissant phoneEnforcementState sur ENFORCE et useSmsBotScore sur true, Identity Platform utilise la protection contre les bots reCAPTCHA pour la validation de l'application. Si la requête d'un utilisateur réussit l'évaluation de la protection contre les bots, un code de validation par SMS est envoyé. Si la requête d'un utilisateur échoue à l'évaluation de la protection contre les bots, Identity Platform bloque la requête et n'envoie pas de SMS contenant un code de validation.

La validation de remplacement n'est pas requise lorsque la protection contre les bots est activée pour les flux d'authentification par téléphone, et 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 disponible si vous décidez de désactiver la protection contre les bots.

Configurer l'intégration d'Identity Platform à l'API reCAPTCHA Enterprise

Pour configurer l'intégration d'Identity Platform à l'API reCAPTCHA Enterprise, procédez comme suit :

Utilisez le SDK Admin pour définir l'état d'application de reCAPTCHA et activer la protection contre les bots.
Configurez le SDK client pour la plate-forme de votre application.

Pour les flux d'authentification par e-mail et mot de passe, nous vous recommandons d'activer d'abord l'application de reCAPTCHA en mode audit et de surveiller les métriques reCAPTCHA émises par votre projet afin d'éviter d'interrompre le trafic utilisateur tout en vérifiant que les flux d'authentification sont protégés. Après avoir vérifié que vos flux d'authentification sont protégés, définissez la protection contre les bots sur ENFORCE. Pour les flux d'authentification par téléphone, activez la protection contre les bots en définissant phoneEnforcementState sur ENFORCE et useSmsBotScore sur true, puis surveillez les métriques reCAPTCHA pour affiner vos seuils de score.

Activer la protection contre les bots reCAPTCHA

Fournisseur d'adresse e-mail/mot de passe

Pour activer la protection contre les bots reCAPTCHA pour les flux d'authentification par adresse e-mail et mot de passe, procédez comme suit :

Si vous ne l'avez pas déjà fait, activez l'API reCAPTCHA Enterprise sur votre projet.
Pour activer la protection contre les bots pour un projet, utilisez le SDK Admin. La compatibilité avec reCAPTCHA est disponible sur les versions 11.7.0 et ultérieures du SDK Admin Node.js.

Exemple :
```
// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE_MODE',
    managedRules: [{
      endScore: END_SCORE,
      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);
  });
}
```
Remplacez les éléments suivants :
- ENFORCE_MODE : mode que vous souhaitez définir pour l'application de l'authentification par adresse e-mail et mot de passe reCAPTCHA. Les valeurs valides sont OFF, AUDIT et ENFORCE. Pour activer la protection contre les bots, ce paramètre doit être défini sur AUDIT ou ENFORCE. Lorsque vous activez la protection contre les bots 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 Comportement de la protection contre les bots reCAPTCHA par fournisseur.
- END_SCORE : score d'évaluation de la protection contre les bots le plus bas qu'une requête peut avoir avant d'échouer. Vous pouvez définir ce score entre 0.0 et 1.0. Par exemple, si vous définissez un seuil de 0.6, reCAPTCHA échouera pour toute requête avec un score de 0.5 ou moins. Par conséquent, plus le score que vous définissez est élevé, plus les règles seront strictes.
Vous pouvez également activer la protection contre les bots avec la même méthode de configuration pour un locataire à l'aide du SDK Admin. Pour en savoir plus sur la mise à jour d'un locataire, consultez Mettre à jour un locataire.
Si vous utilisez Identity Platform sur iOS ou Android, vous devez enregistrer votre application depuis la console Firebase :
- Pour iOS, 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 qui utilise 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 de domaine, puis cliquez sur Ajouter pour l'enregistrer.
Le provisionnement de la clé reCAPTCHA peut prendre plusieurs minutes.
Si vous avez défini l'application sur le mode audit, nous vous recommandons de surveiller les métriques reCAPTCHA pour la protection contre les bots afin de vous assurer que vos flux sont protégés.

Opérateur téléphonique

Pour activer la protection contre les bots reCAPTCHA pour les flux d'authentification par SMS, procédez comme suit :

Si vous ne l'avez pas déjà fait, activez l'API reCAPTCHA Enterprise sur votre projet.
Pour activer la protection contre les bots pour un projet, utilisez le SDK Admin. La compatibilité avec reCAPTCHA est disponible dans les versions 12.7.0 et ultérieures du SDK Admin Node.js.

Exemple :
```
// Update project config with reCAPTCHA config
const updateProjectConfigRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    managedRules: [{
      endScore: END_SCORE,
      action: 'BLOCK'
    }],
    useSmsBotScore: true,
  }
};
let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
```
Remplacez END_SCORE par le score d'évaluation de protection contre les bots le plus bas qu'une requête peut avoir avant d'échouer. Vous pouvez définir ce score entre 0.0 et 1.0. Par exemple, si vous définissez un seuil de 0.6, reCAPTCHA échoue pour toute requête avec un score de 0.5 ou inférieur. Par conséquent, plus vous définissez un score élevé, plus les règles sont strictes.

Définir phoneEnforcementState sur ENFORCE et useSmsBotScore sur true active l'application de la protection contre les bots pour les flux d'authentification par SMS. Pour en savoir plus sur le fonctionnement de l'application des règles par les opérateurs téléphoniques, consultez Comportement de la protection contre les bots reCAPTCHA par opérateur.

Vous pouvez également activer la protection contre les bots avec la même méthode de configuration pour un locataire à l'aide du SDK Admin. Pour en savoir plus sur la mise à jour d'un locataire, consultez Mettre à jour un locataire.

Remarque : Identity Platform n'est pas compatible avec l'authentification par téléphone et l'authentification multifacteur par SMS avec plusieurs locataires sur les plates-formes mobiles.
Si vous utilisez Identity Platform sur iOS ou Android, vous devez enregistrer votre application depuis la console Firebase :
- Pour iOS, 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 qui utilise 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 de domaine, puis cliquez sur Ajouter pour l'enregistrer.
Le provisionnement de la clé reCAPTCHA peut prendre plusieurs minutes.
Surveillez les métriques reCAPTCHA pour la protection contre les bots 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

Installez la dernière version du SDK Web.
- La compatibilité de reCAPTCHA avec l'authentification par adresse 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 dans les versions 11 et ultérieures du SDK JavaScript.
Une fois que vous avez intégré le SDK Web à votre application, le SDK récupère automatiquement votre configuration reCAPTCHA et active la protection pour les fournisseurs que vous avez configurés.

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

Installez la dernière version du SDK Android. La compatibilité de reCAPTCHA avec l'authentification par adresse e-mail et mot de passe et l'authentification par téléphone dans les applications Android est disponible sur la version 23.1.0 et ultérieure du SDK Android.

De plus, la compatibilité avec reCAPTCHA nécessite le niveau d'API 23 (Marshmallow) ou supérieur et 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.
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.5.1'
```
Veillez à utiliser la version 18.5.1 ou ultérieure du SDK reCAPTCHA.

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

Installez 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.
Pour intégrer le SDK reCAPTCHA pour iOS à votre application, consultez Préparer votre environnement.
Assurez-vous que -ObjC est listé dans vos options de l'éditeur de liens. Accédez à Target > Build Settings > All > Linking (Cible > Paramètres de compilation > Tout > Association), puis vérifiez que Other Linker Flags affiche -ObjC.

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 les bots

Surveillez les métriques reCAPTCHA émises par votre projet pour vous assurer que les flux d'authentification sont protégés. Pour les flux d'authentification par e-mail et mot de passe, nous vous recommandons de surveiller les métriques en mode audit avant de définir l'application sur le mode forcé. Par exemple, ces métriques peuvent vous aider à déterminer si vous avez correctement configuré l'intégration d'Identity Platform à l'API reCAPTCHA Enterprise. Ils peuvent également vous aider à affiner votre seuil de score pour le trafic utilisateur. Si le provisionnement de la clé reCAPTCHA échoue ou si les comptes de service requis n'ont pas été créés, les tentatives d'authentification reCAPTCHA aboutissent quand même normalement.

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

identitytoolkit.googleapis.com/recaptcha/verdict_count : suit les différents verdicts renvoyés par reCAPTCHA.
identitytoolkit.googleapis.com/recaptcha/token_count : suit le nombre et l'état des jetons reCAPTCHA reçus par le backend Identity Platform.
identitytoolkit.googleapis.com/recaptcha/risk_scores : suit la distribution des scores de protection contre les bots.

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

Appliquer la protection contre les bots reCAPTCHA pour les flux d'adresse e-mail/mot de passe

Pour les flux d'authentification par e-mail et mot de passe que vous avez initialement configurés en mode AUDIT, après avoir vérifié que votre application reçoit un trafic utilisateur acceptable, vous pouvez passer de emailPasswordEnforcementState à ENFORCE pour bloquer les requêtes qui échouent à l'évaluation reCAPTCHA. Veillez à ne pas perturber les utilisateurs existants, y compris ceux qui utilisent une ancienne version de votre application.

Pour activer l'application de reCAPTCHA pour les flux d'authentification par adresse e-mail et mot de passe sur un projet ou un locataire, utilisez le SDK Admin pour exécuter le code suivant :

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState: 'ENFORCE',
  }
};

Désactiver la protection contre les bots reCAPTCHA

Fournisseur d'adresse e-mail/mot de passe

Pour désactiver la protection contre les bots pour les flux d'authentification par adresse e-mail et mot de passe, utilisez le SDK Admin pour exécuter la commande suivante :

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

Opérateur téléphonique

Pour désactiver toute protection reCAPTCHA par téléphone, y compris la protection contre les bots, pour les flux d'authentification par SMS, utilisez le SDK Admin pour exécuter la commande suivante :

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

Si vous utilisez également reCAPTCHA SMS Defense et que vous souhaitez le laisser activé tout en désactivant la protection contre les bots, définissez useSmsBotScore sur false et laissez phoneEnforcementState défini sur ENFORCE :

const disableBotScoreOnlyRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    useSmsBotScore: false,
    useSmsTollFraudProtection: true
  }
};

Ignorer les verdicts reCAPTCHA avec des fonctions Cloud Run

En plus de configurer des seuils de score, vous pouvez ignorer un verdict reCAPTCHA pour un jeton donné en utilisant des fonctions de blocage pour autoriser ou bloquer des flux en fonction de facteurs personnalisés. Cela est utile dans les cas où le score reCAPTCHA d'une connexion utilisateur donnée peut être faible, mais où l'utilisateur est de confiance ou a été validé par d'autres moyens et est donc autorisé à se connecter.

L'exemple suivant montre comment ignorer un verdict reCAPTCHA à l'aide de fonctions de blocage :

Node.js

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

Étapes suivantes

Activez reCAPTCHA SMS defense pour les flux d'authentification par SMS.
Découvrez comment utiliser votre propre clé reCAPTCHA.
En savoir plus sur la surveillance des métriques reCAPTCHA.
En savoir plus sur reCAPTCHA