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 .
,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 .
,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 . Откройте экран Playground Playground 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.`);
Используйте API REST
Инструменты, описанные выше, хорошо подходят для различных рабочих процессов, включая управление Firebase Security Rules для нескольких баз данных Cloud Firestore в вашем проекте, но вы можете управлять и развернуть Firebase Security Rules используя сам управление API. API управления дает вам наибольшую гибкость.
Также обратите внимание на эти ограничения:
- Правила должны быть меньше 256 киб из кодированного UTF-8 текста при сериализовании.
- Проект может иметь не более 2500 общих развернутых наборов правил. Как только этот предел достигнут, вы должны удалить несколько старых наборов правил, прежде чем создавать новые.
Создать и развернуть Cloud Firestore или Cloud Storage с отдыхом
Примеры в этом разделе используют 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 для этого файла. Затем вы можете использовать источник в этом файле для заполнения полезной нагрузки, необходимой для создания набора правил с помощью вызова projects.rulesets.create
REST. Здесь используйте команду cat
, чтобы вставить содержимое firestore.rules
в полезную нагрузку.
Для отслеживания, чтобы связать это с вашей базой данных 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 Management для развертывания убедитесь, что вы можете избежать условий гонки, в которых ваше приложение немедленно опирается на правила, развертывание которых еще не завершено.
Обновить правила правил Realtime Database .
Realtime Database предоставляет свой собственный интерфейс REST для управления Rules . См. Управление Rules Realtime Database через отдых .
Управление наборами правил с отдыхом
Чтобы помочь управлять развертываниями крупных правил, в дополнение к методу отдыха для создания наборов правил и выпусков, API управления предоставляет методы:
- Список, получить и удалить наборы правил
- Список, получить и удалять выбросы правил
Для очень больших развертываний, которые со временем достигают предела набора правил 2500, вы можете создать логику для удаления самых старых правил в фиксированном временном цикле. Ruleset
, чтобы удалить все наборы правил ruleset_id
развернутые в createTime
более 30 дней, вы можете позвонить в метод projects.rulesets.list
project.rulesets.delete
.
Проверьте свои обновления с отдыхом
Наконец, API управления позволяет вам запускать синтаксические и семантические тесты на Cloud Firestore и Cloud Storage в ваших производственных проектах.
Тестирование с этим компонентом API состоит из:
- Определение объекта
TestSuite
JSON для представления набора объектовTestCase
- Отправление
TestSuite
- Санирование возврата объектов
TestResult
Давайте определим объект TestSuite
с одним TestCase
в файле testcase.json
. В этом примере мы передаем источник языка Rules , встроенный в соответствии с полезной нагрузкой, наряду с тестовым набором для работы по этим правилам. Мы указываем ожидание оценки правил и запрос клиента, на который должен быть проверен набор правил. Вы также можете указать, насколько закончен тестовый отчет, используя «полное», чтобы указать результаты для всех выражений языка 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
(содержащий успех теста/статус неудачи, списки сообщений отладки, списки выраженных правил и их отчетов о оценке) подтвердили бы успех статуса, что доступ к доступу правильно разрешен.
Управление разрешениями для Cloud Storage Security Rules межсетистого обслуживания
Если вы создаете Cloud Storage Security Rules , которые используют содержимое документа Cloud Firestore для оценки условий безопасности , вам будет предложено в консоли Firebase или CLI Firebase , чтобы позволить разрешения для подключения двух продуктов.
Если вы решите отключить такую безопасность поперечного спектра:
Во -первых, прежде чем отключить функцию, отредактируйте свои правила, удалив все операторы, которые используют функции Rules для доступа к Cloud Firestore . В противном случае, после того, как функция отключена, оценки Rules приведут к сбою ваших запросов на хранение.
Используйте страницу IAM в Cloud Console Google, чтобы удалить роль «Агент FireBase Rules Firestore», следуя руководству по облаку для отмены ролей .
Вам будет предложено повторно включить функцию в следующий раз, когда вы сохраните правила поперечного обслуживания от CLI Firebase или консоли Firebase .
,Firebase предоставляет вам несколько инструментов для управления вашими Rules , каждый из которых полезен в конкретных случаях, и каждый из них использует один и тот же API управления правилами безопасности Firebase Firebase.
Независимо от того, какой инструмент используется для его вызова, API управления:
- Принимает источник правил: набор правил, как правило, файл кода, содержащий операторы Firebase Security Rules .
- Магазины проглатывали источник в качестве неизменного набора правил .
- Отслеживает развертывание каждого набора правил в выпуске . Службы безопасности Firebase Security Services ищут релиз для проекта для оценки каждого запроса на защищенный ресурс.
- Предоставляет возможность запускать синтаксические и семантические тесты набора правил.
Используйте CLI Firebase
С помощью CLI Firebase вы можете загрузить местные источники и развернуть релизы . Компания CLI Firebase Local Emulator Suite позволяет вам провести полное локальное тестирование источников .
Использование CLI позволяет вам сохранять ваши правила в контроле версий с помощью кода приложения и развертывания правил в рамках вашего существующего процесса развертывания.
Создать файл конфигурации
Когда вы настраиваете свой проект Firebase с использованием CLI 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
.
Убедитесь, что любые изменения, которые вы вносите в CLI Firebase , отражены в консоли Firebase или что вы постоянно делаете обновления, используя либо консоль Firebase , либо CLI Firebase. В противном случае вы можете перезаписать любые обновления, сделанные в консоли Firebase .
Проверьте свои обновления
Local Emulator Suite предоставляет эмуляторы для всех продуктов с поддержкой правил безопасности. Двигатель правил безопасности для каждого эмулятора выполняет как синтаксическую, так и семантическую оценку правил, тем самым превышая синтаксическое тестирование, предлагаемое API управления правилами безопасности.
Если вы работаете с CLI, набор является отличным инструментом для тестирования Firebase Security Rules . Используйте Local Emulator Suite , чтобы проверить ваши обновления локально и подтвердить, что Rules вашего приложения демонстрируют желаемое поведение.
Разверните ваши обновления
После того, как вы обновили и протестировали свои Rules , разверните источники для производства.
Для Cloud Firestore Security Rules , Associate .rules
Files с вашим по умолчанию и дополнительным именованным базам данных, просмотрев и обновляя свой файл 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 Console, а семантическое тестирование доступно с использованием игровой площадки Rules .
Изменить и обновить свои правила
- Откройте консоль Firebase и выберите свой проект.
- Затем выберите Realtime Database , Cloud Firestore или хранилище в навигации продукта, затем нажмите «Правила» , чтобы перейти к редактору Rules .
- Измените свои правила непосредственно в редакторе.
Проверьте свои обновления
Помимо синтаксиса тестирования в пользовательском интерфейсе редактора, вы можете проверить поведение семантических Rules , используя базу данных и ресурсы для хранения вашего проекта, непосредственно в консоли Firebase , используя игровую площадку Rules . Откройте экран Playground Playground 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.`);
Используйте API REST
Инструменты, описанные выше, хорошо подходят для различных рабочих процессов, включая управление Firebase Security Rules для нескольких баз данных Cloud Firestore в вашем проекте, но вы можете управлять и развернуть Firebase Security Rules используя сам управление API. API управления дает вам наибольшую гибкость.
Также обратите внимание на эти ограничения:
- Правила должны быть меньше 256 киб из кодированного UTF-8 текста при сериализовании.
- Проект может иметь не более 2500 общих развернутых наборов правил. Как только этот предел достигнут, вы должны удалить несколько старых наборов правил, прежде чем создавать новые.
Создать и развернуть Cloud Firestore или Cloud Storage с отдыхом
Примеры в этом разделе используют 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 для этого файла. Затем вы можете использовать источник в этом файле для заполнения полезной нагрузки, необходимой для создания набора правил с помощью вызова projects.rulesets.create
REST. Здесь используйте команду cat
, чтобы вставить содержимое firestore.rules
в полезную нагрузку.
Для отслеживания, чтобы связать это с вашей базой данных 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 Management для развертывания убедитесь, что вы можете избежать условий гонки, в которых ваше приложение немедленно опирается на правила, развертывание которых еще не завершено.
Обновить правила правил Realtime Database .
Realtime Database предоставляет свой собственный интерфейс REST для управления Rules . См. Управление Rules Realtime Database через отдых .
Управление наборами правил с отдыхом
Чтобы помочь управлять развертываниями крупных правил, в дополнение к методу отдыха для создания наборов правил и выпусков, API управления предоставляет методы:
- Список, получить и удалить наборы правил
- Список, получить и удалять выбросы правил
Для очень больших развертываний, которые со временем достигают предела набора правил 2500, вы можете создать логику для удаления самых старых правил в фиксированном временном цикле. Ruleset
, чтобы удалить все наборы правил ruleset_id
развернутые в createTime
более 30 дней, вы можете позвонить в метод projects.rulesets.list
project.rulesets.delete
.
Проверьте свои обновления с отдыхом
Наконец, API управления позволяет вам запускать синтаксические и семантические тесты на Cloud Firestore и Cloud Storage в ваших производственных проектах.
Тестирование с этим компонентом API состоит из:
- Определение объекта
TestSuite
JSON для представления набора объектовTestCase
- Отправление
TestSuite
- Санирование возврата объектов
TestResult
Давайте определим объект TestSuite
с одним TestCase
в файле testcase.json
. В этом примере мы передаем источник языка Rules , встроенный в соответствии с полезной нагрузкой, наряду с тестовым набором для работы по этим правилам. Мы указываем ожидание оценки правил и запрос клиента, на который должен быть проверен набор правил. Вы также можете указать, насколько закончен тестовый отчет, используя «полное», чтобы указать результаты для всех выражений языка 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
(содержащий успех теста/статус неудачи, списки сообщений отладки, списки выраженных правил и их отчетов о оценке) подтвердили бы успех статуса, что доступ к доступу правильно разрешен.
Управление разрешениями для Cloud Storage Security Rules межсетистого обслуживания
Если вы создаете Cloud Storage Security Rules , которые используют содержимое документа Cloud Firestore для оценки условий безопасности , вам будет предложено в консоли Firebase или CLI Firebase , чтобы позволить разрешения для подключения двух продуктов.
Если вы решите отключить такую безопасность поперечного спектра:
Во -первых, прежде чем отключить функцию, отредактируйте свои правила, удалив все операторы, которые используют функции Rules для доступа к Cloud Firestore . В противном случае, после того, как функция отключена, оценки Rules приведут к сбою ваших запросов на хранение.
Используйте страницу IAM в Cloud Console Google, чтобы удалить роль «Агент FireBase Rules Firestore», следуя руководству по облаку для отмены ролей .
Вам будет предложено повторно включить функцию в следующий раз, когда вы сохраните правила поперечного обслуживания от CLI Firebase или консоли Firebase .