Implementar o Firebase App Check para proteger APIs contra clientes não autorizados

Quando você chama uma API diretamente de um app para dispositivos móveis ou da Web (por exemplo, as APIs que permitem acesso a modelos de IA generativa), ela fica vulnerável a abusos por clientes não autorizados. Para ajudar a proteger essas APIs, use o Firebase App Check para verificar se todas as chamadas de API recebidas são do seu app real.

O Firebase AI Logic fornece um gateway de proxy que permite a integração com o Firebase App Check e protege as APIs de modelo de IA generativa chamadas pelos seus apps para dispositivos móveis e Web. Usar App Check com os SDKs Firebase AI Logic é compatível com todas as nossas configurações:

  • Protege os dois provedores da "API Gemini": Gemini Developer API e Vertex AI Gemini API.

  • Protege todos os modelos compatíveis, tanto os Gemini quanto os Imagen.

Resumo de alto nível de como o App Check funciona

Com o App Check, os dispositivos que executam seu app usam um app ou provedor de atestado de dispositivos que verifica um ou ambos os itens a seguir:

  • As solicitações vêm do seu app autêntico
  • As solicitações vêm de um dispositivo autêntico que não foi comprometido

Esse atestado é anexado a todas as solicitações que o app faz usando um SDK do Firebase AI Logic. Quando você ativa o App Check, as solicitações de clientes sem um atestado válido são recusadas, assim como qualquer solicitação originada de um app ou plataforma que você não autorizou.

Recomendamos que, ao configurar o App Check, você se prepare para a proteção avançada (conhecida como proteção contra repetição).

Você pode encontrar informações detalhadas sobre App Check na documentação, incluindo cotas e limites.

Provedores disponíveis e instruções de implementação

A documentação do App Check oferece descrições de provedores de atestado e instruções de implementação.

  1. Escolha um provedor padrão e siga as instruções de implementação nos links a seguir:

    Se nenhum dos provedores padrão for suficiente para suas necessidades, implemente um provedor personalizado que use um provedor de atestado terceirizado ou suas próprias técnicas de atestado.

  2. (Recomendado) Prepare-se para a proteção reforçada do App Check (conhecida como proteção contra repetição).

  3. (Obrigatório) Antes de lançar o app para usuários reais, ative a aplicação do App Check.

Instanciação especial necessária para o Flutter

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

Ao usar App Check com Firebase AI Logic em apps Flutter, é necessário transmitir explicitamente App Check durante a instanciação, assim:

// ...

final ai = await FirebaseAI.googleAI(
  appCheck: FirebaseAppCheck.instance, // for Flutter, pass in App Check explicitly
);

// ...

Prepare-se para a proteção reforçada

No momento, o uso de tokens de uso limitado está disponível apenas para plataformas Apple (v12.2.0 ou mais recente), Android (v17.2.0 ou mais recente, BoM v34.2.0 ou mais recente) e Web (v12.3.0 ou mais recente) .
O suporte a outras plataformas será lançado nas próximas semanas.

Por padrão, o App Check usa tokens de sessão, que têm um tempo de vida (TTL) configurável entre 30 minutos e 7 dias. Esses tokens de sessão são armazenados em cache pelo SDK do App Check e enviados com solicitações do seu app.

No futuro, o App Check vai adicionar a opção de ativar a proteção contra repetição para Firebase AI Logic, semelhante ao suporte que o App Check já oferece para alguns outros recursos. Quando a proteção de repetição está ativada, ela aumenta a proteção das seguintes maneiras:

  • O App Check só vai permitir solicitações acompanhadas por um tipo especial de token chamado token de uso limitado.

  • Depois que o token de uso limitado é verificado, ele é consumido para que possa ser usado apenas uma vez, evitando ataques de repetição.

Para se preparar para a proteção contra reprodução, recomendamos que você ative o uso de tokens de uso limitado como parte da configuração de App Check. Assim, quando a proteção contra repetição estiver disponível, você poderá ativá-la mais cedo, porque mais usuários estarão em versões do app que enviam tokens de uso limitado.

Observe o seguinte se você ativar o uso de tokens de uso limitado no seu app agora (enquanto a proteção contra repetição não estiver disponível):

  • O App Check não bloqueia o uso de tokens de sessão válidos.

  • Assim como os tokens de sessão, os tokens de uso limitado são armazenados em cache pelo SDK App Check e enviados com as solicitações. Esses tokens de uso limitado oferecem uma pequena quantidade de proteção extra em comparação com os tokens de sessão padrão, porque eles têm um TTL mais curto (apenas 5 minutos e não ajustável) em comparação com os tokens de sessão.

  • Embora os tokens de uso limitado sejam válidos por 5 minutos, o SDK ainda vai gerar um novo token para cada solicitação. Esse processo pode adicionar alguma latência à sua solicitação.

No entanto, quando a proteção contra reprodução estiver disponível para Firebase AI Logic no futuro (e você a ativar), não será possível usar tokens de sessão nem reutilizar tokens de uso limitado. A latência adicional para gerar um novo token a cada solicitação ainda vai ocorrer.

Ativar o uso de tokens de uso limitado

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

Confira como ativar o uso de tokens de uso limitado:

  1. Implemente App Check e confira se você ativou a aplicação de App Check no seu app.

  2. No seu app durante a instanciação, ative o uso de tokens de uso limitado definindo o parâmetro useLimitedUseAppCheckTokens como true:

    Swift 

    
// ...

// During instantiation, enable usage of limited-use tokens
let ai = FirebaseAI.firebaseAI(
  backend: .googleAI(),
  useLimitedUseAppCheckTokens: true
)

// ...

    Kotlin 

    
// ...

// During instantiation, enable usage of limited-use tokens
val ai = Firebase.ai(
  backend = GenerativeBackend.googleAI(),
  useLimitedUseAppCheckTokens = true
)

// ...

    Java 

    
// ...

// During instantiation, enable usage of limited-use tokens
FirebaseAI ai = FirebaseAI.getInstance(
  /* backend: */ GenerativeBackend.googleAI(),
  /* useLimitedUseAppCheckTokens: */ true
);

// ...

    Web 

    
// ...

// During instantiation, enable usage of limited-use tokens
const ai = getAI(firebaseApp, {
  backend: new GoogleAIBackend(),
  useLimitedUseAppCheckTokens: true
});

// ...

    Dart

    O uso de tokens de uso limitado com apps do Flutter será compatível na próxima versão. Verifique novamente mais tarde.

    Unity

    O uso de tokens de uso limitado com jogos do Unity será compatível em uma versão futura. Verifique novamente mais tarde.

Entenda como o Firebase AI Logic se integra ao App Check

Para usar os SDKs do Firebase AI Logic, a API do Firebase AI Logic (firebasevertexai.googleapis.com) precisa estar ativada no seu projeto do Firebase. Isso acontece porque as solicitações feitas pelos SDKs do Firebase AI Logic são enviadas primeiro ao servidor do Firebase AI Logic, que atua como um gateway de proxy em que a verificação do Firebase App Check acontece antes de a solicitação ser permitida para o back-end do provedor "Gemini API" escolhido e as APIs para acessar os modelos do Gemini e do Imagen.