Gerenciar e implantar regras de segurança do Firebase

O Firebase fornece várias ferramentas para gerenciar suas Security Rules. Cada uma é útil em casos específicos, e cada uma usa a mesma API de back-end para gerenciamento das regras de segurança do Firebase.

Seja qual for a ferramenta usada para invocá-la, a API de gerenciamento:

• Ingere uma origem de regras: um conjunto de regras, normalmente um arquivo de código que contém instruções Firebase Security Rules.
• armazena a origem ingerida como um conjunto de regras imutável;
• monitora a implantação de cada conjunto de regras em uma versão. Os serviços ativados para regras de segurança do Firebase pesquisam a versão de um projeto para avaliar cada solicitação de um recurso protegido;
• permite executar testes sintáticos e semânticos em um conjunto de regras.

Usar a CLI Firebase

Com a CLI do Firebase, é possível fazer upload de origens locais e implantar versões. Com o Firebase Local Emulator Suite da CLI, você pode fazer testes locais completos das origens.

Usar a CLI permite que você gerencie suas regras utilizando o controle de versões com o código do aplicativo e implemente regras como parte do processo de implantação atual.

Gerar um arquivo de configuração

Ao configurar seu projeto do Firebase usando a CLI do Firebase, você cria um arquivo de configuração .rules no diretório do projeto. Use o seguinte comando para começar a configurar o projeto do Firebase:

Cloud Firestore

// Set up Firestore in your project directory, creates a .rules file
firebase init firestore

Realtime Database

// Set up Realtime Database in your project directory, creates a .rules file
firebase init database

Cloud Storage

// Set up Storage in your project directory, creates a .rules file
firebase init storage

Editar e atualizar as regras

Edite sua origem de regras diretamente no arquivo de configuração .rules.

Verifique se as edições feitas na CLI do Firebase são refletidas no console do Firebase ou se você faz atualizações consistentes usando o console do Firebase ou a CLI do Firebase. Caso contrário, você pode substituir as atualizações feitas no console do Firebase.

Observação: quando você implanta regras de segurança usando a CLI do Firebase, as regras definidas no diretório do projeto substituirão aquelas existentes no console do Firebase. Então, se você decidir defini-las ou editá-las usando o console do Firebase, atualize também as regras definidas no diretório do projeto.

Testar as atualizações

O Local Emulator Suite fornece emuladores para todos os produtos compatíveis com as regras de segurança. O mecanismo de regras de segurança de cada emulador executa a avaliação sintática e semântica das regras, excedendo o teste sintático oferecido pela API de gerenciamento de regras de segurança.

Se você trabalha com a CLI, o pacote é uma excelente ferramenta para testes de Firebase Security Rules. Use o Local Emulator Suite para testar as atualizações localmente e confirmar se as Security Rules do app exibem o comportamento desejado.

Implantar as atualizações

Depois de atualizar e testar o Security Rules, implante as origens na produção.

Para o Cloud Firestore Security Rules, associe os arquivos .rules aos bancos de dados padrão e nomeados adicionais revisando e atualizando o arquivo firebase.json.

Use os comandos a seguir para implantar seletivamente apenas o Security Rules ou como parte do processo de implantação normal.

Cloud Firestore

// Deploy rules for all databases configured in your firebase.json
firebase deploy --only firestore:rules

// Deploy rules for the specified database configured in your firebase.json
firebase deploy --only firestore:<databaseId>

Realtime Database

// Deploy your .rules file
firebase deploy --only database

Cloud Storage

// Deploy your .rules file
firebase deploy --only storage

Use o console Firebase

Observação: o console do Firebase oferece suporte à implantação do Cloud Firestore Security Rules no banco de dados padrão do seu projeto. Com as atualizações futuras, você poderá implantar Security Rules em outros bancos de dados no seu projeto. Use a CLI da Firebase para trabalhar com o Security Rules nos projetos de vários bancos de dados.

Também é possível editar origens do Security Rules e implantá-las como versões usando o console do Firebase. Os testes sintáticos são realizados à medida que você faz edições na IU do console do Firebase, e os testes semânticos estão disponíveis no Playground do Security Rules.

Editar e atualizar as regras

1. Abra o console do Firebase e selecione o projeto.
2. Em seguida, selecione Realtime Database, Cloud Firestore ou Storage na navegação do produto e clique em Regras para acessar o editor do Security Rules.
3. Edite suas regras diretamente no editor.

Observação: quando você implanta regras de segurança usando a CLI do Firebase, as regras definidas no diretório do projeto substituem as no console do Firebase. Então, se você decidir defini-las ou editá-las usando o console do Firebase, atualize também as regras definidas no diretório do projeto.

Testar as atualizações

Além de testar a sintaxe na IU do editor, é possível testar o comportamento semântico do Security Rules usando os recursos de banco de dados e armazenamento do seu projeto, diretamente no console do Firebase, usando o Playground do Security Rules. Abra a tela do Laboratório de testes de regras no editor do Security Rules, modifique as configurações e clique em Executar. Procure a mensagem de confirmação na parte superior do editor.

Implantar as atualizações

Quando você achar que as atualizações foram implementadas conforme o esperado, clique em Publicar.

Usar o SDK Admin

Observação: no momento, o Firebase Admin SDK oferece suporte à implantação do Cloud Firestore Security Rules no banco de dados padrão do seu projeto. Com as atualizações futuras, você poderá implantar Security Rules em outros bancos de dados no seu projeto. Use a CLI da Firebase para trabalhar com o Security Rules nos projetos de vários bancos de dados.

É possível usar os conjuntos de regras do Admin SDK para Node.js. Com esse acesso programático, é possível:

• Implementar ferramentas, scripts, painéis e pipelines de CI/CD personalizados para gerenciar regras.
• Gerenciar regras com mais facilidade em vários projetos do Firebase.

Ao atualizar as regras de maneira programática, é muito importante evitar alterações indesejadas no controle de acesso do seu app. Escreva seu código do Admin SDK com a segurança em primeiro lugar, principalmente ao atualizar ou implantar regras.

Outra coisa importante a ser lembrada é que as versões do Firebase Security Rules levam vários minutos para serem totalmente propagadas. Ao usar a Admin SDK para implantar regras, evite as disputas em que seu aplicativo dependa imediatamente das regras cuja implantação ainda não esteja concluída. Se o caso de uso exigir atualizações frequentes nas regras de controle de acesso, considere soluções que usem Cloud Firestore, que foi projetado para reduzir as disputas, apesar das atualizações frequentes.

Observação: agora é possível fazer testes de unidade nas regras usando os emuladores locais do Cloud Firestore e do Realtime Database, mas o teste não está disponível nesse SDK. Se você quiser garantir que as regras sejam testadas antes da implantação, não recomendamos atualizá-las usando o Admin SDK.

Observe também estes limites:

• As regras precisam ser menores que 256 KiB de texto codificado em UTF-8 quando serializadas.
• Um projeto pode ter no máximo 2.500 conjuntos de regras implantados. Quando esse limite for atingido, você precisará excluir alguns conjuntos de regras antigos antes de criar novos.

Criar e implantar conjuntos de regras do Cloud Storage ou do Cloud Firestore

Um fluxo de trabalho comum para gerenciar regras de segurança com o Admin SDK pode incluir três etapas:

1. Criar uma origem de arquivo de regras (opcional)
2. Criar um conjunto de regras
3. Libere ou implante o novo conjunto de regras

O SDK fornece um método para combinar essas etapas em uma única chamada de API para regras de segurança do Cloud Storage e do Cloud Firestore. Exemplo:

    const source = `service cloud.firestore {
      match /databases/{database}/documents {
        match /carts/{cartID} {
          allow create: if request.auth != null && request.auth.uid == request.resource.data.ownerUID;
          allow read, update, delete: if request.auth != null && request.auth.uid == resource.data.ownerUID;
        }
      }
    }`;
    // Alternatively, load rules from a file
    // const fs = require('fs');
    // const source = fs.readFileSync('path/to/firestore.rules', 'utf8');

    await admin.securityRules().releaseFirestoreRulesetFromSource(source);

Esse mesmo padrão funciona para regras Cloud Storage com releaseFirestoreRulesetFromSource().

Como alternativa, é possível criar o arquivo de regras como um objeto na memória, criar o conjunto de regras e implantá-lo separadamente para ter um controle mais próximo desses eventos. Exemplo:

    const rf = admin.securityRules().createRulesFileFromSource('firestore.rules', source);
    const rs = await admin.securityRules().createRuleset(rf);
    await admin.securityRules().releaseFirestoreRuleset(rs);

Atualizar conjuntos de regras de Realtime Database

Para atualizar os conjuntos de regras Realtime Database com o Admin SDK, use os métodos getRules() e setRules() de admin.database. É possível recuperar conjuntos de regras no formato JSON ou como uma string com comentários incluídos.

Para atualizar um conjunto de regras:

    const source = `{
      "rules": {
        "scores": {
          ".indexOn": "score",
          "$uid": {
            ".read": "$uid == auth.uid",
            ".write": "$uid == auth.uid"
          }
        }
      }
    }`;
    await admin.database().setRules(source);

Gerenciar conjuntos de regras

Para ajudar a gerenciar grandes conjuntos de regras, a Admin SDK permite listar todas as regras atuais com admin.securityRules().listRulesetMetadata. Exemplo:

    const allRulesets = [];
    let pageToken = null;
    while (true) {
      const result = await admin.securityRules().listRulesetMetadata(pageToken: pageToken);
      allRulesets.push(...result.rulesets);
      pageToken = result.nextPageToken;
      if (!pageToken) {
        break;
      }
    }

Para implantações muito grandes que atingem o limite de 2.500 regras ao longo do tempo, é possível criar uma lógica para excluir as regras mais antigas em um ciclo de tempo fixo. Por exemplo, para excluir todos os conjuntos de regras implantados por mais de 30 dias:

    const thirtyDays = new Date(Date.now() - THIRTY_DAYS_IN_MILLIS);
    const promises = [];
    allRulesets.forEach((rs) => {
      if (new Date(rs.createTime) < thirtyDays) {
        promises.push(admin.securityRules().deleteRuleset(rs.name));
      }
    });
    await Promise.all(promises);
    console.log(`Deleted ${promises.length} rulesets.`);

Usar a API REST

As ferramentas descritas acima são adequadas para vários fluxos de trabalho, incluindo o gerenciamento de Firebase Security Rules para vários bancos de dados do Cloud Firestore no seu projeto, mas talvez você queira gerenciar e implantar o Firebase Security Rules usando a própria API Management. A API Management oferece a maior flexibilidade.

Observação: esta seção aborda os casos de uso de gerenciamento básico semelhantes aos apresentados acima. Para mais casos de uso e exemplos disponíveis com essa API, consulte a documentação de referência completa da API REST de gerenciamento de regras.

Observe também estes limites:

• As regras precisam ser menores que 256 KiB de texto codificado em UTF-8 quando serializadas.
• Um projeto pode ter no máximo 2.500 conjuntos de regras implantados. Quando esse limite for atingido, você precisará excluir alguns conjuntos de regras antigos antes de criar novos.

Criar e implantar conjuntos de regras do Cloud Firestore ou do Cloud Storage com REST

Os exemplos nesta seção usam o Firestore Security Rules, mas também se aplicam ao Cloud Storage Security Rules.

Os exemplos também usam cURL para fazer chamadas de API. As etapas para configurar e transmitir tokens de autenticação são omitidas. É possível testar essa API usando o APIs Explorer integrado à documentação de referência.

As etapas típicas para criar e implantar um conjunto de regras usando a API de gerenciamento são as seguintes:

1. Criar origens de arquivos de regras
2. Criar um conjunto de regras
3. Lance (implante) o novo conjunto de regras.

Criar uma origem

Digamos que você esteja trabalhando no projeto do Firebase secure_commerce e queira implantar Security Rules de Cloud Firestore bloqueadas em um banco de dados chamado east_store no seu projeto.

É possível implementar essas regras em um arquivo firestore.rules.

service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

Criar um conjunto de regras

Agora, gere uma impressão digital codificada em base64 para esse arquivo. Em seguida, use a origem nesse arquivo para preencher o payload necessário para criar um conjunto de regras com a chamada REST projects.rulesets.create. Aqui, use o comando cat para inserir o conteúdo de firestore.rules no payload REST.

Para rastreamento, associe isso ao banco de dados east_store e defina attachment_point como east_store.

curl -X POST -d '{
  "source": {
    "files": [
      {
        "content": "' $(cat storage.rules) '",
        "name": "firestore.rules",
        "fingerprint": <sha fingerprint>
      },
    "attachment_point": "firestore.googleapis.com/databases/east_store"
    ]
  }
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets'

A API retorna uma resposta de validação e um nome de conjunto de regras, por exemplo, projects/secure_commerce/rulesets/uuid123.

Lançar (implantar) um conjunto de regras

Se o conjunto de regras for válido, a etapa final será implantar o novo conjunto de regras em uma versão nomeada.

curl -X POST -d '{
  "name": "projects/secure_commerce/releases/cloud.firestore/east_store"  ,
  "rulesetName": "projects/secure_commerce/rulesets/uuid123"
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/releases'

Observação: para lançamento no banco de dados (padrão), o caminho projects//releases/cloud.firestore/(default) é equivalente a projects//releases/cloud.firestore.

As versões do Firebase Security Rules levam alguns minutos para serem totalmente propagadas. Ao usar a API REST de gerenciamento para fazer a implantação, evite as disputas em que seu aplicativo dependa imediatamente das regras cuja implantação ainda não esteja concluída.

Atualizar conjuntos de regras do Realtime Database com REST

O Realtime Database fornece uma interface REST própria para gerenciar o Security Rules. Consulte Como gerenciar o Realtime Database do Firebase Security Rules com a API REST.

Gerenciar conjuntos de regras com REST

Para ajudar a gerenciar implantações de regras grandes, além de um método REST para criar conjuntos de regras e versões, a API de gerenciamento fornece métodos para:

• listar, recuperar e excluir conjuntos de regras
• listar, receber e excluir versões de regras

Para implantações muito grandes que atingem o limite de 2.500 regras ao longo do tempo, é possível criar uma lógica para excluir as regras mais antigas em um ciclo de tempo fixo. Por exemplo, para excluir todos os conjuntos de regras implantados por mais de 30 dias, chame o método projects.rulesets.list, analise a lista JSON de objetos Ruleset nas chaves createTime e chame project.rulesets.delete nos conjuntos de regras correspondentes por ruleset_id.

Testar as atualizações com REST

Por fim, a API Management permite executar testes sintáticos e semânticos em recursos Cloud Firestore e Cloud Storage nos seus projetos de produção.

Observação: os testes executados usando a API REST usam bancos de dados de produção, buckets de armazenamento e recursos relacionados. Esses testes podem gerar cobranças de uso. Recomendamos que você use o Firebase Local Emulator Suite para realizar testes do Firebase Security Rules, já que é possível executar testes em recursos off-line que não são de produção sem cobranças de uso. Consulte nosso guia sobre como testar o Firebase Security Rules com o Local Emulator Suite.

O teste com este componente da API consiste em:

1. Definir um objeto JSON TestSuite para representar um conjunto de objetos TestCase
2. Enviar o TestSuite
3. Analisar os objetos TestResult retornados

Vamos definir um objeto TestSuite com um único TestCase em um arquivo testcase.json. Neste exemplo, transmitimos a origem da linguagem Security Rules inline com o payload REST, junto com o pacote de testes a ser executado nessas regras. Especificamos uma expectativa de avaliação de regras e a solicitação do cliente que será usada para testar o conjunto de regras. Também é possível especificar o nível de detalhamento do relatório de teste usando o valor "FULL" para indicar que os resultados de todas as expressões de linguagem Security Rules precisam ser incluídos no relatório, incluindo expressões que não correspondem à solicitação.

 {
  "source":
  {
    "files":
    [
      {
        "name": "firestore.rules",
        "content": "service cloud.firestore {
          match /databases/{database}/documents {
            match /users/{userId}{
              allow read: if (request.auth.uid == userId);
            }
            function doc(subpath) {
              return get(/databases/$(database)/documents/$(subpath)).data;
            }
            function isAccountOwner(accountId) {
              return request.auth.uid == accountId 
                  || doc(/users/$(request.auth.uid)).accountId == accountId;
            }
            match /licenses/{accountId} {
              allow read: if isAccountOwner(accountId);
            }
          }
        }"
      }
    ]
  },
  "testSuite":
  {
    "testCases":
    [
      {
        "expectation": "ALLOW",
        "request": {
           "auth": {"uid": "123"},
           "path": "/databases/(default)/documents/licenses/abcd",
           "method": "get"},
        "functionMocks": [
            {
            "function": "get",
            "args": [{"exact_value": "/databases/(default)/documents/users/123"}],
            "result": {"value": {"data": {"accountId": "abcd"}}}
            }
          ]
      }
    ]
  }
}

Podemos enviar este TestSuite para avaliação com o método projects.test.

curl -X POST -d '{
    ' $(cat testcase.json) '
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/rulesets/uuid123:test'

O TestReport retornado (contendo o status de teste SUCCESS/FAILURE, listas de mensagens de depuração, listas de expressões de regras visitadas e os relatórios de avaliação) confirmaria com o status SUCCESS que o acesso foi permitido corretamente.

Gerenciar permissões para Cloud Storage Security Rules entre serviços

Se você criar Cloud Storage Security Rules que usam o conteúdo de documentos do Cloud Firestore para avaliar as condições de segurança, será solicitado no Firebase console ou na CLI do Firebase que você ative as permissões para conectar os dois produtos.

Se você decidir desativar esse tipo de segurança entre serviços, faça o seguinte:

1. Antes de desativar o recurso, edite as regras, removendo todas as instruções que usam funções Security Rules para acessar o Cloud Firestore. Caso contrário, depois que o recurso for desativado, as avaliações do Security Rules farão com que as solicitações do Storage falhem.

2. Use a página IAM no Console do Google Cloud para excluir o papel "Agente de serviço do Firestore para regras do Firebase" seguindo o guia do Cloud para revogar papéis.

   Observação: na página IAM, marque a caixa "Incluir concessões do papel fornecidas pelo Google" para ver todos os papéis.
   Observação: na página IAM, você vai encontrar a conta de serviço do Firebase Storage com o ID terminando em @gcp-sa-firebasestorage.iam.gserviceaccount.com. Se as regras entre serviços diferentes estiverem ativadas, você verá o papel "Agente de serviço do Firestore para regras de Firebase" listado.

Você precisará reativar o recurso na próxima vez que salvar as regras de vários serviços na Firebase CLI ou no console do Firebase.