Firebase App Check para plataformas da Apple

1. Introdução

O Firebase App Check ajuda a proteger seus recursos de back-end contra abusos, como fraude de faturamento e phishing, garantindo que as solicitações venham de apps e dispositivos legítimos. Ele funciona com os serviços do Firebase e com seus próprios serviços de back-end para manter os recursos seguros.

Saiba mais sobre o Firebase App Check na documentação do Firebase.

O App Check usa serviços específicos da plataforma para verificar a integridade de um app e/ou dispositivo. Esses serviços são chamados de provedores de atestado. Um desses provedores é o serviço App Attest da Apple, que o App Check pode usar para verificar a autenticidade de apps e dispositivos Apple.

O que você vai criar

Neste codelab, você vai adicionar e aplicar o App Check em um aplicativo de exemplo para proteger o Realtime Database do projeto contra acesso de apps e dispositivos ilegítimos.

O que você aprenderá

• Como adicionar o Firebase App Check a um app.
• Como instalar diferentes provedores de declaração do App Check do Firebase.
• Como configurar o App Attest para seu app.
• Como configurar o provedor de atestado de depuração para testar seu app em simuladores durante o desenvolvimento.

O que é necessário

• Xcode 13.3.1 ou versões mais recentes
• Uma conta de desenvolvedor da Apple que permite criar novos identificadores de apps
• Um dispositivo iOS/iPadOS compatível com o App Attest. Saiba mais sobre a disponibilidade da API App Attest.

Observação:ainda é possível concluir este codelab sem uma conta de desenvolvedor da Apple e um dispositivo qualificado. Nesse caso, só será possível executar o app em um simulador com um provedor de depuração do Firebase App Check.

2. Baixar o projeto inicial

O repositório de início rápido do Firebase para iOS (link em inglês) contém apps de exemplo para demonstrar diferentes produtos do Firebase. Você vai usar o app de início rápido do banco de dados do Firebase para SwiftUI como base para este codelab.

Clone o repositório de início rápido do Firebase para iOS na linha de comando:

git clone https://github.com/firebase/quickstart-ios.git
cd quickstart-ios

Abra o projeto do app de início rápido do Realtime Database SwiftUI no Xcode:

cd database/DatabaseExampleSwiftUI/DatabaseExample
xed .

3. Adicionar o App Check ao seu app

1. Aguarde o Swift Package Manager resolver as dependências do projeto.
2. Abra a guia Geral do destino do app DatabaseExample (iOS). Em seguida, na seção Frameworks, bibliotecas e conteúdo incorporado, clique no botão +.
3. Selecione para adicionar FirebaseAppCheck.

4. Criar e instalar a fábrica de provedores do App Check

1. No grupo de arquivos Shared, adicione um novo grupo chamado AppCheck.
2. Dentro desse grupo, crie uma classe de fábrica em um arquivo separado, por exemplo, MyAppCheckProviderFactory.swift, e adicione-o à meta DatabaseExample (iOS):

   import Firebase
   
   class MyAppCheckProviderFactory: NSObject, AppCheckProviderFactory {
     func createProvider(with app: FirebaseApp) -> AppCheckProvider? {
       #if targetEnvironment(simulator)
         // App Attest is not available on simulators.
         // Use a debug provider.
         return AppCheckDebugProvider(app: app)
       #else
         // Use App Attest provider on real devices.
         return AppAttestProvider(app: app)
       #endif
     }
   }
   

3. Em seguida, no DatabaseExampleApp.swift, importe FirebaseAppCheck e defina uma instância da classe MyAppCheckProviderFactory como a fábrica do provedor do App Check.

   import SwiftUI
   import FirebaseCore
   import FirebaseAppCheck
   
   @main
   struct DatabaseExampleApp: App {
     init() {
       // Set an instance of MyAppCheckProviderFactory as an App Check
       // provider factory before configuring Firebase.
       AppCheck.setAppCheckProviderFactory(MyAppCheckProviderFactory())
       FirebaseApp.configure()
     }
     ...
   }
   

5. Criar e configurar um projeto do Firebase

Para usar o App Check no seu projeto iOS, siga estas etapas no Console do Firebase:

• Configure um projeto do Firebase.
• Adicione o app iOS ao projeto do Firebase.
• Configure o Firebase Authentication.
• Inicialize a instância do Realtime Database que você vai proteger.
• Configure o App Check.

Criar um projeto

Primeiro, crie um projeto do Firebase.

1. No console do Firebase, selecione Adicionar projeto.
2. Nomeie o projeto App Check Codelab
3. Clique em Continuar.
4. Desative o Google Analytics para o projeto e clique em Criar projeto.

Criar uma instância do Realtime Database

Agora, navegue até a seção Realtime Database do console do Firebase.

1. Clique no botão Criar banco de dados para iniciar o fluxo de trabalho de criação do banco de dados.
2. Mantenha o local padrão (us-central1) do banco de dados inalterado e clique em Próxima.
3. Verifique se o Modo bloqueado está selecionado e clique no botão Ativar para ativar as regras de segurança do banco de dados.
4. Navegue até a guia Regras do navegador do Realtime Database e substitua as regras padrão pelo seguinte:

   {
       "rules": {
           // User profiles are only readable/writable by the user who owns it
           "users": {
               "$UID": {
                   ".read": "auth.uid == $UID",
                   ".write": "auth.uid == $UID"
               }
           },
           // Posts can be read by anyone but only written by logged-in users.
           "posts": {
               ".read": true,
               ".write": "auth.uid != null",
               "$POSTID": {
                   // UID must match logged in user and is fixed once set
                   "uid": {
                       ".validate": "(data.exists() && data.val() == newData.val()) || newData.val() == auth.uid"
                   },
                   // User can only update own stars
                   "stars": {
                       "$UID": {
                           ".validate": "auth.uid == $UID"
                       }
                   }
               }
           },
           // User posts can be read by anyone but only written by the user that owns it,
           // and with a matching UID
           "user-posts": {
               ".read": true,
               "$UID": {
                   "$POSTID": {
                       ".write": "auth.uid == $UID",
                       ".validate": "data.exists() || newData.child('uid').val() == auth.uid"
                   }
               }
           },
           // Comments can be read by anyone but only written by a logged in user
           "post-comments": {
               ".read": true,
               ".write": "auth.uid != null",
               "$POSTID": {
                   "$COMMENTID": {
                       // UID must match logged in user and is fixed once set
                       "uid": {
                           ".validate": "(data.exists() && data.val() == newData.val()) || newData.val() == auth.uid"
                       }
                   }
               }
           }
       }
   }
   

5. Clique no botão Publicar para ativar as regras de segurança atualizadas.

Preparar seu app iOS para ser conectado ao Firebase

Para executar o app de exemplo em um dispositivo físico, adicione o projeto à sua equipe de desenvolvimento para que o Xcode possa gerenciar o perfil de provisionamento necessário. Siga estas etapas para adicionar o app de exemplo à sua conta de desenvolvedor:

1. No Xcode, selecione o projeto DatabaseExample no navegador de projetos.
2. Selecione o destino DatabaseExample (iOS) e abra a guia Assinatura e recursos.
3. Você vai encontrar uma mensagem de erro dizendo "A assinatura de DatabaseExample (iOS) exige uma equipe de desenvolvimento".
4. Atualize o identificador do pacote para um identificador exclusivo. A maneira mais fácil de fazer isso é usando o nome de domínio reverso do seu site, por exemplo, com.acme.samples.firebase.quickstart.DatabaseExample. Não use esse ID. Escolha um ID exclusivo.
5. Selecione sua equipe de desenvolvimento.
6. Você vai saber que tudo deu certo quando o Xcode mostrar "Provisioning Profile: Xcode Managed Profile" e um pequeno ícone de informações ao lado desse rótulo. Clique nesse ícone para mostrar mais detalhes sobre o perfil de provisionamento.

Importante:se você não fornecer um identificador de pacote exclusivo, o projeto não será registrado no portal de desenvolvedores da Apple. Somente apps registrados podem ser executados em um dispositivo físico.

Conectar seu app iOS

Para uma explicação detalhada sobre como conectar seu app, confira a documentação sobre como adicionar o Firebase ao seu projeto iOS. Para começar, siga estas etapas principais no Console do Firebase:

1. Na tela Visão geral do projeto do novo projeto, clique no botão + Adicionar app e depois no ícone iOS+ para adicionar um novo app iOS ao projeto do Firebase.
2. Insira o ID do pacote do seu app (use o que você definiu na seção anterior, como com.acme.samples.firebase.quickstart.DatabaseExample. Lembre-se de que esse precisa ser um identificador exclusivo).
3. Clique em Registrar app.
4. O Firebase gera um arquivo GoogleService-Info.plist que contém todos os metadados necessários do Firebase para seu app.
5. Clique em Fazer o download do GoogleService-Info.plist para baixar o arquivo.
6. No Xcode, você vai ver que o projeto já tem um arquivo chamado GoogleService-Info.plist. Exclua esse arquivo primeiro. Ele será substituído pelo arquivo do seu projeto do Firebase na próxima etapa.
7. Copie o arquivo GoogleService-Info.plist que você baixou na etapa anterior para a pasta raiz do seu projeto Xcode e adicione-o ao destino DatabaseExample (iOS). Verifique se ele está nomeado como GoogleService-Info.plist.
8. Clique nas etapas restantes do fluxo de registro. Como o projeto de exemplo já está configurado corretamente, não é necessário fazer mudanças no código.

Configure o Firebase Authentication

Ufa. Já fizemos bastante configuração, mas aguente firme! Se você não conhece o Firebase, já viu partes essenciais de um fluxo de trabalho com que vai se familiarizar em breve.

Agora, você vai configurar o Firebase Authentication para este app.

Ativar o provedor de login por e-mail/senha de autenticação

1. Ainda no console do Firebase, abra a seção Autenticação.
2. Clique em Começar para configurar o Firebase Authentication no seu projeto.
3. Selecione a guia Método de login.
4. Selecione E-mail/senha na seção Provedores nativos.
5. Ative a opção E-mail/senha e clique em Salvar.

Adicionar um usuário de teste

1. Abra a guia Usuários da seção Autenticação.
2. Clique em Adicionar usuário.
3. Especifique um e-mail e uma senha para o usuário de teste e clique em Adicionar usuário.

Faça um teste

Volte para o Xcode e execute o aplicativo no simulador do iOS. Faça login com o e-mail e a senha do usuário de teste que você acabou de criar. Depois de fazer login, crie uma postagem, publique um comentário em uma postagem e marque/desmarque postagens com estrela.

6. Configurar um provedor de declaração do App Attest

Nesta etapa, você vai configurar o App Check para usar o provedor App Attest no console do Firebase.

1. No console do Firebase, navegue até a seção App Check.
2. Clique em Começar.
3. Na guia Apps, clique no seu app para expandir os detalhes.
4. Clique em App Attest para configurar o App Attest e insira o ID da equipe da sua conta de desenvolvedor da Apple. Você pode encontrar essa informação na seção Assinatura do portal de desenvolvedores da Apple:
5. Clique em Salvar.

Assim, você tem um projeto do Firebase funcionando e conectado ao novo app, e o App Check está ativado.

Agora você já pode configurar nosso serviço de atestado específico. Para mais informações sobre esse fluxo de trabalho, consulte Ativar o App Check com o App Attest no iOS.

7. Configurar o App Attest para seu aplicativo

Agora é hora de usar o SDK do App Check do Firebase e implementar um código do cliente.

Primeiro, configure o projeto do Xcode para que o SDK possa usar a API App Attest da Apple e garantir que as solicitações enviadas do seu app venham de instâncias legítimas dele.

1. Adicione o recurso App Attest ao destino do app no projeto Xcode:
2. abra a guia Assinatura e recursos nas configurações de destino do app
3. clique no botão +
4. Na caixa de diálogo, encontre e selecione o recurso App Attest .
5. Um arquivo DatabaseExample (iOS).entitlements vai aparecer na pasta raiz do seu projeto Xcode depois de realizar a etapa anterior.
6. No arquivo DatabaseExample (iOS).entitlements, mude o valor da chave App Attest Environment para production..

Importante:no momento, o Firebase App Check só é compatível com o provedor App Attest quando ele está no modo de produção. Por padrão, quando você executa o app no Xcode, o App Attest é executado no sandbox ou no modo de desenvolvimento. Portanto, siga as etapas acima para mudar o modo do App Attest. Caso contrário, o Firebase App Check não vai conseguir realizar o atestado do dispositivo.

Depois de concluir essas etapas e iniciar o app em um dispositivo iOS físico (iPhone/iPad), ele ainda poderá acessar o Realtime Database. Em uma etapa posterior, você vai aplicar o App Check, que vai bloquear solicitações enviadas de apps e dispositivos ilegítimos.

Para saber mais sobre esse fluxo de trabalho, consulte Ativar o App Check com o App Attest no iOS.

8. Configurar um provedor de atestado de depuração para o simulador do iOS

O provedor Firebase App Check Debug permite testar aplicativos com a aplicação do Firebase App Check em ambientes não confiáveis, incluindo o simulador do iOS, durante o processo de desenvolvimento. Em seguida, configure o provedor de depuração.

Aviso: o provedor de depuração permite o acesso aos recursos do Firebase em dispositivos não verificados. Você nunca deve usar o provedor de depuração em builds de produção do seu app. Além disso, tenha cuidado para não vazar seu token de depuração.

Instalar o provedor de depuração do Firebase no seu app

Opção 1: criar condicionalmente uma instância do provedor de depuração na sua fábrica

Você fez a maior parte disso ao criar a fábrica de provedores do App Check. Nesta etapa, você vai adicionar o registro do segredo de depuração local gerado pelo provedor de depuração. Assim, será possível registrar essa instância do app no console do Firebase para fins de depuração.

Atualize MyAppCheckProviderFactory.swift com o seguinte código:

import Firebase

class MyAppCheckProviderFactory: NSObject, AppCheckProviderFactory {
  func createProvider(with app: FirebaseApp) -> AppCheckProvider? {
#if targetEnvironment(simulator)
    // App Attest is not available on simulators.
    // Use a debug provider.
    let provider = AppCheckDebugProvider(app: app)

    // Print only locally generated token to avoid a valid token leak on CI.
    print("Firebase App Check debug token: \(provider?.localDebugToken() ?? "" )")

    return provider
#else
    // Use App Attest provider on real devices.
    return AppAttestProvider(app: app)
#endif
  }
}

Essa abordagem oferece mais flexibilidade para configurar o App Check dependendo do ambiente. Por exemplo, você pode usar outros provedores de comprovação, como o DeviceCheck ou um provedor personalizado em versões do SO em que o App Attest não está disponível. Veja um exemplo abaixo.

import Firebase

class MyAppCheckProviderFactory: NSObject, AppCheckProviderFactory {
  func createProvider(with app: FirebaseApp) -> AppCheckProvider? {
      #if targetEnvironment(simulator)
      // App Attest is not available on simulators.
      // Use a debug provider.
      let provider = AppCheckDebugProvider(app: app)

      // Print only locally generated token to avoid a valid token leak on CI.
      print("Firebase App Check debug token: \(provider?.localDebugToken() ?? "" )")

      return provider
      #else
      if #available(iOS 14.0, *) {
        // Use App Attest provider on real devices.
        return AppAttestProvider(app: app)
      } else {
        return DeviceCheckProvider(app: app)
      }
      #endif
  }
}

Opção 2: instalar o AppCheckDebugProviderFactory

Em casos mais simples, é possível instalar temporária ou condicionalmente o AppCheckDebugProviderFactory antes de configurar a instância do aplicativo do Firebase:

init() {
#if targetEnvironment(simulator)
  let providerFactory = AppCheckDebugProviderFactory()
#else
  let providerFactory = MyAppCheckProviderFactory()
#endif

  AppCheck.setAppCheckProviderFactory(providerFactory)

  FirebaseApp.configure()
}

Isso vai economizar algumas linhas de código ao criar sua própria fábrica de provedores do App Check.

Registrar o segredo de depuração no console do Firebase

Extrair o secret de depuração do simulador do iOS

1. Se você escolheu instalar AppCheckDebugProviderFactory (opção 2 acima), adicione -FIRDebugEnabled aos argumentos de inicialização do app para ativar a geração de registros de depuração:
2. Executar o app em um simulador
3. Encontre o secret de depuração no console do Xcode. Use o filtro do console para encontrar mais rápido:

Observação:o segredo de depuração é gerado para seu simulador no primeiro lançamento do app e armazenado nos padrões do usuário. Se você remover o app, redefinir o simulador ou usar outro simulador, um novo secret de depuração será gerado. Registre o novo secret de depuração.

Registrar o segredo de depuração

1. De volta ao console do Firebase, acesse a seção App Check.
2. Na guia Apps, clique no seu app para expandir os detalhes.
3. No menu flutuante, selecione Gerenciar tokens de depuração:
4. Adicione o segredo que você copiou do console do Xcode e clique em Salvar .

Depois dessas etapas, você poderá usar o app no simulador mesmo com a verificação de app ativada.

Observação:o provedor de depuração foi projetado especificamente para ajudar a evitar vazamentos de segredos de depuração. Com a abordagem atual, não é necessário armazenar o segredo de depuração no código-fonte.

Mais detalhes sobre esse fluxo podem ser encontrados na documentação. Consulte Usar o App Check com o provedor de depuração no iOS.

9. Ativar a aplicação do App Check no Firebase Realtime Database

Por enquanto, nosso app declara um AppCheckProviderFactory que retorna um AppAttestProvider para dispositivos reais. Ao ser executado em um dispositivo físico, o app vai realizar o atestado e enviar os resultados ao back-end do Firebase. No entanto, o back-end do Firebase ainda aceita solicitações de qualquer dispositivo, do simulador do iOS, de um script etc. Esse modo é útil quando você ainda tem usuários com uma versão antiga do app sem o App Check e não quer aplicar verificações de acesso ainda.

Agora, é necessário ativar a aplicação do App Check para garantir que o app do Firebase só possa ser acessado em dispositivos legítimos. As versões antigas do app sem integração do App Check vão parar de funcionar quando você ativar a aplicação no projeto do Firebase.

Atenção:em um aplicativo ativo com usuários, não ative a aplicação, a menos que você tenha certeza de que os usuários migraram para a nova versão do app que pode passar pelo atestado do App Check. Todos os usuários reais que usam o app antigo sem o App Check integrado vão perder o acesso ao Realtime Database, mesmo que usem dispositivos legítimos.

Para que a transição seja tranquila para os usuários, geralmente é necessário lançar o app integrado ao App Check com antecedência e manter o projeto do Firebase sem aplicação por um tempo. As métricas de solicitação do App Check disponíveis no console do Firebase podem ajudar você a decidir quando é o momento certo de ativar a aplicação.

1. Na seção App Check do Console do Firebase, clique em Realtime Database para abrir os detalhes.
2. Clique em Aplicar.

3. Leia as informações na caixa de diálogo de confirmação e clique em Aplicar.

Depois de concluir essas etapas, apenas apps legítimos poderão acessar o banco de dados. Todos os outros apps serão bloqueados.

Tente acessar o Realtime Database com um app ilegítimo

Para ver a aplicação do App Check em ação, siga estas etapas:

1. Desative o registro do App Check comentando o código de registro do App Check no método init do ponto de entrada do app em DatabaseExampleApp.
2. Para redefinir o simulador, selecione Dispositivo > Apagar todo o conteúdo e as configurações. Isso vai limpar o simulador e invalidar o token do dispositivo.
3. Execute o app novamente no simulador.
4. Você vai ver a seguinte mensagem de erro:

   [FirebaseDatabase][I-RDB034005] Firebase Database connection was forcefully killed by the server.  Will not attempt reconnect. Reason: Invalid appcheck token.
   

Para reativar o App Check, faça o seguinte:

1. Remova o comentário do código de registro do App Check em DatabaseExampleApp.
2. Reinicie o app.
3. Anote o novo token do App Check no console do Xcode.
4. Registre o token de depuração nas configurações do App Check do app no Console do Firebase.
5. Execute o app novamente.
6. A mensagem de erro não vai mais aparecer, e você poderá adicionar novas postagens e comentários no app.

10. Parabéns!

Agora você sabe como:

• Adicionar o App Check a um projeto atual
• Configurar um provedor de declaração do App Attest para a versão de produção do seu app
• Configurar um provedor de atestado de depuração para testar o app em um simulador
• Acompanhe o lançamento da versão do app para saber quando aplicar o App Check no seu projeto do Firebase
• Ativar a aplicação obrigatória do App Check

Próximas etapas

Saiba como usar a Configuração remota para lançar gradualmente o App Check para seus usuários no codelab "Lançar gradualmente o Firebase App Check usando a Configuração remota do Firebase".

Confira outros recursos úteis

A configuração descrita neste codelab funciona na maioria dos casos, mas o App Check oferece mais flexibilidade, se necessário. Confira os links a seguir para mais detalhes:

• Repositório de início rápido do Firebase para iOS
• Ativar o App Check com o App Attest no iOS
• Firebase App Check na documentação do Firebase
• Como estabelecer a integridade do seu app
• Registrar um ID do app
• Ativar recursos do app