Управление и развертывание правил безопасности Firebase

Firebase предоставляет вам несколько инструментов для управления Rules , каждый из которых полезен в определенных случаях, и каждый из них использует один и тот же внутренний API управления правилами безопасности Firebase.

Независимо от того, какой инструмент используется для вызова, API управления:

  • Принимает источник правил: набор правил, обычно файл кода, содержащий операторы Firebase Security Rules .
  • Сохраняет принятый исходный код как неизменяемый набор правил .
  • Отслеживает развертывание каждого набора правил в релизе . Службы с поддержкой правил безопасности Firebase ищут релиз для проекта, чтобы оценить каждый запрос на защищенный ресурс.
  • Предоставляет возможность проводить синтаксические и семантические тесты набора правил.

Используйте Firebase CLI

С Firebase CLI вы можете загружать локальные источники и развертывать релизы . Firebase Local Emulator Suite CLI позволяет вам выполнять полное локальное тестирование источников .

Использование CLI позволяет вам контролировать версии правил вместе с кодом приложения и развертывать правила как часть существующего процесса развертывания.

Создать файл конфигурации

Когда вы настраиваете свой проект Firebase с помощью Firebase CLI, вы создаете файл конфигурации .rules в каталоге вашего проекта. Используйте следующую команду, чтобы начать настройку вашего проекта 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

Редактируйте и обновляйте свои правила

Отредактируйте источник правил непосредственно в файле конфигурации .rules .

Убедитесь, что любые изменения, которые вы делаете в Firebase CLI, отражаются в консоли Firebase , или что вы последовательно делаете обновления, используя либо консоль Firebase , либо Firebase CLI. В противном случае вы можете перезаписать любые обновления, сделанные в консоли Firebase .

Протестируйте свои обновления

Local Emulator Suite предоставляет эмуляторы для всех продуктов с поддержкой Security Rules. Механизм Security Rules для каждого эмулятора выполняет как синтаксическую, так и семантическую оценку правил, тем самым превосходя синтаксическое тестирование, предлагаемое API управления Security Rules.

Если вы работаете с CLI, Suite — отличный инструмент для тестирования Firebase Security Rules . Используйте Local Emulator Suite для локального тестирования обновлений и подтверждения того, что Rules вашего приложения демонстрируют желаемое поведение.

Разверните ваши обновления

После обновления и тестирования Rules разверните исходные коды в рабочей среде.

Для Cloud Firestore Security Rules свяжите файлы .rules с базами данных по умолчанию и дополнительными именованными базами данных, просмотрев и обновив файл firebase.json .

Используйте следующие команды для выборочного развертывания Rules по отдельности или для их развертывания в рамках обычного процесса развертывания.

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

Используйте консоль Firebase

Вы также можете редактировать источники Rules и развертывать их как релизы из консоли Firebase . Синтаксическое тестирование выполняется по мере редактирования в пользовательском интерфейсе консоли Firebase , а семантическое тестирование доступно с помощью Rules Playground.

Редактируйте и обновляйте свои правила

  1. Откройте консоль Firebase и выберите свой проект.
  2. Затем выберите Realtime Database , Cloud Firestore или Storage в навигации по продукту, затем нажмите Rules , чтобы перейти к редактору Rules .
  3. Редактируйте свои правила прямо в редакторе.

Протестируйте свои обновления

В дополнение к тестированию синтаксиса в пользовательском интерфейсе редактора вы можете тестировать поведение семантических Rules , используя базу данных и ресурсы хранения вашего проекта, непосредственно в консоли Firebase , используя Rules Playground . Откройте экран Rules Playground в редакторе Rules , измените настройки и нажмите Run . Найдите сообщение с подтверждением в верхней части редактора.

Разверните ваши обновления

Как только вы убедитесь, что ваши обновления соответствуют вашим ожиданиям, нажмите «Опубликовать» .

Используйте Admin SDK

Вы можете использовать Admin SDK для наборов правил Node.js. С этим программным доступом вы можете:

  • Внедряйте пользовательские инструменты, скрипты, панели мониторинга и конвейеры CI/CD для управления правилами.
  • Упростите управление правилами в нескольких проектах Firebase.

При программном обновлении правил очень важно избегать внесения непреднамеренных изменений в контроль доступа для вашего приложения. Пишите код Admin SDK , думая прежде всего о безопасности, особенно при обновлении или развертывании правил.

Еще одна важная вещь, которую следует иметь в виду, заключается в том, что для полного распространения релизов Firebase Security Rules требуется несколько минут. При использовании Admin SDK для развертывания правил убедитесь, что избегаете условий гонки, в которых ваше приложение немедленно полагается на правила, развертывание которых еще не завершено. Если ваш вариант использования требует частых обновлений правил контроля доступа, рассмотрите решения с использованием Cloud Firestore , который разработан для уменьшения условий гонки, несмотря на частые обновления.

Также обратите внимание на следующие ограничения:

  • Правила должны быть меньше 256 КБ текста в кодировке UTF-8 при сериализации.
  • Проект может иметь не более 2500 развернутых наборов правил. После достижения этого предела необходимо удалить некоторые старые наборы правил перед созданием новых.

Создание и развертывание наборов правил Cloud Storage или Cloud Firestore

Типичный рабочий процесс управления правилами безопасности с помощью Admin SDK может включать три отдельных шага:

  1. Создать исходный файл правил (необязательно)
  2. Создать набор правил
  3. Выпуск или развертывание нового набора правил

SDK предоставляет метод объединения этих шагов в один вызов API для правил безопасности Cloud Storage и Cloud Firestore . Например:

    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);

Этот же шаблон работает для правил Cloud Storage с releaseFirestoreRulesetFromSource() .

В качестве альтернативы вы можете создать файл правил как объект в памяти, создать набор правил и развернуть набор правил отдельно для более тесного контроля этих событий. Например:

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

Обновление наборов правил Realtime Database

Чтобы обновить наборы правил Realtime Database с помощью Admin SDK , используйте методы getRules() и setRules() admin.database . Вы можете получить наборы правил в формате JSON или в виде строки с включенными комментариями.

Чтобы обновить набор правил:

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

Управление наборами правил

Для управления большими наборами правил Admin SDK позволяет вам перечислить все существующие правила с помощью admin.securityRules().listRulesetMetadata . Например: 

    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;
      }
    }

Для очень больших развертываний, которые со временем достигают предела в 2500 наборов правил, вы можете создать логику для удаления самых старых правил в фиксированном временном цикле. Например, чтобы удалить все наборы правил, развернутые более 30 дней: 

    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.`);

Используйте REST API

Описанные выше инструменты хорошо подходят для различных рабочих процессов, включая управление Firebase Security Rules для нескольких баз данных Cloud Firestore в вашем проекте, но вы можете захотеть управлять и развертывать Firebase Security Rules с помощью самого API управления. API управления дает вам наибольшую гибкость.

Также обратите внимание на следующие ограничения:

  • Правила должны быть меньше 256 КБ текста в кодировке UTF-8 при сериализации.
  • Проект может иметь не более 2500 развернутых наборов правил. После достижения этого предела необходимо удалить некоторые старые наборы правил перед созданием новых.

Создание и развертывание наборов правил Cloud Firestore или Cloud Storage с помощью REST

В примерах в этом разделе используются Rules Firestore, хотя они применимы и к Rules Cloud Storage .

В примерах также используется cURL для выполнения вызовов API. Шаги по настройке и передаче токенов аутентификации опущены. Вы можете поэкспериментировать с этим API, используя API Explorer, интегрированный со справочной документацией.

Типичные шаги по созданию и развертыванию набора правил с использованием API управления:

  1. Создать источники файлов правил
  2. Создать набор правил
  3. Выпустить (развернуть) новый набор правил.

Создать источник

Предположим, вы работаете над проектом Firebase secure_commerce и хотите развернуть заблокированные Rules Cloud Firestore в базе данных вашего проекта с именем east_store .

Вы можете реализовать эти правила в файле firestore.rules . 

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

Создать набор правил

Теперь сгенерируйте отпечаток в кодировке base64 для этого файла. Затем вы можете использовать источник в этом файле для заполнения полезной нагрузки, необходимой для создания набора правил с помощью вызова REST projects.rulesets.create . Здесь используйте команду cat для вставки содержимого firestore.rules в полезную нагрузку REST.

Для отслеживания, чтобы связать это с базой данных east_store , установите для attachment_point 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'

API возвращает ответ проверки и имя набора правил, например projects/secure_commerce/rulesets/uuid123 .

Выпуск (развертывание) набора правил

Если набор правил действителен, последним шагом является развертывание нового набора правил в именованном выпуске. 

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'

Имейте в виду, что для полного распространения релизов Firebase Security Rules требуется несколько минут. При использовании API управления REST для развертывания убедитесь, что вы избегаете условий гонки, в которых ваше приложение немедленно полагается на правила, развертывание которых еще не завершено.

Обновление наборов правил Realtime Database с помощью REST

Realtime Database предоставляет собственный интерфейс REST для управления Rules . См. Управление Rules Firebase Realtime Database через REST .

Управление наборами правил с помощью REST

Для управления большими развертываниями правил, в дополнение к методу REST для создания наборов правил и выпусков, API управления предоставляет методы для:

  • список, получение и удаление наборов правил
  • список, получение и удаление релизов правил

Для очень больших развертываний, которые со временем достигают предела в 2500 наборов правил, вы можете создать логику для удаления самых старых правил в фиксированном временном цикле. Например, чтобы удалить все наборы правил, развернутые более 30 дней, вы можете вызвать метод projects.rulesets.list , проанализировать список JSON объектов Ruleset по их ключам createTime , а затем вызвать project.rulesets.delete для соответствующих наборов правил по ruleset_id .

Тестируйте обновления с помощью REST

Наконец, API управления позволяет вам запускать синтаксические и семантические тесты на ресурсах Cloud Firestore и Cloud Storage в ваших производственных проектах.

Тестирование с помощью этого компонента API состоит из:

  1. Определение объекта TestSuite JSON для представления набора объектов TestCase
  2. Отправка TestSuite
  3. Анализ возвращаемых объектов TestResult

Давайте определим объект TestSuite с одним TestCase в файле testcase.json . В этом примере мы передаем исходный язык Rules в составе полезной нагрузки REST вместе с тестовым набором для запуска по этим правилам. Мы указываем ожидание оценки Rules и клиентский запрос, по которому должен быть протестирован набор правил. Вы также можете указать, насколько полным должен быть тестовый отчет, используя значение «FULL», чтобы указать, что результаты для всех выражений языка Rules должны быть включены в отчет, включая выражения, которые не были сопоставлены с запросом. 

 {
  "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"}}}
            }
          ]
      }
    ]
  }
}

Затем мы можем отправить этот TestSuite на оценку с помощью метода projects.test . 

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

Возвращаемый TestReport (содержащий статус теста SUCCESS/FAILURE, списки отладочных сообщений, списки посещенных выражений правил и их отчеты об оценке) подтвердит со статусом SUCCESS, что доступ разрешен должным образом.

Управление разрешениями для Cloud Storage Security Rules между службами

Если вы создаете Cloud Storage Security Rules , которые используют содержимое документов Cloud Firestore для оценки условий безопасности , вам будет предложено в консоли Firebase или Firebase CLI включить разрешения для подключения двух продуктов.

Если вы решили отключить такую ​​межсервисную безопасность:

  1. Во-первых, перед отключением функции отредактируйте свои правила, удалив все операторы, которые используют функции Rules для доступа к Cloud Firestore . В противном случае после отключения функции оценки Rules приведут к сбою ваших запросов на хранилище.

  2. Используйте страницу IAM в консоли Google Cloud Console, чтобы удалить роль «Firebase Rules Firestore Service Agent», следуя руководству Cloud по отзыву ролей .

Вам будет предложено повторно включить эту функцию при следующем сохранении кросс-сервисных правил из Firebase CLI или консоли Firebase .