Catch up on highlights from Firebase at Google I/O 2023. Learn more

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

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

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

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

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

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

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

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

Когда вы настраиваете свой проект Firebase с помощью интерфейса командной строки Firebase, вы создаете файл конфигурации .rules в каталоге вашего проекта. Используйте следующую команду, чтобы начать настройку проекта Firebase:

Облако Firestore

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

База данных реального времени

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

Облачное хранилище

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

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

Отредактируйте источник правил непосредственно в файле конфигурации .rules . Убедитесь, что любые изменения, которые вы вносите в интерфейсе командной строки Firebase, отражаются в консоли Firebase, или что вы последовательно вносите обновления с помощью консоли Firebase или интерфейса командной строки Firebase. В противном случае вы можете перезаписать любые обновления, сделанные в консоли Firebase.

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

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

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

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

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

Облако Firestore

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

База данных реального времени

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

Облачное хранилище

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

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

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

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

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

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

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

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

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

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

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

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

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

Еще одна важная вещь, о которой следует помнить, это то, что для полного распространения выпусков правил безопасности Firebase требуется несколько минут. При использовании 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);

Тот же шаблон работает для правил облачного хранилища с помощью releaseFirestoreRulesetFromSource() .

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

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

Обновление наборов правил базы данных реального времени

Чтобы обновить наборы правил базы данных реального времени с помощью 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 и развертывать их с помощью самого API управления. API управления обеспечивает максимальную гибкость.

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

Также обратите внимание на эти ограничения:

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

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

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

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

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

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

Предположим, вы работаете над проектом secure_commerce Firebase и хотите развернуть заблокированные правила облачного хранилища. Вы можете реализовать эти правила в файле storage.rules .

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

Теперь сгенерируйте для этого файла отпечаток в кодировке base64. Затем вы можете использовать исходный код в этом файле для заполнения полезной нагрузки, необходимой для создания набора правил, с помощью REST-вызова projects.rulesets.create . Здесь мы используем команду cat для вставки содержимого storage.rules в полезную нагрузку 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'

API возвращает ответ проверки и имя набора правил, например projects/secure_commerce/rulesets/uuid123 . Если набор правил действителен, последним шагом будет развертывание нового набора правил в именованном выпуске.

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'

Обновление наборов правил базы данных реального времени с помощью REST

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

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

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

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

Для очень больших развертываний, которые со временем достигают предела в 2500 наборов правил, вы можете создать логику для удаления самых старых правил в фиксированном цикле времени. Например, чтобы удалить все наборы правил, развернутые более 30 дней, вы можете вызвать метод projects.rulesets.list , проанализировать список объектов Ruleset в формате JSON по их ключам 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 вместе с набором тестов для запуска этих правил. Мы указываем ожидание оценки правил и запрос клиента, по которому должен тестироваться набор правил. Вы также можете указать, насколько полным является отчет о тестировании, используя значение «ПОЛНЫЙ», чтобы указать результаты для всех языковых выражений правил, которые должны быть включены в отчет, включая выражения, которые не были сопоставлены с запросом.

 {
  "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, списки отладочных сообщений, списки посещенных выражений Rules и их отчеты об оценке) будет подтверждать статусом SUCCESS, что доступ разрешен должным образом.

Управление разрешениями для межсервисных правил безопасности облачного хранилища

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

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

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

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

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