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

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

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

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

Используйте интерфейс командной строки Firebase

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

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

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

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

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

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

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

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

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

Примечание. Когда вы развертываете правила безопасности с помощью Firebase CLI , правила, определенные в каталоге вашего проекта, перезаписывают любые существующие правила в консоли Firebase . Итак, если вы решите определить или отредактировать свои правила безопасности с помощью консоли Firebase , обязательно обновите правила, определенные в каталоге вашего проекта.

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

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

Развертывание обновлений

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

Используйте SDK администратора

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

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

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

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

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

Примечание. Хотя теперь можно выполнять модульное тестирование ваших правил с помощью локальных эмуляторов Cloud Firestore и Realtime Database , тестирование недоступно через этот SDK. Если вы хотите убедиться, что ваши правила проверены перед развертыванием, мы не рекомендуем обновлять правила с помощью Admin SDK .

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

• Правила должны быть меньше 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 управления обеспечивает максимальную гибкость.

Примечание. В этом разделе описаны основные варианты использования управления, аналогичные представленным выше. Дополнительные варианты использования и примеры, доступные с этим API, см. в полной справочной документации REST 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'

Примечание. Для выпуска в базу данных (по умолчанию) путь projects/ /releases/cloud.firestore/(default) projects/ /releases/cloud.firestore/(default) эквивалентно projects/ /releases/cloud.firestore projects/ /releases/cloud.firestore .

Имейте в виду, что для полного распространения выпусков 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 в ваших производственных проектах.

Примечание. Тесты, выполняемые с использованием REST API, используют рабочие базы данных, сегменты хранилища и связанные ресурсы. За такое тестирование может взиматься плата за использование. Мы настоятельно рекомендуем вам использовать Firebase Local Emulator Suite для тестирования Firebase Security Rules , поскольку вы можете запускать тесты на автономных непроизводственных ресурсах без платы за использование. См. наше руководство по тестированию Firebase Security Rules с помощью Local Emulator Suite .

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

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

Давайте определим объект TestSuite с одним TestCase в файле testcase.json . В этом примере мы передаем исходный код языка Rules вместе с полезной нагрузкой REST вместе с набором тестов для выполнения этих правил. Мы указываем ожидание оценки правил и запрос клиента, по которому должен тестироваться набор правил. Вы также можете указать, насколько полным является отчет о тестировании, используя значение «ПОЛНЫЙ», чтобы указать, что в отчет должны быть включены результаты для всех выражений языка 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, чтобы удалить роль «Агент службы Firestore правил Firebase», следуя руководству по отзыву ролей в Cloud .

   Примечание. На странице IAM установите флажок «Включить предоставленные Google роли», чтобы просмотреть все роли.
   Примечание. На странице IAM вы должны найти учетную запись службы хранилища Firebase, идентификатор которой заканчивается на @gcp-sa-firebasestorage.iam.gserviceaccount.com . Если кросс-сервисные правила включены, вы увидите в списке роль «Агент службы Firestore правил Firebase».

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