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

La compatibilité avec App Check pour le SDK Navigation pour iOS sera déployée au cours des prochains jours. Si vous ne voyez pas encore cette fonctionnalité dans la console Firebase, réessayez dans quelques jours.

Firebase App Check protège les appels de votre application vers Google Maps Platform en bloquant le trafic provenant de sources autres que vos applications légitimes. Pour ce faire, il 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 frais non autorisés. App Check améliore également considérablement la création de rapports sur les perturbations en temps réel dans l'écosystème de votre application de flotte, ce qui profite à tous les conducteurs qui l'utilisent. Pour en savoir plus, consultez Création de rapports sur les 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 : Surveiller les requêtes de votre application et décider 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 la création de rapports sur les perturbations.

Navigation

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

Création de rapports sur les perturbations

App Check est fortement recommandé si votre application est compatible avec la création de rapports sur les perturbations et les fonctionnalités de vote en temps réel. L'activation d'App Check permet de s'assurer que vos conducteurs bénéficient des itinéraires les plus précis, en tenant compte de tous les commentaires en temps réel.

Pourquoi App Check est-il important pour la création de rapports ?

• Le niveau de confiance élevé pour les fermetures : les événements ayant un impact sur l'itinéraire, tels que 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 rapports inexacts potentiels, l'infrastructure de modération de Google pour les perturbations liées aux fermetures de routes repose sur des signaux d'intégrité de l'appareil et de l'application forts.
• Comment App Check valide les rapports : les rapports 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 son niveau de confiance et permet de l'évaluer pour son impact sur la carte en direct.
• L'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, même si vos utilisateurs peuvent toujours signaler et voter, leurs rapports sont moins susceptibles d'être visibles sur la carte ou d'affecter les itinéraires des autres conducteurs, et qu'ils nécessiteront une validation supplémentaire.

App Check est-il adapté à mes besoins ?

App Check est recommandé dans la plupart des cas. Toutefois, il n'est pas nécessaire ou n'est pas 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

En règle générale, vous devez suivre ces étapes 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 lors du développement ou dans les environnements d'intégration continue (CI).
6. Surveillez les requêtes de votre application avant d'activer l'application. De cette façon, vous appliquez App Check de manière transparente 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 rencontreront 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.
• TTL des jetons : la valeur TTL (Time To Live) détermine la durée de validité du jeton App Check avant qu'il ne soit nécessaire de l'actualiser. 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 de référence sécurisée, mais le SDK tente automatiquement d'actualiser en arrière-plan environ la moitié de la valeur TTL. Pour obtenir des instructions détaillées dans la console, consultez la documentation Firebase App Check.

Intégrer votre application à App Check

Prérequis et exigences

• Une application avec le SDK Navigation pour iOS version 11.0 ou ultérieure installée.
• L'ID du bundle de l'application.
• Votre ID d'équipe dans l'onglet "Membership" (Abonnement) de votre 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.
• L'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 GoogleService-Info.plist fichier, non modifié, 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 : Ajouter la bibliothèque App Check et initialiser 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 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 à la place, définissez la fabrique à l'aide de la commande suivante :

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

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

Étape 3 : Ajouter le fournisseur de jetons

Remarque : Si votre application utilise également d'autres SDK Google Maps Platform compatibles avec App Check (tels que 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 être conforme 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 : Initialiser les API Navigation et App Check

Initialisez le SDK Navigation pour iOS (à l'aide de GMSServices) et enregistrez votre instance de fournisseur de jetons en convertissant le handle de services opaques partagé en GMSServices :

Swift

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

// Register your App Check token provider before initializing Navigation SDK for iOS
if let services = GMSServices.sharedServices() as? GMSServices {
    services.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 *)[GMSServices sharedServices]).appCheckTokenProvider = [[AppCheckTokenProvider alloc] init];

Étape 5 : Activer 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 à partir d'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 lors du développement et des 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 l'usine du fournisseur 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 du fournisseur de débogage Firebase App Check.

Étape 6 : Surveiller les requêtes de votre application et décider de l'application

Remarque : L'application n'est pas strictement requise pour que les rapports sur les perturbations en temps réel bénéficient de la vérification de l'intégrité de l'appareil. 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 au niveau du projet.

Avant d'activer la mesure d'application, surveillez les requêtes de votre application pour vous assurer que vous ne perturbez pas 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 validé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.