Управление и развертывание правил безопасности 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 предоставляет эмуляторы для всех продуктов с поддержкой правил безопасности. Механизм правил безопасности для каждого эмулятора выполняет как синтаксическую, так и семантическую оценку правил, тем самым превосходя возможности синтаксического тестирования, предлагаемые API управления правилами безопасности.

Если вы работаете с CLI, этот набор — отличный инструмент для тестирования 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 .

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

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

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

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

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

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

Используйте 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 в вашем проекте, но вы можете использовать API управления и развёртывать 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. Выпустить (развернуть) новый набор правил.

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

Предположим, вы работаете над проектом secure_commerce Firebase и хотите развернуть заблокированные 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 занимает несколько минут. При использовании REST API управления для развёртывания убедитесь, что ваше приложение не использует правила, развёртывание которых ещё не завершено, в условиях гонки.

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

Realtime Database предоставляет собственный интерфейс REST для управления Rules . См. раздел Управление Rules 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 вместе с набором тестов для выполнения этих правил. Мы указываем ожидаемое значение оценки правил и клиентский запрос, на основе которого будет тестироваться набор правил. Вы также можете указать полноту отчёта о тестировании, используя значение «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 .