Regras de segurança para operações de pipeline

Regras de segurança para operações de pipeline

As regras de operações de pipeline permitem que você corresponda aos recursos de filtragem do mecanismo de regras atual. Embora as operações de pipeline ofereçam um conjunto avançado de recursos, o mecanismo de regras é restrito ao reconhecimento de filtros simples para garantir a satisfação e a segurança da consulta.

Requisitos de edição e modo

Este documento se aplica à edição Enterprise do Firestore no modo nativo.

Expressões de filtro compatíveis

Para que uma consulta seja restrita pelas suas regras, ela precisa usar operadores de comparação padrão com constantes. O mecanismo de regras reconhece os seguintes tipos de filtros:

• Igualdade e desigualdade: eq, neq.
• Comparações: gt, gte, lt, lte.
• Assinatura: in, arrayContains.

Veja alguns exemplos:

• where(eq("foo", 2))
• where(lt("foo", 2))
• documents("/user/1", "/user/2").where(...)

Observação: expressões complexas, como operações aritméticas em um filtro (por exemplo, where(eq("foo" * 2, 10))) ou funções de string como strContains, não são reconhecidas para restringir consultas.

Propriedades da solicitação

Você pode continuar usando o objeto request para validar a autenticação e o contexto da consulta, embora algumas propriedades disponíveis em consultas padrão não sejam compatíveis com pipelines.

Propriedades compatíveis

O novo mecanismo continua oferecendo suporte às seguintes propriedades:

• request.auth: acesse o UID do usuário e os dados do token.
• request.method: identifica a operação (por exemplo, get, list).
• request.path: o caminho do recurso que está sendo acessado.
• request.time: o carimbo de data/hora do lado do servidor da solicitação.

Propriedades não compatíveis

As propriedades request.query, como limit, offset e orderBy, não são compatíveis com as verificações de regras de pipelines devido à complexidade de determinar esses valores em consultas de várias etapas.

Processamento e permissões de estágio do pipeline

Há diferentes estágios de pipeline que são mapeados para operações granulares específicas em regras de segurança:

• Permissões allow list: acionadas pelas etapas collection(), collectionGroup() e database().
• Permissões de allow get: acionadas pela etapa documents(), que é tratada de maneira semelhante a uma operação em lote get.
• Permissões allow create: acionadas pelas etapas insert() e upsert() ao criar novos documentos.
• Permissões allow update: acionadas pelas etapas update() e upsert() ao atualizar documentos.
• Permissões allow delete: acionadas pelas etapas delete().
• Permissões allow write: aplicam-se a todas as operações de DML (insert(), update(), upsert() e delete()).
• Etapas de modificação de campo: as regras só operam em dados armazenados, não em valores derivados. Se um pipeline incluir estágios que modificam campos (por exemplo, AddFields, ReplaceWith, Select), o mecanismo de regras vai parar de aplicar restrições de filtro depois que esse estágio for encontrado.
• Etapa de literais: a etapa literals() não lê do banco de dados, mas pode gerar custos. Para evitar abusos, ele precisa ser combinado com outro estágio (como collection()) que pode ser verificado por regras.

Estágios da linguagem de manipulação de dados (DML) e regras de segurança

Ao executar as etapas da linguagem de manipulação de dados (DML, na sigla em inglês) (insert(), update(), upsert() e delete()), as regras de segurança avaliam as permissões de maneira diferente das consultas de leitura:

• Avaliação de regras por documento: ao contrário dos pipelines de leitura, que exigem expressões de filtro antecipadamente para restringir a consulta no momento do planejamento, as operações de DML avaliam as regras de segurança em relação a cada mutação de documento individual.
• Variáveis de regra:
  • request.resource: contém os dados do documento proposto para as operações insert(), update() e upsert().
  • resource: contém os dados do documento atual armazenados no banco de dados antes da modificação (disponível para update(), delete() e upsert() de documentos atuais).

Limites do sistema e comportamento de execução com DML

Ao executar operações de DML com regras de segurança, tenha em mente os seguintes limites do sistema e comportamentos de execução:

O limite de 20 pesquisas em get() e exists()

As regras de segurança do Firebase permitem no máximo 20 pesquisas de documentos (get() ou exists()) em uma solicitação inteira.

Quando um pipeline de DML é executado fora de uma transação explícita, os documentos são processados em lotes. Como cada lote é executado na própria transação e os documentos podem ser modificados simultaneamente entre os lotes, as regras de segurança e as pesquisas de documentos são reavaliadas para cada lote de gravação.

Mesmo que as regras de segurança sejam avaliadas em relação a um único documento estático, por exemplo, verificando se um usuário é administrador:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /posts/{postId} {
      allow write: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.isAdmin == true;
    }
  }
}

Cada lote de gravação de documentos realiza uma pesquisa. Como resultado, depois de gravar todos os documentos possíveis, o limite de 20 pesquisas para a solicitação é atingido, e o pipeline falha com um erro PERMISSION_DENIED. Além disso, cada pesquisa realizada por lote de gravação gera o próprio faturamento de leitura.

Dica :para evitar atingir o limite de 20 pesquisas em operações DML em massa, use declarações personalizadas em tokens do Firebase Authentication (por exemplo, request.auth.token.isAdmin == true) em vez de pesquisas get() ou exists(). As declarações personalizadas são validadas na memória diretamente do token de autenticação, evitando completamente as leituras de documentos e os limites de pesquisa.

Sucesso parcial e PERMISSION_DENIED

Quando executadas fora de uma transação, as operações de DML confirmam as gravações em lotes sequenciais. Se um lote falhar, seja porque um documento não atende a uma condição de regra ou porque o limite de 20 pesquisas foi excedido, o pipeline será interrompido e retornará um erro PERMISSION_DENIED.

No entanto, os lotes que já foram confirmados não são revertidos. O banco de dados permanece em um estado parcialmente atualizado. Como o cliente recebe um erro sem uma lista de documentos modificados, é necessário consultar seus dados para inspecionar quais gravações foram bem-sucedidas.

Dica :se a carga de trabalho exigir uma execução do tipo "tudo ou nada", execute o pipeline de DML em uma transação de usuário explícita (por exemplo, usando runTransaction e transaction.execute(pipeline)). Em uma transação, todas as operações são confirmadas juntas ou reverter completamente em caso de erro. As transações estão sujeitas aos limites de transação da edição Firestore Enterprise.

Como diagnosticar falhas de regras com os Registros de Auditoria do Cloud

Por motivos de segurança, os erros PERMISSION_DENIED voltados para o cliente não divulgam qual condição da regra de segurança falhou ou se o limite de 20 pesquisas foi atingido.

Para diagnosticar falhas na avaliação de regras, os administradores do projeto podem inspecionar os registros de auditoria do Cloud no console do Google Cloud (em Firestore > Monitoramento ou na Análise de registros) para conferir entradas detalhadas do EvaluationError.