Utiliser App Check pour sécuriser le SDK Navigation pour iOS

Firebase App Check protège les appels de votre application à Google Maps Platform en bloquant le trafic provenant de sources autres que vos applications légitimes. Pour ce faire, elle demande à un fournisseur d'attestation tel que App Attest d'évaluer l'authenticité de l'application ou de l'appareil. Lorsque vous intégrez votre application à App Check, vous ajoutez une protection contre les requêtes malveillantes et non autorisées, ce qui protège votre facturation contre les débits non autorisés. App Check améliore également considérablement le signalement des perturbations en temps réel dans votre écosystème d'applications pour les flottes, ce qui profite à tous les conducteurs qui utilisent votre application. Pour en savoir plus, consultez Signalement des perturbations.

Important : App Check ne bloque pas le trafic non autorisé par défaut. Vous devez activer manuellement l'application après avoir vérifié les métriques de votre application (voir Étape 6 : Surveillez les requêtes de votre application et décidez de l'application).

Pourquoi utiliser App Check ?

App Check protège deux zones distinctes du SDK Navigation pour iOS : la fonctionnalité de navigation principale et le signalement des perturbations.

Navigation

App Check permet de bloquer les principales requêtes du SDK Navigation pour iOS provenant de sources malveillantes ou non autorisées. Cela vous est directement bénéfique, car cela protège votre projet contre la fraude à la facturation et l'épuisement des quotas.

Signaler une perturbation

App Check est fortement recommandé si votre application permet de signaler des perturbations en temps réel et de voter. L'activation d'App Check permet de fournir à vos conducteurs les itinéraires les plus précis en tenant compte de tous les commentaires en temps réel.

Pourquoi App Check est-il important pour les rapports ?

• Niveau de confiance élevé pour les fermetures : les événements ayant un impact sur les itinéraires, comme les fermetures de routes, peuvent modifier considérablement le comportement de routage pour tous les conducteurs. Pour protéger la carte contre le vandalisme, le spam ou les signalements inexacts, l'infrastructure de modération de Google pour les perturbations liées aux fermetures de routes s'appuie sur des signaux d'intégrité fiables des appareils et des applications.
• Comment App Check valide les signalements : les signalements et les votes des utilisateurs envoyés depuis le SDK Navigation pour iOS incluent le jeton App Check, qui est utilisé par le backend de Google pour valider la légitimité des commentaires, ce qui augmente leur niveau de fiabilité et permet de les évaluer pour déterminer leur impact sur la carte en direct.
• Impact de l'omission d'App Check : les rapports envoyés sans jeton App Check valide sont évalués selon un modèle de confiance plus faible et peuvent être traités uniquement comme des signaux silencieux. Cela signifie que vos utilisateurs peuvent toujours signaler des problèmes et voter, mais que leurs signalements sont moins susceptibles d'être visibles sur la carte ou d'affecter les itinéraires d'autres conducteurs. Ils devront également être validés.

App Check est-il adapté à mes besoins ?

App Check est recommandé dans la plupart des cas. Toutefois, il n'est pas nécessaire ni compatible dans les cas suivants :

• Applications privées ou expérimentales : si votre application n'est pas accessible au public, App Check n'est pas nécessaire.
• Appareils compromis : les fournisseurs d'attestation recommandés empêchent le SDK Navigation pour iOS de s'exécuter sur des appareils non fiables, tels que les téléphones rootés ou jailbreakés. Pour prendre en charge ces appareils, déployez un fournisseur d'attestation personnalisé.

Présentation des étapes d'implémentation

De manière générale, vous devez suivre les étapes suivantes pour intégrer votre application à App Check :

1. Ajoutez Firebase à votre application.
2. Ajoutez la bibliothèque App Check et initialisez App Check.
3. Ajoutez un fournisseur de jetons. Cette étape appelle le fournisseur d'attestation de votre choix pour vérifier l'intégrité de l'appareil ou de l'application.
4. Initialisez les API Navigation et App Check.
5. Activez le débogage. Cela est utile pendant le développement ou dans les environnements d'intégration continue (CI).
6. Surveillez les demandes de votre application avant d'activer l'application des règles. Vous pouvez ainsi appliquer App Check de manière fluide, sans perturber vos utilisateurs.

Éléments à prendre en compte lors de la planification d'une intégration App Check

• Quotas des fournisseurs d'attestation : les fournisseurs d'attestation que nous recommandons, DeviceCheck ou App Attest, sont soumis à des quotas et des limites définis par Apple.
• Latence au démarrage : dans la plupart des cas, vos utilisateurs ne rencontreront pas de latence lors d'une utilisation normale, car les jetons App Check sont mis en cache sur l'appareil. Le système actualise automatiquement les jetons App Check en arrière-plan avant leur expiration pour maintenir des performances fluides. Toutefois, si aucun jeton App Check valide n'est présent, les utilisateurs de votre application subiront une certaine latence au démarrage. Par exemple, cette latence se produit lors des démarrages à froid lorsqu'un jeton mis en cache a expiré ou est manquant.
• Valeur TTL du jeton : la valeur TTL (Time to Live) détermine la durée de validité du jeton App Check avant qu'il ne doive être actualisé. Vous pouvez configurer cette durée entre 30 minutes et 7 jours dans la console Firebase. Une durée d'une heure est recommandée comme base sécurisée, mais le SDK tente automatiquement d'actualiser l'arrière-plan à environ la moitié de la durée TTL. Pour obtenir des instructions détaillées sur la console, consultez la documentation Firebase App Check.

Intégrer votre application à App Check

Conditions préalables et exigences

• Une application avec le SDK Navigation pour iOS version 11.0 ou ultérieure installé.
• ID du bundle de l'application.
• L'ID de votre équipe, que vous trouverez dans l'onglet "Abonnement" de la console Apple Developer.
• Si vous prévoyez d'utiliser DeviceCheck, votre fichier de clé privée et votre ID de clé.
• Vous devez être le propriétaire de l'application dans la console Google Cloud.
• ID du projet de votre application dans la console Google Cloud.

Étape 1 : Ajouter Firebase à votre application

Suivez les instructions de la documentation pour les développeurs Firebase afin d'ajouter Firebase à votre application. Ajoutez votre fichier GoogleService-Info.plist, sans le modifier, au niveau racine de votre projet.

Dans votre fichier AppDelegate, importez les modules suivants :

Swift

import FirebaseCore
import FirebaseAppCheck
import GoogleNavigation

Objective-C

@import FirebaseCore;
@import FirebaseAppCheck;
@import GoogleNavigation;

Étape 2 : Ajoutez la bibliothèque App Check et initialisez App Check

Firebase fournit des instructions pour chaque fournisseur d'attestation par défaut. Ces instructions vous montrent comment configurer un projet Firebase et ajouter la bibliothèque App Check à votre application. Suivez les exemples de code fournis pour initialiser App Check.

1. Suivez les instructions Firebase pour ajouter la bibliothèque App Check :
   • Instructions pour App Attest
   • Instructions DeviceCheck
2. Initialisez App Check dans votre AppDelegate :
   • Si vous utilisez App Attest, créez une implémentation de AppCheckProviderFactory et enregistrez-la avant d'appeler FirebaseApp.configure() :

     Swift

     class YourAppCheckProviderFactory: NSObject, AppCheckProviderFactory {
         func createProvider(with app: FirebaseApp) -> AppCheckProvider? {
             return AppAttestProvider(app: app)
         }
     }
     // In application(_:didFinishLaunchingWithOptions:)
     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)
     FirebaseApp.configure()

     Objective-C

     #import <FirebaseCore/FirebaseCore.h>
     #import <FirebaseAppCheck/FirebaseAppCheck.h>
     
     @interface YourAppCheckProviderFactory : NSObject <FIRAppCheckProviderFactory>
     @end
     
     @implementation YourAppCheckProviderFactory
     - (nullable id<FIRAppCheckProvider>)createProviderWithApp:(FIRApp *)app {
         return [[FIRAppAttestProvider alloc] initWithApp:app];
     }
     @end
     
     // In application:didFinishLaunchingWithOptions:
     YourAppCheckProviderFactory *providerFactory = [[YourAppCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
     [FIRApp configure];

   • Si vous utilisez DeviceCheck, définissez la fabrique comme suit :

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

     FIRDeviceCheckProviderFactory *providerFactory = [[FIRDeviceCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];

Étape 3 : Ajoutez le fournisseur de jetons

Remarque : Si votre application utilise également d'autres SDK Google Maps Platform compatibles avec App Check (comme le SDK Places), vous pouvez utiliser la même configuration Firebase App Check, mais vous devez implémenter et enregistrer l'interface du fournisseur de jetons spécifique à chaque SDK.

Créez un fichier nommé AppCheckTokenProvider (ou, si vous utilisez Objective-C, deux fichiers nommés AppCheckTokenProvider.h et AppCheckTokenProvider.m) au niveau racine de votre application.

Cette classe doit se conformer au protocole GMSAppCheckTokenProvider et implémenter la méthode fetchAppCheckTokenWithCompletion.

Swift

import Foundation
import FirebaseAppCheck
import GoogleNavigation

class AppCheckTokenProvider: NSObject, GMSAppCheckTokenProvider {
    func fetchAppCheckToken(completion: @escaping (String?, Error?) -> Void) {
        AppCheck.appCheck().token(forcingRefresh: false) { token, error in
            if let error = error {
                print("App Check Error: \(error)")
                completion(nil, error)
                return
            }
            guard let token = token else {
                completion(nil, NSError(domain: "AppCheck", code: -1, userInfo: [NSLocalizedDescriptionKey: "Token is nil"]))
                return
            }
            print("App Check Token: \(token.token)")
            completion(token.token, nil)
        }
    }
}

Objective-C

// AppCheckTokenProvider.h
#import <Foundation/Foundation.h>
#import <GoogleNavigation/GoogleNavigation.h>

NS_ASSUME_NONNULL_BEGIN

@interface AppCheckTokenProvider : NSObject <GMSAppCheckTokenProvider>
@end

NS_ASSUME_NONNULL_END

// AppCheckTokenProvider.m
#import "AppCheckTokenProvider.h"
#import <FirebaseAppCheck/FirebaseAppCheck.h>

@implementation AppCheckTokenProvider
- (void)fetchAppCheckTokenWithCompletion:(void (^)(NSString * _Nullable token, NSError * _Nullable error))completion {
    [[FIRAppCheck appCheck] tokenForcingRefresh:NO
                                     completion:^(FIRAppCheckToken * _Nullable token, NSError * _Nullable error) {
        if (token) {
            completion(token.token, nil);
        } else {
            completion(nil, error);
        }
    }];
}
@end

Étape 4 : Initialisez les API Navigation et App Check

Initialisez le SDK Navigation pour iOS et enregistrez votre instance de fournisseur de jetons sur GMSServices :

Swift

// In application(_:didFinishLaunchingWithOptions:)
GMSServices.provideAPIKey("YOUR_API_KEY")

// Register your App Check token provider before initializing Navigation SDK for iOS
GMSServices.appCheckTokenProvider = AppCheckTokenProvider()

Objective-C

// In application:didFinishLaunchingWithOptions:
[GMSServices provideAPIKey:@"YOUR_API_KEY"];

// Register your App Check token provider before initializing Navigation SDK for iOS
GMSServices.appCheckTokenProvider = [[AppCheckTokenProvider alloc] init];

Étape 5 : Activez le débogage (facultatif)

Une fois App Check appliqué au SDK Navigation pour iOS, les fonctionnalités de votre application qui dépendent du SDK Navigation pour iOS ne s'exécuteront pas dans un simulateur ni dans un environnement d'intégration continue (CI), car ces environnements ne sont pas considérés comme des appareils valides. Pour exécuter votre application dans ces environnements pendant le développement et les tests, vous devez créer une version de débogage de votre application qui utilise le fournisseur de débogage App Check au lieu d'un fournisseur d'attestation de production.

1. Configurez la fabrique de fournisseurs de débogage dans votre AppDelegate :

   Swift

   #if targetEnvironment(simulator)
   let providerFactory = AppCheckDebugProviderFactory()
   #else
   let providerFactory = YourAppCheckProviderFactory()
   #endif
   AppCheck.setAppCheckProviderFactory(providerFactory)

   Objective-C

   #if TARGET_OS_SIMULATOR
   id<FIRAppCheckProviderFactory> providerFactory = [[FIRAppCheckDebugProviderFactory alloc] init];
   #else
   id<FIRAppCheckProviderFactory> providerFactory = [[YourAppCheckProviderFactory alloc] init];
   #endif
   [FIRAppCheck setAppCheckProviderFactory:providerFactory];

2. Activez la journalisation dans votre projet Xcode, lancez l'application et recherchez le jeton de débogage local dans le journal de la console.
3. Copiez et ajoutez ce jeton de débogage à la console Firebase. Pour en savoir plus, consultez la documentation sur le fournisseur de débogage Firebase App Check.

Étape 6 : Surveillez les demandes concernant votre application et décidez de l'application des règles

Remarque : L'application des règles n'est pas strictement nécessaire pour que les signalements de perturbations en temps réel bénéficient de la validation de l'intégrité des appareils. Toutefois, une protection complète contre la fraude à la facturation, l'usurpation d'identité et l'utilisation abusive des quotas nécessite l'activation de l'application des règles au niveau du projet.

Avant d'activer la mesure d'application, surveillez les requêtes de votre application pour vous assurer de ne pas perturber les utilisateurs légitimes.

1. Accédez à l'écran des métriques App Check dans la console Firebase pour afficher le pourcentage de trafic validé par rapport au trafic non validé.
2. Une fois que vous êtes sûr que la majorité de votre trafic est vérifiée et que les utilisateurs légitimes sont passés à une version de votre application contenant votre implémentation App Check, activez l'application.
3. Une fois l'application activée, App Check refusera tout le trafic sans jeton App Check valide.