Ative o App Check com Play Integrity no Android

Esta página mostra como habilitar o App Check em um aplicativo Android, usando o provedor Play Integrity integrado. Ao ativar o App Check, você ajuda a garantir que apenas seu aplicativo possa acessar os recursos do Firebase do seu projeto. Veja uma Visão geral deste recurso.

Atualmente, o provedor de integridade do Google Play integrado é compatível apenas com aplicativos Android distribuídos pelo Google Play. Para usar os recursos off-Play do Play Integrity ou usar o App Check com seu próprio provedor personalizado, consulte Implementar um provedor personalizado do App Check .

1. Configure seu projeto do Firebase

1. Adicione o Firebase ao seu projeto Android, caso ainda não tenha feito isso.

2. Ative a API Play Integrity:

   1. No Google Play Console , selecione seu aplicativo ou adicione-o, caso ainda não tenha feito isso.

   2. Na seção Versão , clique em Configuração > Integridade do aplicativo .

   3. Na página da Integrity API , clique em Vincular projeto e selecione seu projeto do Firebase na lista de projetos do Google Cloud.

      O projeto selecionado aqui deve ser o mesmo projeto do Firebase que você registrou seu aplicativo (veja a próxima etapa).

3. Registre seus aplicativos para usar o App Check com o provedor Play Integrity na seção App Check do Firebase console. Você precisará fornecer a impressão digital SHA-256 do certificado de assinatura do seu aplicativo.

   Normalmente, você precisa registrar todos os aplicativos do seu projeto porque, depois de ativar a aplicação de um produto Firebase, apenas os aplicativos registrados poderão acessar os recursos de back-end do produto.

4. Opcional : nas configurações de registro do aplicativo, defina um tempo de vida (TTL) personalizado para os tokens do App Check emitidos pelo provedor. Você pode definir o TTL para qualquer valor entre 30 minutos e 7 dias. Ao alterar esse valor, esteja ciente das seguintes compensações:

   • Segurança: TTLs mais curtos fornecem segurança mais forte, pois reduzem a janela na qual um token vazado ou interceptado pode ser abusado por um invasor.
   • Desempenho: TTLs mais curtos significam que seu aplicativo realizará o atestado com mais frequência. Como o processo de atestado do aplicativo adiciona latência às solicitações de rede sempre que é executado, um TTL curto pode afetar o desempenho do seu aplicativo.
   • Cota e custo: TTLs mais curtos e reatestação frequente esgotam sua cota mais rapidamente e, para serviços pagos, podem custar mais. Consulte Cotas e limites .

   O TTL padrão de 1 hora é razoável para a maioria dos aplicativos. Observe que a biblioteca App Check atualiza os tokens em aproximadamente metade da duração do TTL.

2. Adicione a biblioteca App Check ao seu aplicativo

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.1.0')

    // Declare the dependency for the App Check library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

dependencies {
    // Declare the dependency for the App Check library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity:16.0.0'
}

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.1.0')

    // Declare the dependency for the App Check library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

dependencies {
    // Declare the dependency for the App Check library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity:16.0.0'
}

3. Inicialize o App Check

Adicione o seguinte código de inicialização ao seu aplicativo para que ele seja executado antes de usar qualquer outro SDK do Firebase:

FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance());

FirebaseApp.initializeApp(/*context=*/this)
val firebaseAppCheck = FirebaseAppCheck.getInstance()
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance()
)

Depois que a biblioteca do App Check estiver instalada em seu aplicativo, comece a distribuir o aplicativo atualizado para seus usuários.

O aplicativo cliente atualizado começará a enviar tokens do App Check junto com todas as solicitações feitas ao Firebase, mas os produtos Firebase não exigirão que os tokens sejam válidos até que você ative a aplicação na seção App Check do Firebase console. Consulte as próximas duas seções para obter detalhes.

4. Monitore as métricas de solicitação

Agora que seu aplicativo atualizado está nas mãos dos usuários, você pode ativar a aplicação do App Check para os produtos Firebase que você usa. Antes de fazer isso, no entanto, certifique-se de que isso não atrapalhe seus usuários legítimos existentes.

Realtime Database, Cloud Firestore e Cloud Storage

Uma ferramenta importante que você pode usar para tomar essa decisão para Realtime Database, Cloud Firestore e Cloud Storage é a tela de métricas de solicitação do App Check.

Para visualizar as métricas de solicitação do App Check para um produto, abra a seção App Check do Firebase console. Por exemplo:

As métricas de solicitação para cada produto são divididas em quatro categorias:

• As solicitações verificadas são aquelas que possuem um token válido do App Check. Depois de habilitar a aplicação do App Check, somente solicitações nesta categoria serão bem-sucedidas.

• Solicitações de cliente desatualizadas são aquelas que não possuem um token do App Check. Essas solicitações podem ser de uma versão mais antiga do SDK do Firebase antes da inclusão do App Check no aplicativo.

• Solicitações de origem desconhecidas são aquelas que não possuem um token do App Check e não parecem vir do SDK do Firebase. Podem ser de solicitações feitas com chaves de API roubadas ou solicitações forjadas feitas sem o SDK do Firebase.

• Solicitações inválidas são aquelas que têm um token de verificação de aplicativo inválido, que pode ser de um cliente inautêntico tentando representar seu aplicativo ou de ambientes emulados.

A distribuição dessas categorias para seu aplicativo deve informar quando você decide ativar a aplicação. Aqui estão algumas orientações:

• Se quase todas as solicitações recentes forem de clientes verificados, considere habilitar a aplicação para começar a proteger seus recursos de back-end.

• Se uma parte significativa das solicitações recentes for de clientes provavelmente desatualizados, para evitar a interrupção dos usuários, considere esperar que mais usuários atualizem seu aplicativo antes de ativar a aplicação. A aplicação do App Check em um aplicativo lançado interromperá as versões anteriores do aplicativo que não estão integradas ao SDK do App Check.

• Se seu aplicativo ainda não foi iniciado, você deve habilitar a aplicação do App Check imediatamente, pois não há clientes desatualizados em uso.

Funções de nuvem

Para o Cloud Functions, você pode obter as métricas do App Check examinando os registros de suas funções. Cada invocação de uma função que pode ser chamada emite uma entrada de log estruturada como no exemplo a seguir:

{
  "severity": "INFO",    // INFO, WARNING, or ERROR
  "logging.googleapis.com/labels": {"firebase-log-type": "callable-request-verification"},
  "jsonPayload": {
    "message": "Callable header verifications passed.",
    "verifications": {
      // ...
      "app": "MISSING",  // VALID, INVALID, or MISSING
    }
  }
}

Você pode analisar essas métricas no Console do Google Cloud criando uma métrica de contador baseada em registros com o seguinte filtro de métrica:

resource.type="cloud_function"
resource.labels.function_name="YOUR_CLOUD_FUNCTION"
resource.labels.region="us-central1"
labels.firebase-log-type="callable-request-verification"

Rotule a métrica usando o campo jsonPayload.verifications.appCheck .

5. Ativar aplicação

Para ativar a aplicação, siga as instruções para cada produto abaixo. Depois de ativar a aplicação de um produto, todas as solicitações não verificadas para esse produto serão rejeitadas.

Realtime Database, Cloud Firestore e Cloud Storage

Para ativar a aplicação do Realtime Database, Cloud Firestore (iOS e Android) e Cloud Storage:

1. Abra a seção App Check do Firebase console.

2. Expanda a visualização de métricas do produto para o qual você deseja ativar a aplicação.

3. Clique em Aplicar e confirme sua escolha.

Observe que pode levar até 15 minutos após a ativação da imposição para que ela entre em vigor.

Funções de nuvem

Consulte Ativar a aplicação do App Check para o Cloud Functions .

Próximos passos

Se, depois de registrar seu aplicativo para o App Check, você quiser executá-lo em um ambiente que o App Check normalmente não classificaria como válido, como um emulador durante o desenvolvimento ou de um ambiente de integração contínua (CI), você pode crie uma compilação de depuração do seu aplicativo que use o provedor de depuração do App Check em vez de um provedor de atestado real.

Consulte Usar o App Check com o provedor de depuração no Android .