Usar o App Check para proteger o SDK Navigation para iOS

O Firebase App Check protege as chamadas do seu app para a Plataforma Google Maps bloqueando o tráfego que vem de fontes diferentes dos seus apps legítimos. Isso é feito solicitando uma avaliação da autenticidade do app ou do dispositivo a um provedor de atestado, como o App Attest. Ao integrar seu app com o App Check, você adiciona proteção contra solicitações maliciosas e não autorizadas, o que protege seu faturamento contra cobranças indevidas. O App Check também melhora significativamente os relatórios de interrupção em tempo real no ecossistema de apps da sua frota, beneficiando todos os motoristas que usam seu app. Para mais informações, consulte Relatórios de interrupção.

Importante:o App Check não bloqueia o tráfego não autorizado por padrão. É necessário ativar a aplicação manualmente depois de verificar as métricas do app. Consulte Etapa 6: monitorar as solicitações do app e decidir sobre a aplicação.

Por que usar o App Check?

O App Check protege duas áreas distintas do SDK Navigation para iOS: a funcionalidade principal de navegação e a denúncia de interrupções.

Navegação

O App Check ajuda a bloquear solicitações principais do SDK Navigation para iOS de fontes maliciosas ou não autorizadas. Isso beneficia você diretamente, protegendo seu projeto contra fraude de faturamento e esgotamento de cota.

Denúncia de interrupção

O App Check é altamente recomendado se o app oferece suporte a recursos de votação e relatórios de interrupção em tempo real. Ao ativar o App Check, você garante que os motoristas recebam as rotas mais precisas, considerando todos os feedbacks em tempo real.

Por que o App Check é importante para a geração de relatórios:

• Alto nível de confiança para interdições:eventos que afetam a rota, como interdições de vias, podem alterar significativamente o comportamento de roteamento para todos os motoristas. Para proteger o mapa contra possível vandalismo, spam ou denúncias imprecisas, a infraestrutura de moderação do Google para interrupções de vias depende de indicadores fortes de integridade do dispositivo e do app.
• Como o App Check valida os relatórios:os relatórios e votos dos usuários enviados pelo SDK Navigation para iOS incluem o token do App Check, que é usado pelo back-end do Google para validar a legitimidade do feedback, aumentando o nível de confiança e permitindo que ele seja avaliado quanto ao impacto no mapa em tempo real.
• O impacto de omitir o App Check:os relatórios enviados sem um token válido do App Check são avaliados em um modelo de confiança mais baixa e podem ser processados apenas como indicadores silenciosos. Isso significa que, embora os usuários ainda possam fazer alertas e votar, é menos provável que eles apareçam no mapa ou afetem as rotas de outros motoristas, e eles vão precisar de mais validação.

O App Check é adequado para mim?

O App Check é recomendado na maioria dos casos, mas não é necessário ou não tem suporte nos seguintes cenários:

• Apps particulares ou experimentais:se o app não estiver acessível ao público, não será necessário usar o App Check.
• Dispositivos comprometidos:os provedores de atestado recomendados impedem que o SDK Navigation para iOS seja executado em dispositivos não confiáveis, como smartphones com acesso root ou jailbreak. Para oferecer suporte a esses dispositivos, implante um provedor de atestado personalizado.

Visão geral das etapas de implementação

Em um nível alto, siga estas etapas para integrar seu app ao App Check:

1. Adicione o Firebase ao aplicativo.
2. Adicione a biblioteca do App Check e inicialize o serviço.
3. Adicione um provedor de token. Essa etapa invoca o provedor de atestado escolhido para verificar a integridade do dispositivo ou do app.
4. Inicialize as APIs Navigation e App Check.
5. Ative a depuração. Isso é útil durante o desenvolvimento ou em ambientes de integração contínua (CI).
6. Monitore as solicitações do app antes de ativar a aplicação. Assim, você aplica o App Check sem interromper os usuários.

Considerações ao planejar uma integração do App Check

• Cotas de provedores de atestado:os provedores de atestado que recomendamos, DeviceCheck ou App Attest, estão sujeitos a cotas e limitações definidas pela Apple.
• Latência de inicialização:na maioria das situações, os usuários não vão sentir latência durante o uso normal, porque os tokens do App Check são armazenados em cache no dispositivo. O sistema atualiza automaticamente os tokens do App Check em segundo plano antes do vencimento para manter o desempenho perfeito. No entanto, se um token do App Check válido não estiver presente, os usuários do app vão ter alguma latência na inicialização. Por exemplo, essa latência ocorre durante inicializações a frio quando um token armazenado em cache expira ou está ausente.
• TTL do token:o time to live (TTL) determina por quanto tempo o token do App Check é válido antes de precisar ser atualizado. É possível configurar essa duração de 30 minutos a 7 dias no console do Firebase. Uma duração de uma hora é recomendada como um valor de referência seguro, mas o SDK tenta atualizações em segundo plano automaticamente em aproximadamente metade da duração do TTL. Para instruções detalhadas no console, consulte a documentação do Firebase App Check.

Integrar seu app ao App Check

Pré-requisitos e requisitos

• Um app com o SDK Navigation para iOS versão 11.0 ou mais recente instalado.
• O ID do pacote do app.
• O ID da equipe na guia "Membership" do console de desenvolvedor da Apple.
• Se você planeja usar o DeviceCheck, o arquivo de chave privada e o ID da chave.
• Você precisa ser o proprietário do app no console do Google Cloud.
• O ID do projeto do seu app no console do Google Cloud.

Etapa 1: adicionar o Firebase ao app

Siga as instruções na documentação para desenvolvedores do Firebase e adicione o Firebase ao seu app. Adicione o arquivo GoogleService-Info.plist, sem modificações, ao nível raiz do projeto.

No arquivo AppDelegate, importe os seguintes módulos:

Swift

import FirebaseCore
import FirebaseAppCheck
import GoogleNavigation

Objective-C

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

Etapa 2: adicionar a biblioteca do App Check e inicializar o App Check

O Firebase oferece instruções para cada provedor de atestado padrão. Estas instruções mostram como configurar um projeto do Firebase e adicionar a biblioteca do App Check ao seu app. Siga os exemplos de código fornecidos para inicializar o App Check.

1. Siga as instruções do Firebase para adicionar a biblioteca do App Check:
   • Instruções do App Attest.
   • Instruções do DeviceCheck.
2. Inicialize o App Check no seu AppDelegate:
   • Se você estiver usando o App Attest, crie uma implementação de AppCheckProviderFactory e registre-a antes de chamar 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];

   • Se você estiver usando o DeviceCheck, defina a fábrica usando o seguinte:

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

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

Etapa 3: adicionar o provedor de token

Observação:se o app também usa outros SDKs da Plataforma Google Maps compatíveis com o App Check (como o SDK do Places), você pode usar a mesma configuração do Firebase App Check, mas precisa implementar e registrar a interface do provedor de token específica para cada SDK.

Crie um arquivo chamado AppCheckTokenProvider (ou, se você estiver usando Objective-C, dois arquivos chamados AppCheckTokenProvider.h e AppCheckTokenProvider.m) no nível raiz do app.

Essa classe precisa estar em conformidade com o protocolo GMSAppCheckTokenProvider e implementar o método 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

Etapa 4: inicializar as APIs Navigation e App Check

Inicialize o SDK Navigation para iOS e registre sua instância de provedor de token em 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];

Etapa 5: ativar a depuração (opcional)

Depois que o App Check for aplicado ao SDK Navigation para iOS, os recursos do seu app que dependem dele não serão executados em um simulador ou em um ambiente de integração contínua (CI), porque esses ambientes não se qualificam como dispositivos válidos. Para executar o app nesses ambientes durante o desenvolvimento e os testes, crie um build de depuração do app que use o provedor de depuração do App Check em vez de um provedor de atestado de produção.

1. Configure a fábrica do provedor de depuração em 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. Ative o registro em log no projeto do Xcode, inicie o app e localize o token de depuração local no registro do console.
3. Copie e adicione esse token de depuração ao console do Firebase. Para mais detalhes, consulte a documentação do provedor de depuração do Firebase App Check.

Etapa 6: monitorar as solicitações de apps e decidir sobre a aplicação

Observação:a aplicação não é estritamente necessária para que os relatórios de interrupção em tempo real se beneficiem da verificação de integridade do dispositivo. No entanto, a proteção total contra fraude de faturamento, spoofing e abuso de cota depende da ativação da aplicação no nível do projeto.

Antes de ativar a restrição, monitore as solicitações do app para garantir que você não vai prejudicar usuários legítimos.

1. Acesse a tela de métricas do App Check no console do Firebase para conferir a porcentagem de tráfego verificado e não verificado.
2. Quando você tiver certeza de que a maior parte do tráfego é de usuários verificados e legítimos que atualizaram para uma versão do app com a implementação do App Check, ative a aplicação obrigatória.
3. Quando a aplicação estiver ativada, o App Check vai rejeitar todo o tráfego sem um token válido.