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 .
Проверьте свои обновления
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 .
Редактируйте и обновляйте свои правила
- Откройте консоль Firebase и выберите свой проект.
- Затем выберите Realtime Database , Cloud Firestore или «Хранилище» в навигации по продукту, затем нажмите «Правила» , чтобы перейти к редактору Rules .
- Редактируйте свои правила прямо в редакторе.
Проверьте свои обновления
Помимо тестирования синтаксиса в пользовательском интерфейсе редактора, вы можете протестировать семантическое поведение Rules , используя базу данных и ресурсы хранилища вашего проекта, непосредственно в консоли Firebase , используя игровую площадку Rules . Откройте экран «Площадка правил» в редакторе Rules , измените настройки и нажмите «Выполнить» . Найдите сообщение с подтверждением в верхней части редактора.
Развертывание обновлений
Если вы уверены, что ваши обновления соответствуют ожиданиям, нажмите «Опубликовать» .
Используйте 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 может включать три отдельных шага:
- Создайте источник файла правил (необязательно)
- Создать набор правил
- Выпустить или развернуть новый набор правил
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 управления:
- Создание источников файлов правил
- Создать набор правил
- Выпустите (разверните) новый набор правил.
Создать источник
Предположим, вы работаете над своим проектом 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 состоит из:
- Определение объекта
TestSuite
JSON для представления набора объектовTestCase
. - Отправка
TestSuite
- Анализ возвращаемых объектов
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 включить разрешения для подключения двух продуктов.
Если вы решите отключить такую межсервисную безопасность:
Во-первых, прежде чем отключать эту функцию, отредактируйте свои правила, удалив все операторы, которые используют функции Rules для доступа к Cloud Firestore . В противном случае после отключения этой функции оценки Rules приведут к сбою запросов к хранилищу.
Используйте страницу IAM в Google Cloud Console, чтобы удалить роль «Агент службы Firestore правил Firebase», следуя руководству по отзыву ролей в Cloud .
Вам будет предложено повторно включить эту функцию при следующем сохранении межсервисных правил из интерфейса командной строки Firebase или консоли Firebase .