Premiers pas avec App Check avec reCAPTCHA Enterprise dans les applications Web

Cette page explique comment activer App Check dans une application Web à l'aide du fournisseur reCAPTCHA Enterprise. Lorsque vous activez App Check, vous vous assurez que seule votre application peut accéder aux ressources backend de votre projet. Consultez la présentation de cette fonctionnalité.

Notez que App Check utilise des clés de site basées sur le score reCAPTCHA Enterprise, ce qui le rend invisible pour les utilisateurs. Le fournisseur reCAPTCHA Enterprise ne demandera jamais aux utilisateurs de résoudre un défi.

Si votre cas d'utilisation nécessite des fonctionnalités reCAPTCHA Enterprise non implémentées par App Check, ou si vous souhaitez utiliser App Check avec votre propre fournisseur personnalisé, consultez Implémenter un fournisseur App Check personnalisé.

1. Configurer votre projet Firebase

  1. Ajoutez Firebase à votre projet JavaScript si ce n'est pas déjà fait.

  2. Ouvrez la section reCAPTCHA Enterprise de la console Cloud, puis procédez comme suit :

    1. Si vous êtes invité à activer l'API reCAPTCHA Enterprise, faites-le.
    2. Créez une clé de type Site Web. Vous devrez spécifier les domaines sur lesquels vous hébergez votre application Web. Laissez l'option "Utiliser le défi de la case à cocher" désélectionnée.

  3. Enregistrez vos applications pour utiliser App Check avec le fournisseur reCAPTCHA Enterprise dans la section App Check de la console Firebase. Vous devrez fournir la clé de site que vous avez obtenue à l'étape précédente.

    Vous devez généralement enregistrer toutes les applications de votre projet, car une fois que vous avez activé l'application pour un produit Firebase, seules les applications enregistrées pourront accéder aux ressources backend du produit.

  4. Facultatif : Dans les paramètres d'enregistrement de l'application, définissez une durée de vie (TTL) personnalisée pour les jetons émis par le fournisseur.App Check Vous pouvez définir la durée de vie sur n'importe quelle valeur comprise entre 30 minutes et 7 jours. Lorsque vous modifiez cette valeur, tenez compte des compromis suivants :

    • Sécurité : des durées de vie plus courtes offrent une sécurité renforcée, car elles réduisent la fenêtre pendant laquelle un jeton divulgué ou intercepté peut être utilisé de manière abusive par un pirate informatique.
    • Performances : des durées de vie plus courtes signifient que votre application effectuera une attestation plus fréquemment. Étant donné que le processus d'attestation de l'application ajoute de la latence aux requêtes réseau chaque fois qu'il est effectué, une durée de vie courte peut avoir un impact sur les performances de votre application.
    • Quota et coût : des durées de vie plus courtes et une nouvelle attestation fréquente épuisent votre quota plus rapidement et, pour les services payants, peuvent entraîner des coûts plus élevés. Consultez Quotas et limites.

    La durée de vie par défaut de 1 heure est raisonnable pour la plupart des applications. Notez que la bibliothèque App Check actualise les jetons environ à la moitié de la durée de vie.

Configurer les paramètres avancés (facultatif)

Lorsqu'un utilisateur consulte votre application Web, reCAPTCHA Enterprise évalue le niveau de risque de l'interaction utilisateur et renvoie un score compris entre 0,0 et 1,0, par incréments de 0,1. Le score 1,0 indique que l'interaction présente un risque faible et est très certainement légitime, tandis que 0,0 indique que l'interaction présente un risque élevé et peut être frauduleuse. App Check vous permet de configurer un seuil de risque d'application afin d'ajuster votre tolérance à ce risque.

Dans la plupart des cas d'utilisation, la valeur de seuil par défaut de 0,5 est recommandée. Si votre cas d'utilisation nécessite un ajustement, vous pouvez le configurer dans la section App Check de la console Firebase pour chacune de vos applications Web.

Détails

App Check utilise le seuil de risque d'application que vous avez configuré comme score reCAPTCHA Enterprise minimal requis pour qu'une interaction utilisateur soit considérée comme légitime. Tous les scores reCAPTCHA Enterprise strictement inférieurs au seuil que vous avez configuré seront rejetés. Lorsque vous ajustez le seuil de risque de votre application, tenez compte des points suivants :

  • Sur les 11 niveaux de score reCAPTCHA Enterprise possibles, seuls les quatre niveaux de score suivants sont disponibles avant que vous n'ajoutiez un compte de facturation Google Cloud à votre projet : 0,1, 0,3, 0,7 et 0,9. Pendant ce temps, App Check n'autorisera que les valeurs de seuil de risque d'application de 0,1, 0,3, 0,5, 0,7, et 0,9. Une valeur de seuil de risque d'application de 0,5 est toujours recommandée pour la plupart des cas d'utilisation.

    • Pour activer les 11 niveaux de score reCAPTCHA Enterprise, ajoutez un compte de facturation Google Cloud à votre projet. Pour ce faire, vous pouvez passer à la formule Blaze . Une fois cette opération effectuée, App Check vous permettra de configurer n'importe quelle valeur de seuil de risque d'application comprise entre 0,0 et 1,0, par incréments de 0,1.

  • Pour surveiller la distribution des scores reCAPTCHA Enterprise élevés et faibles pour votre application Web, accédez à la page reCAPTCHA Enterprise de la Google Cloud console et sélectionnez la clé de site utilisée par votre application Web.

  • Si vous avez une faible tolérance au risque d'application, déplacez le curseur vers la gauche pour augmenter le seuil de risque d'application.

    • Une valeur de 1,0 n'est pas recommandée, car ce paramètre peut également empêcher l'accès à des utilisateurs légitimes qui ne répondent pas à ce seuil de confiance élevé.

  • Si vous avez une haute tolérance au risque d'application, déplacez le curseur vers la droite pour diminuer le seuil de risque d'application.

    • Une valeur de 0,0 n'est pas recommandée, car ce paramètre désactive la protection contre les utilisations abusives.

Pour en savoir plus, consultez la documentation de reCAPTCHA Enterprise.

2. Ajouter la bibliothèque App Check à votre application

Ajoutez Firebase à votre application Web si ce n'est pas déjà fait. Veillez à importer la App Check bibliothèque.

3. Initialiser App Check

Ajoutez le code d'initialisation suivant à votre application avant d'accéder à des services Firebase. Vous devrez transmettre votre clé de site reCAPTCHA Enterprise, que vous avez créée dans la console Cloud, à activate().

Web

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

const app = initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to initializeAppCheck().
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(/* reCAPTCHA Enterprise site key */),
  isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
});

Web

firebase.initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to activate().
const appCheck = firebase.appCheck();
appCheck.activate(
  new firebase.appCheck.ReCaptchaEnterpriseProvider(
    /* reCAPTCHA Enterprise site key */
  ),
  true // Set to true to allow auto-refresh.
);

Étapes suivantes

Une fois la bibliothèque App Check installée dans votre application, déployez-la.

L'application cliente mise à jour commencera à envoyer des App Check jetons avec chaque requête adressée à Firebase, mais les produits Firebase n'exigeront pas que les jetons soient valides tant que vous n'aurez pas activé l'application dans la section App Check de la console Firebase.

Surveiller les métriques et activer l'application

Avant d'activer l'application, vous devez vous assurer que cela ne perturbera pas vos utilisateurs légitimes existants. En revanche, si vous constatez une utilisation suspecte des ressources de votre application, vous pouvez activer l'application plus tôt.

Pour vous aider à prendre cette décision, vous pouvez consulter les App Check métriques pour les services que vous utilisez :

Activer l'application App Check

Lorsque vous comprenez l'impact de App Check sur vos utilisateurs et que vous êtes prêt à continuer, vous pouvez activer l'application App Check :

Utiliser App Check dans des environnements de débogage

Si, après avoir enregistré votre application pour App Check, vous souhaitez exécuter votre application dans un environnement que App Check ne classerait normalement pas comme valide, par exemple localement pendant le développement ou à partir d'un environnement d'intégration continue (CI), vous pouvez créer une version de débogage de votre application qui utilise le fournisseur de débogage App Check au lieu d'un véritable fournisseur d'attestation.

Consultez Utiliser App Check avec le fournisseur de débogage dans les applications Web.

Remarque sur le coût

App Check crée une évaluation en votre nom pour valider le jeton de réponse de l'utilisateur chaque fois qu'un navigateur exécutant votre application Web actualise son jeton App Check. Votre projet sera facturé pour chaque évaluation créée au-delà du quota sans frais. Pour en savoir plus, consultez Tarifs de reCAPTCHA.

Par défaut, votre application Web actualise ce jeton deux fois par heure. Pour contrôler la fréquence à laquelle votre application actualise les jetons App Check (et donc la fréquence à laquelle de nouvelles évaluations sont créées), configurez leur durée de vie.