获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

Gerenciar e implantar regras de segurança do Firebase

O Firebase oferece várias ferramentas para gerenciar suas regras, cada uma útil em casos específicos e cada uma usando a mesma API de gerenciamento de regras de segurança do Firebase de back-end.

Não importa qual ferramenta é usada para invocá-la, a API de gerenciamento:

  • Ingere uma origem de regras : um conjunto de regras, normalmente um arquivo de código contendo instruções de regras de segurança do Firebase.
  • Armazena a origem ingerida como um conjunto de regras imutável.
  • Rastreia a implantação de cada conjunto de regras em uma versão . Os serviços habilitados para as regras de segurança do Firebase pesquisam a versão de um projeto para avaliar cada solicitação de um recurso seguro.
  • Fornece a capacidade de executar testes sintáticos e semânticos de um conjunto de regras.

Usar a CLI do Firebase

Com a Firebase CLI , você pode fazer upload de fontes locais e implantar versões . O Firebase Local Emulator Suite da CLI permite realizar testes locais completos de fontes .

O uso da CLI permite que você mantenha suas regras sob controle de versão com seu código de aplicativo e implemente regras como parte de seu processo de implementação existente.

Gerar um arquivo de configuração

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

Cloud Firestore

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

Banco de dados em tempo real

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

Armazenamento na núvem

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

Edite e atualize suas regras

Edite sua origem de regras diretamente no arquivo de configuração .rules . Certifique-se de que todas as edições feitas na Firebase CLI sejam refletidas no Firebase console ou que você faça atualizações consistentemente usando o Firebase console ou a Firebase CLI. Caso contrário, você poderá substituir as atualizações feitas no console do Firebase.

Teste suas atualizações

O Local Emulator Suite fornece emuladores para todos os produtos habilitados para Regras de Segurança. O mecanismo de regras de segurança para cada emulador realiza avaliação sintática e semântica de regras, excedendo assim o teste sintático que a API de gerenciamento de regras de segurança oferece.

Se você estiver trabalhando com a CLI, o Suite é uma excelente ferramenta para testar as regras de segurança do Firebase. Use o Local Emulator Suite para testar suas atualizações localmente e confirme se as regras do seu aplicativo exibem o comportamento desejado.

Implante suas atualizações

Depois de atualizar e testar suas regras, implante as fontes em produção. Use os comandos a seguir para implantar seletivamente suas regras sozinhas ou implantá-las como parte de seu processo de implantação normal.

Cloud Firestore

// Deploy your .rules file
firebase deploy --only firestore:rules

Banco de dados em tempo real

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

Armazenamento na núvem

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

Usar o console do Firebase

Você também pode editar origens de regras e implantá-las como versões do Firebase console. O teste sintático é executado conforme você edita na IU do console do Firebase, e o teste sintático está disponível usando o Rules Playground.

Edite e atualize suas regras

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

Teste suas atualizações

Além de testar a sintaxe na IU do editor, você pode testar o comportamento semântico das regras, usando o banco de dados e os recursos de armazenamento do seu projeto, diretamente no console do Firebase, usando o Rules Playground . Abra a tela Rules Playground no editor de regras, modifique as configurações e clique em Run . Procure a mensagem de confirmação na parte superior do editor.

Implante suas atualizações

Quando estiver certo de que suas atualizações são o que você espera, clique em Publicar .

Usar o SDK Admin

Você pode usar os conjuntos de regras do SDK Admin para Node.js . Com este acesso programático, você pode:

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

Ao atualizar as regras programaticamente, é muito importante evitar fazer alterações não intencionais no controle de acesso do seu aplicativo. Escreva o código do Admin SDK com a segurança em mente, especialmente ao atualizar ou implantar regras.

Outra coisa importante a ter em mente é que as versões do Firebase Security Rules levam alguns minutos para serem totalmente propagadas. Ao usar o SDK Admin para implantar regras, certifique-se de evitar condições de corrida em que seu aplicativo depende imediatamente de regras cuja implantação ainda não foi concluída. Se o seu caso de uso exigir atualizações frequentes das regras de controle de acesso, considere soluções usando o Cloud Firestore, projetado para reduzir as condições de corrida apesar das atualizações frequentes.

Observe também estes limites:

  • As regras devem 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 no total. Quando esse limite for atingido, você deverá 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 típico para gerenciar regras de segurança com o SDK Admin pode incluir três etapas distintas:

  1. Criar uma fonte 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 as regras de segurança do Cloud Storage e do Cloud Firestore. Por 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 do Cloud Storage com releaseFirestoreRulesetFromSource() .

Como alternativa, você pode criar o arquivo de regras como um objeto na memória, criar o conjunto de regras e implantar o conjunto de regras separadamente para um controle mais próximo desses eventos. Por 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 do Realtime Database

Para atualizar os conjuntos de regras do Realtime Database com o SDK Admin, use os getRules() e setRules() de admin.database . Você pode 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, o SDK Admin permite listar todas as regras existentes com admin.securityRules().listRulesetMetadata . Por 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 conjuntos de regras ao longo do tempo, você pode criar 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, mas convém gerenciar e implantar as regras de segurança do Firebase usando a própria API de gerenciamento. A API de gerenciamento oferece a você a maior flexibilidade.

Esteja ciente de que as versões do Firebase Security Rules levam vários minutos para serem totalmente propagadas. Ao usar a API REST de gerenciamento para implantar, certifique-se de evitar condições de corrida em que seu aplicativo depende imediatamente de regras cuja implantação ainda não foi concluída.

Observe também estes limites:

  • As regras devem 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 no total. Quando esse limite for atingido, você deverá excluir alguns conjuntos de regras antigos antes de criar novos.

Crie e implante conjuntos de regras do Cloud Storage ou do Cloud Firestore com REST

Os exemplos nesta seção usam regras de armazenamento, embora também se apliquem às regras do Cloud Firestore.

Os exemplos também usam cURL para fazer chamadas de API. As etapas para configurar e passar tokens de autenticação são omitidas. Você pode experimentar essa API usando o API 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:

  1. Criar fontes de arquivo de regras
  2. Criar um conjunto de regras
  3. Liberar (implantar) o novo conjunto de regras

Vamos supor que você esteja trabalhando em seu projeto secure_commerce do Firebase e queira implantar regras de armazenamento em nuvem bloqueadas. Você pode implementar essas regras em um arquivo storage.rules .

service firebase.storage {
  match /b/{bucket}/o {
    match /{allPaths=**} {
      allow read, write: if false;
    }
  }
}

Agora, gere uma impressão digital codificada em base64 para este arquivo. Você pode então usar a origem nesse arquivo para preencher a carga útil necessária para criar um conjunto de regras com a chamada REST projects.rulesets.create . Aqui, usamos o comando cat para inserir o conteúdo de storage.rules na carga útil REST.

curl -X POST -d '{
  "source": {
    {
      "files": [
        {
          "content": "' $(cat storage.rules) '",
          "name": "storage.rules",
          "fingerprint": <sha fingerprint>
        }
      ]
    }
  }
}' '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 . 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/prod/v23   "  ,
  "rulesetName": "projects/secure_commerce/rulesets/uuid123",
}' 'https://firebaserules.googleapis.com/v1/projects/secure_commerce/releases'

Atualizar conjuntos de regras do Realtime Database com REST

O Realtime Database fornece sua própria interface REST para gerenciar regras. Consulte Gerenciar regras do Firebase Realtime Database via REST .

Gerenciar conjuntos de regras com REST

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

  • listar, obter e excluir conjuntos de regras
  • listar, obter e excluir versões de regras

Para implantações muito grandes que atingem o limite de 2.500 conjuntos de regras ao longo do tempo, você pode criar 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, você pode chamar o método projects.rulesets.list , analisar a lista JSON de objetos Ruleset em suas chaves createTime e chamar project.rulesets.delete nos conjuntos de regras correspondentes por ruleset_id .

Teste suas atualizações com REST

Por fim, a API de gerenciamento permite que você execute testes sintáticos e semânticos nos recursos do Cloud Firestore e do Cloud Storage em seus projetos de produção.

O teste com este componente da API consiste em:

  1. Definindo um objeto JSON TestSuite para representar um conjunto de objetos TestCase
  2. Enviando o TestSuite
  3. Analisando objetos TestResult retornados

Vamos definir um objeto TestSuite com um único TestCase em um arquivo testcase.json . Neste exemplo, passamos a origem da linguagem Rules em linha com a carga útil REST, juntamente com o conjunto de testes para executar essas regras. Especificamos uma expectativa de avaliação de Regras e a solicitação do cliente em relação à qual o conjunto de regras deve ser testado. Você também pode especificar o quão completo é o relatório de teste, usando o valor "FULL" para indicar que os resultados de todas as expressões de linguagem de regras devem ser incluídas no relatório, incluindo expressões que não corresponderam à 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 então 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 SUCCESS/FAILURE do teste, listas de mensagens de depuração, listas de expressões de Regras visitadas e seus relatórios de avaliação) confirmaria com o status SUCCESS que o acesso está devidamente permitido.

Gerenciar permissões para regras de segurança do Cloud Storage entre serviços

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

Se você decidir desabilitar essa segurança entre serviços:

  1. Primeiro, antes de desativar o recurso, edite suas regras, removendo todas as instruções que usam funções de regras para acessar o Cloud Firestore. Caso contrário, depois que o recurso for desabilitado, as avaliações de regras farão com que suas solicitações de armazenamento falhem.

  2. Use a página do IAM no Console do Google Cloud para excluir a função "Firebase Rules Firestore Service Agent" seguindo o guia do Cloud para revogação de funções .

Você será solicitado a reativar o recurso na próxima vez que salvar regras entre serviços da Firebase CLI ou do Firebase console.