Язык правил безопасности

Firebase Security Rules используют гибкие, мощные, настраиваемые языки, которые поддерживают широкий диапазон сложности и детализации. Вы можете сделать свои Rules настолько конкретными или настолько общими, насколько это целесообразно для вашего приложения. Правила Realtime Database используют синтаксис, похожий на JavaScript в структуре JSON. В правилах Cloud Firestore и Cloud Storage используется язык, основанный на языке общих выражений (CEL) , который основан на CEL с операторами match allow , поддерживающими условно предоставленный доступ.

Однако, поскольку это специальные языки, существует кривая обучения. Используйте это руководство, чтобы лучше понять язык Rules и глубже погрузиться в более сложные правила.

Выберите продукт, чтобы узнать больше о его правилах.

Базовая структура

Cloud Firestore

Firebase Security Rules в Cloud Firestore и Cloud Storage используют следующую структуру и синтаксис:

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

При разработке правил важно понимать следующие ключевые понятия:

  • Запрос: метод или методы, вызываемые в операторе allow . Это методы, которые вы разрешаете запускать. Стандартные методы: get , list , create , update и delete . Удобные методы read и write обеспечивают широкий доступ для чтения и записи в указанной базе данных или пути хранения.
  • Путь: база данных или место хранения, представленное в виде пути URI.
  • Правило: оператор allow , который включает условие, разрешающее запрос, если его значение истинно.

Каждая из этих концепций более подробно описана ниже.

Cloud Storage

Firebase Security Rules в Cloud Firestore и Cloud Storage используют следующую структуру и синтаксис:

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

При разработке правил важно понимать следующие ключевые понятия:

  • Запрос: метод или методы, вызываемые в операторе allow . Это методы, которые вы разрешаете запускать. Стандартные методы: get , list , create , update и delete . Удобные методы read и write обеспечивают широкий доступ для чтения и записи в указанной базе данных или пути хранения.
  • Путь: база данных или место хранения, представленное в виде пути URI.
  • Правило: оператор allow , который включает условие, разрешающее запрос, если его значение истинно.

Каждая из этих концепций более подробно описана ниже.

Realtime Database

В Realtime Database Firebase Security Rules состоят из выражений, подобных JavaScript, содержащихся в документе JSON.

Они используют следующий синтаксис:

{
  "rules": {
    "<<path>>": {
    // Allow the request if the condition for each method is true.
      ".read": <<condition>>,
      ".write": <<condition>>,
      ".validate": <<condition>>
    }
  }
}

В правиле есть три основных элемента:

  • Путь: расположение базы данных. Это отражает структуру JSON вашей базы данных.
  • Запрос: это методы, которые правило использует для предоставления доступа. Правила read и write предоставляют широкий доступ для чтения и записи, а правила validate действуют как вторичная проверка для предоставления доступа на основе входящих или существующих данных.
  • Условие: условие, которое разрешает запрос, если его значение истинно.

Конструкции правил

Cloud Firestore

Основные элементы правила в Cloud Firestore и Cloud Storage следующие:

  • Декларация service : объявляет продукт Firebase, к которому применяются правила.
  • Блок match : определяет путь в базе данных или сегменте хранилища, к которому применяются правила.
  • Оператор allow : предоставляет условия предоставления доступа, различающиеся по методам. Поддерживаемые методы включают: get , list , create , update , delete , а также удобные методы read и write .
  • Необязательные объявления function : предоставьте возможность комбинировать и обертывать условия для использования в нескольких правилах.

service содержит один или несколько блоков match с операторами allow , предоставляющими условия предоставления доступа к запросам. Переменные request и resource доступны для использования в условиях правила. Язык Firebase Security Rules также поддерживает объявления function .

Версия синтаксиса

Оператор syntax указывает версию языка правил Firebase, использованного для написания источника. Последняя версия языка — v2 .

rules_version = '2';
service cloud.firestore {
...
}

Если оператор rules_version не указан, ваши правила будут оцениваться с использованием механизма v1 .

Услуга

Декларация service определяет, к какому продукту или услуге Firebase применяются ваши правила. Вы можете включить только одно объявление service в исходный файл.

Cloud Firestore

service cloud.firestore {
 // Your 'match' blocks with their corresponding 'allow' statements and
 // optional 'function' declarations are contained here
}

Cloud Storage

service firebase.storage {
  // Your 'match' blocks with their corresponding 'allow' statements and
  // optional 'function' declarations are contained here
}

Если вы определяете правила как для Cloud Firestore , так и для Cloud Storage с помощью интерфейса командной строки Firebase , вам придется хранить их в отдельных файлах.

Соответствовать

Блок match объявляет шаблон path , который сопоставляется с путем для запрошенной операции (входящий request.path ). Тело match должно содержать один или несколько вложенных блоков match , allow разрешения или объявлений function . Путь во вложенных блоках match указывается относительно пути в родительском блоке match .

Шаблон path — это имя, подобное каталогу, которое может включать переменные или подстановочные знаки. Шаблон path допускает совпадение сегментов с одним и несколькими путями. Любые переменные, связанные с path , видны в области match или любой вложенной области, где объявлен path .

Совпадения с шаблоном path могут быть частичными или полными:

  • Частичные совпадения: шаблон path представляет собой совпадение префикса request.path .
  • Полные совпадения: шаблон path соответствует всему request.path .

При полном совпадении оцениваются правила внутри блока. При частичном совпадении проверяются вложенные правила match , чтобы определить, завершит ли совпадение какой-либо вложенный path .

Правила в каждом полном match оцениваются, чтобы определить, разрешить ли запрос. Если какое-либо соответствующее правило предоставляет доступ, запрос разрешается. Если ни одно соответствующее правило не предоставляет доступ, запрос отклоняется.

// Given request.path == /example/hello/nested/path the following
// declarations indicate whether they are a partial or complete match and
// the value of any variables visible within the scope.
service firebase.storage {
  // Partial match.
  match /example/{singleSegment} {   // `singleSegment` == 'hello'
    allow write;                     // Write rule not evaluated.
    // Complete match.
    match /nested/path {             // `singleSegment` visible in scope.
      allow read;                    // Read rule is evaluated.
    }
  }
  // Complete match.
  match /example/{multiSegment=**} { // `multiSegment` == /hello/nested/path
    allow read;                      // Read rule is evaluated.
  }
}

Как показано в приведенном выше примере, объявления path поддерживают следующие переменные:

  • Односегментный подстановочный знак: переменная подстановочного знака объявляется в пути путем заключения переменной в фигурные скобки: {variable} . Эта переменная доступна в операторе match как string .
  • Рекурсивный подстановочный знак: рекурсивный или многосегментный подстановочный знак соответствует нескольким сегментам пути на пути или под ним. Этот подстановочный знак соответствует всем путям ниже заданного вами местоположения. Вы можете объявить это, добавив строку =** в конец переменной сегмента: {variable=**} . Эта переменная доступна в операторе match как объект path .

Позволять

Блок match содержит один или несколько операторов allow . Это ваши настоящие правила. Вы можете применить allow правила к одному или нескольким методам. Условия оператора allow должны иметь значение true, чтобы Cloud Firestore или Cloud Storage могли удовлетворить любой входящий запрос. Вы также можете писать операторы allow без условий, например, allow read . Однако если оператор allow не включает условие, он всегда разрешает запрос этого метода.

Если какое-либо из allow правил для метода удовлетворено, запрос разрешается. Кроме того, если более широкое правило предоставляет доступ, Rules предоставляют доступ и игнорируют более детальные правила, которые могут ограничивать доступ.

Рассмотрим следующий пример, где любой пользователь может читать или удалять любые свои файлы. Более детальное правило разрешает запись только в том случае, если пользователь, запрашивающий запись, является владельцем файла и файл имеет формат PNG. Пользователь может удалить любые файлы в подпути — даже если они не являются PNG — поскольку предыдущее правило это разрешает.

service firebase.storage {
  // Allow the requestor to read or delete any resource on a path under the
  // user directory.
  match /users/{userId}/{anyUserFile=**} {
    allow read, delete: if request.auth != null && request.auth.uid == userId;
  }

  // Allow the requestor to create or update their own images.
  // When 'request.method' == 'delete' this rule and the one matching
  // any path under the user directory would both match and the `delete`
  // would be permitted.

  match /users/{userId}/images/{imageId} {
    // Whether to permit the request depends on the logical OR of all
    // matched rules. This means that even if this rule did not explicitly
    // allow the 'delete' the earlier rule would have.
    allow write: if request.auth != null && request.auth.uid == userId && imageId.matches('*.png');
  }
}

Метод

Каждый оператор allow включает в себя метод, который предоставляет доступ для входящих запросов того же метода.

Метод Тип запроса
Удобные методы
read Любой тип запроса на чтение
write Любой тип запроса на запись
Стандартные методы
get Запросы на чтение отдельных документов или файлов
list Чтение запросов на запросы и коллекции
create Запись новых документов или файлов
update Запись в существующие документы базы данных или обновление метаданных файлов.
delete Удалить данные

Вы не можете перекрывать методы чтения в одном и том же блоке match или конфликтующие методы записи в одном объявлении path .

Например, следующие правила не будут выполнены:

service bad.example {
  match /rules/with/overlapping/methods {
    // This rule allows reads to all authenticated users
    allow read: if request.auth != null;

    match another/subpath {
      // This secondary, more specific read rule causes an error
      allow get: if request.auth != null && request.auth.uid == "me";
      // Overlapping write methods in the same path cause an error as well
      allow write: if request.auth != null;
      allow create: if request.auth != null && request.auth.uid == "me";
    }
  }
}

Функция

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

  • Функции могут содержать только один оператор return . Они не могут содержать никакой дополнительной логики. Например, они не могут выполнять циклы или вызывать внешние службы.
  • Функции могут автоматически получать доступ к функциям и переменным из области, в которой они определены. Например, функция, определенная в области видимости service cloud.firestore , имеет доступ к переменной resource и встроенным функциям, таким как get() и exists() .
  • Функции могут вызывать другие функции, но не могут выполняться рекурсивно. Общая глубина стека вызовов ограничена 20.
  • В правилах версии v2 функции могут определять переменные с помощью ключевого слова let . Функции могут иметь до 10 привязок let, но должны заканчиваться оператором return.

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

service cloud.firestore {
  match /databases/{database}/documents {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }

    match /cities/{city} {
      allow read, write: if signedInOrPublic();
    }

    match /users/{user} {
      allow read, write: if signedInOrPublic();
    }
  }
}

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

function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  let isAdmin = exists(/databases/$(database)/documents/admins/$(userId));
  return isAuthor || isAdmin;
}

Обратите внимание, как назначение isAdmin обеспечивает поиск коллекции администраторов. Для отложенных вычислений без необходимости ненужных поисков воспользуйтесь преимуществами короткого замыкания && (AND) и || (ИЛИ) сравнения для вызова второй функции только в том случае, если isAuthor равно true (для сравнений && ) или false (для сравнений || ).

function isAdmin(userId) {
  return exists(/databases/$(database)/documents/admins/$(userId));
}
function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  // `||` is short-circuiting; isAdmin called only if isAuthor == false.
  return isAuthor || isAdmin(userId);
}

Использование функций в правилах безопасности делает их более удобными в обслуживании по мере роста сложности правил.

Cloud Storage

Основные элементы правила в Cloud Firestore и Cloud Storage следующие:

  • Декларация service : объявляет продукт Firebase, к которому применяются правила.
  • Блок match : определяет путь в базе данных или сегменте хранилища, к которому применяются правила.
  • Оператор allow : предоставляет условия предоставления доступа, различающиеся по методам. Поддерживаемые методы включают: get , list , create , update , delete , а также удобные методы read и write .
  • Необязательные объявления function : предоставьте возможность комбинировать и обертывать условия для использования в нескольких правилах.

service содержит один или несколько блоков match с операторами allow , предоставляющими условия предоставления доступа к запросам. Переменные request и resource доступны для использования в условиях правила. Язык Firebase Security Rules также поддерживает объявления function .

Версия синтаксиса

Оператор syntax указывает версию языка правил Firebase, использованного для написания источника. Последняя версия языка — v2 .

rules_version = '2';
service cloud.firestore {
...
}

Если оператор rules_version не указан, ваши правила будут оцениваться с использованием механизма v1 .

Услуга

Декларация service определяет, к какому продукту или услуге Firebase применяются ваши правила. Вы можете включить только одно объявление service в исходный файл.

Cloud Firestore

service cloud.firestore {
 // Your 'match' blocks with their corresponding 'allow' statements and
 // optional 'function' declarations are contained here
}

Cloud Storage

service firebase.storage {
  // Your 'match' blocks with their corresponding 'allow' statements and
  // optional 'function' declarations are contained here
}

Если вы определяете правила как для Cloud Firestore , так и для Cloud Storage с помощью интерфейса командной строки Firebase , вам придется хранить их в отдельных файлах.

Соответствовать

Блок match объявляет шаблон path , который сопоставляется с путем для запрошенной операции (входящий request.path ). Тело match должно содержать один или несколько вложенных блоков match , allow разрешения или объявлений function . Путь во вложенных блоках match указывается относительно пути в родительском блоке match .

Шаблон path — это имя, подобное каталогу, которое может включать переменные или подстановочные знаки. Шаблон path допускает совпадение сегментов с одним и несколькими путями. Любые переменные, связанные с path , видны в области match или любой вложенной области, где объявлен path .

Совпадения с шаблоном path могут быть частичными или полными:

  • Частичные совпадения: шаблон path представляет собой совпадение префикса request.path .
  • Полные совпадения: шаблон path соответствует всему request.path .

При полном совпадении оцениваются правила внутри блока. При частичном совпадении проверяются вложенные правила match , чтобы определить, завершит ли совпадение какой-либо вложенный path .

Правила в каждом полном match оцениваются, чтобы определить, разрешить ли запрос. Если какое-либо соответствующее правило предоставляет доступ, запрос разрешается. Если ни одно соответствующее правило не предоставляет доступ, запрос отклоняется.

// Given request.path == /example/hello/nested/path the following
// declarations indicate whether they are a partial or complete match and
// the value of any variables visible within the scope.
service firebase.storage {
  // Partial match.
  match /example/{singleSegment} {   // `singleSegment` == 'hello'
    allow write;                     // Write rule not evaluated.
    // Complete match.
    match /nested/path {             // `singleSegment` visible in scope.
      allow read;                    // Read rule is evaluated.
    }
  }
  // Complete match.
  match /example/{multiSegment=**} { // `multiSegment` == /hello/nested/path
    allow read;                      // Read rule is evaluated.
  }
}

Как показано в приведенном выше примере, объявления path поддерживают следующие переменные:

  • Односегментный подстановочный знак: переменная подстановочного знака объявляется в пути путем заключения переменной в фигурные скобки: {variable} . Эта переменная доступна в операторе match как string .
  • Рекурсивный подстановочный знак: рекурсивный или многосегментный подстановочный знак соответствует нескольким сегментам пути на пути или под ним. Этот подстановочный знак соответствует всем путям ниже заданного вами местоположения. Вы можете объявить это, добавив строку =** в конец переменной сегмента: {variable=**} . Эта переменная доступна в операторе match как объект path .

Позволять

Блок match содержит один или несколько операторов allow . Это ваши настоящие правила. Вы можете применить allow правила к одному или нескольким методам. Условия оператора allow должны иметь значение true, чтобы Cloud Firestore или Cloud Storage могли удовлетворить любой входящий запрос. Вы также можете писать операторы allow без условий, например, allow read . Однако если оператор allow не включает условие, он всегда разрешает запрос этого метода.

Если какое-либо из allow правил для метода удовлетворено, запрос разрешается. Кроме того, если более широкое правило предоставляет доступ, Rules предоставляют доступ и игнорируют более детальные правила, которые могут ограничивать доступ.

Рассмотрим следующий пример, где любой пользователь может читать или удалять любые свои файлы. Более детальное правило разрешает запись только в том случае, если пользователь, запрашивающий запись, является владельцем файла и файл имеет формат PNG. Пользователь может удалить любые файлы в подпути — даже если они не являются PNG — поскольку предыдущее правило это разрешает.

service firebase.storage {
  // Allow the requestor to read or delete any resource on a path under the
  // user directory.
  match /users/{userId}/{anyUserFile=**} {
    allow read, delete: if request.auth != null && request.auth.uid == userId;
  }

  // Allow the requestor to create or update their own images.
  // When 'request.method' == 'delete' this rule and the one matching
  // any path under the user directory would both match and the `delete`
  // would be permitted.

  match /users/{userId}/images/{imageId} {
    // Whether to permit the request depends on the logical OR of all
    // matched rules. This means that even if this rule did not explicitly
    // allow the 'delete' the earlier rule would have.
    allow write: if request.auth != null && request.auth.uid == userId && imageId.matches('*.png');
  }
}

Метод

Каждый оператор allow включает в себя метод, который предоставляет доступ для входящих запросов того же метода.

Метод Тип запроса
Удобные методы
read Любой тип запроса на чтение
write Любой тип запроса на запись
Стандартные методы
get Запросы на чтение отдельных документов или файлов
list Чтение запросов на запросы и коллекции
create Запись новых документов или файлов
update Запись в существующие документы базы данных или обновление метаданных файлов.
delete Удалить данные

Вы не можете перекрывать методы чтения в одном и том же блоке match или конфликтующие методы записи в одном объявлении path .

Например, следующие правила не будут выполнены:

service bad.example {
  match /rules/with/overlapping/methods {
    // This rule allows reads to all authenticated users
    allow read: if request.auth != null;

    match another/subpath {
      // This secondary, more specific read rule causes an error
      allow get: if request.auth != null && request.auth.uid == "me";
      // Overlapping write methods in the same path cause an error as well
      allow write: if request.auth != null;
      allow create: if request.auth != null && request.auth.uid == "me";
    }
  }
}

Функция

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

  • Функции могут содержать только один оператор return . Они не могут содержать никакой дополнительной логики. Например, они не могут выполнять циклы или вызывать внешние службы.
  • Функции могут автоматически получать доступ к функциям и переменным из области, в которой они определены. Например, функция, определенная в области видимости service cloud.firestore , имеет доступ к переменной resource и встроенным функциям, таким как get() и exists() .
  • Функции могут вызывать другие функции, но не могут выполняться рекурсивно. Общая глубина стека вызовов ограничена 20.
  • В правилах версии v2 функции могут определять переменные с помощью ключевого слова let . Функции могут иметь до 10 привязок let, но должны заканчиваться оператором return.

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

service cloud.firestore {
  match /databases/{database}/documents {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }

    match /cities/{city} {
      allow read, write: if signedInOrPublic();
    }

    match /users/{user} {
      allow read, write: if signedInOrPublic();
    }
  }
}

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

function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  let isAdmin = exists(/databases/$(database)/documents/admins/$(userId));
  return isAuthor || isAdmin;
}

Обратите внимание, как назначение isAdmin обеспечивает поиск коллекции администраторов. Для отложенных вычислений без необходимости ненужных поисков воспользуйтесь преимуществами короткого замыкания && (AND) и || (ИЛИ) сравнения для вызова второй функции только в том случае, если isAuthor равно true (для сравнений && ) или false (для сравнений || ).

function isAdmin(userId) {
  return exists(/databases/$(database)/documents/admins/$(userId));
}
function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  // `||` is short-circuiting; isAdmin called only if isAuthor == false.
  return isAuthor || isAdmin(userId);
}

Использование функций в правилах безопасности делает их более удобными в обслуживании по мере роста сложности правил.

Realtime Database

Как указано выше, Rules Realtime Database включают три основных элемента: расположение базы данных как зеркало структуры JSON базы данных, тип запроса и условие предоставления доступа.

Расположение базы данных

Структура ваших правил должна соответствовать структуре данных, которые вы храните в своей базе данных. Например, в приложении чата со списком сообщений у вас могут быть такие данные:

  {
    "messages": {
      "message0": {
        "content": "Hello",
        "timestamp": 1405704370369
      },
      "message1": {
        "content": "Goodbye",
        "timestamp": 1405704395231
      },
      ...
    }
  }

Ваши правила должны отражать эту структуру. Например:

  {
    "rules": {
      "messages": {
        "$message": {
          // only messages from the last ten minutes can be read
          ".read": "data.child('timestamp').val() > (now - 600000)",

          // new messages must have a string content and a number timestamp
          ".validate": "newData.hasChildren(['content', 'timestamp']) &&
                        newData.child('content').isString() &&
                        newData.child('timestamp').isNumber()"
        }
      }
    }
  }

Как показано в приведенном выше примере, Rules Realtime Database поддерживают переменную $location для сопоставления сегментов пути. Используйте префикс $ перед сегментом пути, чтобы сопоставить правило с любыми дочерними узлами на пути.

  {
    "rules": {
      "rooms": {
        // This rule applies to any child of /rooms/, the key for each room id
        // is stored inside $room_id variable for reference
        "$room_id": {
          "topic": {
            // The room's topic can be changed if the room id has "public" in it
            ".write": "$room_id.contains('public')"
          }
        }
      }
    }
  }

Вы также можете использовать $variable параллельно с именами констант.

  {
    "rules": {
      "widget": {
        // a widget can have a title or color attribute
        "title": { ".validate": true },
        "color": { ".validate": true },

        // but no other child paths are allowed
        // in this case, $other means any key excluding "title" and "color"
        "$other": { ".validate": false }
      }
    }
  }

Метод

В Realtime Database существует три типа правил. Два из этих типов правил — read и write — применяются к методу входящего запроса. Тип правила validate обеспечивает соблюдение структур данных и проверяет формат и содержимое данных. Rules запускают правила .validate после проверки того, что правило .write предоставляет доступ.

Типы правил
.читать Описывает, разрешено ли пользователям читать данные и когда это возможно.
.писать Описывает, разрешена ли запись данных и когда это возможно.
.валидатировать Определяет, как будет выглядеть правильно отформатированное значение, есть ли у него дочерние атрибуты и тип данных.

По умолчанию, если правило не разрешает это, доступ по пути запрещен.

Условия строительства

Cloud Firestore

Условие — это логическое выражение, которое определяет, следует ли разрешить или запретить конкретную операцию. Переменные request и resource предоставляют контекст для этих условий.

Переменная request

Переменная request включает в себя следующие поля и соответствующую информацию:

request.auth

Веб-токен JSON (JWT), содержащий учетные данные аутентификации из Firebase Authentication . Токен auth содержит набор стандартных утверждений и любых пользовательских утверждений, которые вы создаете с помощью Firebase Authentication . Узнайте больше о правилах безопасности и Authentication Firebase Security Rules .

request.method

request.method может быть любым стандартным методом или пользовательским методом. Удобные методы read и write также существуют для упрощения правил записи, которые применяются ко всем стандартным методам только для чтения или ко всем стандартным методам только для записи соответственно.

request.params

request.params включает в себя любые данные, не связанные конкретно с request.resource , которые могут быть полезны для оценки. На практике эта карта должна быть пустой для всех стандартных методов и должна содержать нересурсные данные для пользовательских методов. Службы должны быть осторожны, чтобы не переименовывать и не изменять тип каких-либо ключей и значений, представленных в качестве параметров.

request.path

request.path — это путь к целевому resource . Путь указывается относительно сервиса. Сегменты пути, содержащие небезопасные для URL-адреса символы, такие как / закодированы в URL-адресе.

resource переменная

resource — это текущее значение в сервисе, представленное в виде карты пар ключ-значение. Ссылка на resource в условии приведет не более к одному чтению значения из службы. Этот поиск будет учитываться в любой квоте, связанной со службой, для ресурса. Для запросов get resource будет учитываться только в квоте при отклонении.

Операторы и приоритет операторов

Используйте приведенную ниже таблицу в качестве справки для операторов и их соответствующего приоритета в Rules для Cloud Firestore и Cloud Storage .

Даны произвольные выражения a и b , поле f и индекс i .

Оператор Описание Ассоциативность
a[i] a() af Индекс, вызов, доступ к полям слева направо
!a -a Унарное отрицание справа налево
a/ba%ba*b Мультипликативные операторы слева направо
a+b ab Аддитивные операторы слева направо
a>ba>=ba Реляционные операторы слева направо
a in b Наличие в списке или на карте слева направо
a is type Сравнение типов, где type может быть bool, int, float, число, строка, список, карта, временная метка, продолжительность, путь или широта. слева направо
a==ba!=b Операторы сравнения слева направо
a && b Условное И слева направо
a || b Условное ИЛИ слева направо
a ? true_value : false_value Тернарное выражение слева направо

Cloud Storage

Условие — это логическое выражение, которое определяет, следует ли разрешить или запретить конкретную операцию. Переменные request и resource предоставляют контекст для этих условий.

Переменная request

Переменная request включает в себя следующие поля и соответствующую информацию:

request.auth

Веб-токен JSON (JWT), содержащий учетные данные аутентификации из Firebase Authentication . Токен auth содержит набор стандартных утверждений и любых пользовательских утверждений, которые вы создаете с помощью Firebase Authentication . Узнайте больше о правилах безопасности и Authentication Firebase Security Rules .

request.method

request.method может быть любым стандартным методом или пользовательским методом. Удобные методы read и write также существуют для упрощения правил записи, которые применяются ко всем стандартным методам только для чтения или ко всем стандартным методам только для записи соответственно.

request.params

request.params включает в себя любые данные, не связанные конкретно с request.resource , которые могут быть полезны для оценки. На практике эта карта должна быть пустой для всех стандартных методов и должна содержать нересурсные данные для пользовательских методов. Службы должны быть осторожны, чтобы не переименовывать и не изменять тип каких-либо ключей и значений, представленных в качестве параметров.

request.path

request.path — это путь к целевому resource . Путь указывается относительно сервиса. Сегменты пути, содержащие небезопасные для URL-адреса символы, такие как / закодированы в URL-адресе.

resource переменная

resource — это текущее значение в сервисе, представленное в виде карты пар ключ-значение. Ссылка на resource в условии приведет не более к одному чтению значения из службы. Этот поиск будет учитываться в любой квоте, связанной со службой, для ресурса. Для запросов get resource будет учитываться только в квоте при отклонении.

Операторы и приоритет операторов

Используйте приведенную ниже таблицу в качестве справки для операторов и их соответствующего приоритета в Rules для Cloud Firestore и Cloud Storage .

Даны произвольные выражения a и b , поле f и индекс i .

Оператор Описание Ассоциативность
a[i] a() af Индекс, вызов, доступ к полям слева направо
!a -a Унарное отрицание справа налево
a/ba%ba*b Мультипликативные операторы слева направо
a+b ab Аддитивные операторы слева направо
a>ba>=ba Реляционные операторы слева направо
a in b Наличие в списке или на карте слева направо
a is type Сравнение типов, где type может быть bool, int, float, число, строка, список, карта, временная метка, продолжительность, путь или широта. слева направо
a==ba!=b Операторы сравнения слева направо
a && b Условное И слева направо
a || b Условное ИЛИ слева направо
a ? true_value : false_value Тернарное выражение слева направо

Realtime Database

Условие — это логическое выражение, которое определяет, следует ли разрешить или запретить конкретную операцию. Вы можете определить эти условия в Rules Realtime Database следующими способами.

Предопределенные переменные

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

Предопределенные переменные
сейчас Текущее время в миллисекундах с эпохи Linux. Это особенно хорошо работает для проверки временных меток, созданных с помощью Firebase.database.ServerValue.TIMESTAMP SDK.
корень RuleDataSnapshot , представляющий корневой путь в базе данных Firebase, существовавший до попытки операции.
новые данные RuleDataSnapshot, представляющий данные в том виде, в каком они будут существовать после предпринятой операции. Он включает в себя новые записываемые данные и существующие данные.
данные RuleDataSnapshot, представляющий данные в том виде, в каком они существовали до предпринятой операции.
$переменные Путь с подстановочными знаками, используемый для представления идентификаторов и динамических дочерних ключей.
авторизация Представляет полезную нагрузку токена прошедшего проверку подлинности пользователя.

Эти переменные можно использовать где угодно в ваших правилах. Например, приведенные ниже правила безопасности гарантируют, что данные, записываемые в узел /foo/ , должны представлять собой строку длиной менее 100 символов:

{
  "rules": {
    "foo": {
      // /foo is readable by the world
      ".read": true,

      // /foo is writable by the world
      ".write": true,

      // data written to /foo must be a string less than 100 characters
      ".validate": "newData.isString() && newData.val().length < 100"
    }
  }
}

Правила на основе данных

Любые данные в вашей базе данных могут использоваться в ваших правилах. Используя предопределенные переменные root , data и newData , вы можете получить доступ к любому пути, который существовал бы до или после события записи.

Рассмотрим этот пример, который разрешает операции записи, пока значение узла /allow_writes/ равно true , у родительского узла не установлен флаг readOnly и во вновь записанных данных есть дочерний узел с именем foo :

".write": "root.child('allow_writes').val() === true &&
          !data.parent().child('readOnly').exists() &&
          newData.child('foo').exists()"

Правила на основе запросов

Хотя вы не можете использовать правила в качестве фильтров, вы можете ограничить доступ к подмножествам данных, используя параметры запроса в своих правилах. Используйте query. выражения в ваших правилах для предоставления доступа на чтение или запись на основе параметров запроса.

Например, следующее правило на основе запроса использует правила безопасности на основе пользователей и правила на основе запросов, чтобы ограничить доступ к данным в коллекции baskets только корзинами покупок, принадлежащими активному пользователю:

"baskets": {
  ".read": "auth.uid !== null &&
            query.orderByChild === 'owner' &&
            query.equalTo === auth.uid" // restrict basket access to owner of basket
}

Следующий запрос, включающий параметры запроса в правило, будет успешным:

db.ref("baskets").orderByChild("owner")
                 .equalTo(auth.currentUser.uid)
                 .on("value", cb)                 // Would succeed

Однако запросы, которые не включают параметры в правило, завершатся ошибкой PermissionDenied :

db.ref("baskets").on("value", cb)                 // Would fail with PermissionDenied

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

Например, следующее правило ограничивает доступ для чтения только к первым 1000 результатам запроса, упорядоченным по приоритету:

messages: {
  ".read": "query.orderByKey &&
            query.limitToFirst <= 1000"
}

// Example queries:

db.ref("messages").on("value", cb)                // Would fail with PermissionDenied

db.ref("messages").limitToFirst(1000)
                  .on("value", cb)                // Would succeed (default order by key)

Следующий query. выражения доступны в Realtime Database Security Rules .

Выражения правил на основе запросов
Выражение Тип Описание
query.orderByKey
query.orderByPriority
query.orderByValue
логическое значение Верно для запросов, упорядоченных по ключу, приоритету или значению. В противном случае неверно.
query.orderByChild нить
нулевой
Используйте строку для представления относительного пути к дочернему узлу. Например, query.orderByChild === "address/zip" . Если запрос не упорядочен дочерним узлом, это значение равно нулю.
запрос.startAt
запрос.endAt
запрос.equalTo
нить
число
логическое значение
нулевой
Извлекает границы выполняющегося запроса или возвращает значение NULL, если набор границ отсутствует.
query.limitToFirst
query.limitToLast
число
нулевой
Получает ограничение на выполнение запроса или возвращает значение NULL, если ограничение не установлено.

Операторы

Rules Realtime Database поддерживают ряд операторов , которые можно использовать для объединения переменных в операторе условия. Полный список операторов смотрите в справочной документации .

Создание условий

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

Некоторые рекомендации по созданию простых, готовых к использованию Rules см. в разделе «Основные правила безопасности» .

,

Firebase Security Rules используют гибкие, мощные, настраиваемые языки, которые поддерживают широкий диапазон сложности и детализации. Вы можете сделать свои Rules настолько конкретными или настолько общими, насколько это целесообразно для вашего приложения. Правила Realtime Database используют синтаксис, похожий на JavaScript в структуре JSON. В правилах Cloud Firestore и Cloud Storage используется язык, основанный на языке общих выражений (CEL) , который основан на CEL с операторами match allow , поддерживающими условно предоставленный доступ.

Однако, поскольку это специальные языки, существует кривая обучения. Используйте это руководство, чтобы лучше понять язык Rules и глубже погрузиться в более сложные правила.

Выберите продукт, чтобы узнать больше о его правилах.

Базовая структура

Cloud Firestore

Firebase Security Rules в Cloud Firestore и Cloud Storage используют следующую структуру и синтаксис:

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

При разработке правил важно понимать следующие ключевые понятия:

  • Запрос: метод или методы, вызываемые в операторе allow . Это методы, которые вы разрешаете запускать. Стандартные методы: get , list , create , update и delete . Удобные методы read и write обеспечивают широкий доступ для чтения и записи в указанной базе данных или пути хранения.
  • Путь: база данных или место хранения, представленное в виде пути URI.
  • Правило: оператор allow , который включает условие, разрешающее запрос, если его значение истинно.

Каждая из этих концепций более подробно описана ниже.

Cloud Storage

Firebase Security Rules в Cloud Firestore и Cloud Storage используют следующую структуру и синтаксис:

service <<name>> {
  // Match the resource path.
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}

При разработке правил важно понимать следующие ключевые понятия:

  • Запрос: метод или методы, вызываемые в операторе allow . Это методы, которые вы разрешаете запускать. Стандартные методы: get , list , create , update и delete . Удобные методы read и write обеспечивают широкий доступ для чтения и записи в указанной базе данных или пути хранения.
  • Путь: база данных или место хранения, представленное в виде пути URI.
  • Правило: оператор allow , который включает условие, разрешающее запрос, если его значение истинно.

Каждая из этих концепций более подробно описана ниже.

Realtime Database

В Realtime Database Firebase Security Rules состоят из выражений, подобных JavaScript, содержащихся в документе JSON.

Они используют следующий синтаксис:

{
  "rules": {
    "<<path>>": {
    // Allow the request if the condition for each method is true.
      ".read": <<condition>>,
      ".write": <<condition>>,
      ".validate": <<condition>>
    }
  }
}

В правиле есть три основных элемента:

  • Путь: расположение базы данных. Это отражает структуру JSON вашей базы данных.
  • Запрос: это методы, которые правило использует для предоставления доступа. Правила read и write предоставляют широкий доступ для чтения и записи, а правила validate действуют как вторичная проверка для предоставления доступа на основе входящих или существующих данных.
  • Условие: условие, которое разрешает запрос, если его значение истинно.

Конструкции правил

Cloud Firestore

Основные элементы правила в Cloud Firestore и Cloud Storage следующие:

  • Декларация service : объявляет продукт Firebase, к которому применяются правила.
  • Блок match : определяет путь в базе данных или сегменте хранилища, к которому применяются правила.
  • Оператор allow : предоставляет условия предоставления доступа, различающиеся по методам. Поддерживаемые методы включают: get , list , create , update , delete , а также удобные методы read и write .
  • Необязательные объявления function : предоставьте возможность комбинировать и обертывать условия для использования в нескольких правилах.

service содержит один или несколько блоков match с операторами allow , предоставляющими условия предоставления доступа к запросам. Переменные request и resource доступны для использования в условиях правила. Язык Firebase Security Rules также поддерживает объявления function .

Версия синтаксиса

Оператор syntax указывает версию языка правил Firebase, использованного для написания источника. Последняя версия языка — v2 .

rules_version = '2';
service cloud.firestore {
...
}

Если оператор rules_version не указан, ваши правила будут оцениваться с использованием механизма v1 .

Услуга

Декларация service определяет, к какому продукту или услуге Firebase применяются ваши правила. Вы можете включить только одно объявление service в исходный файл.

Cloud Firestore

service cloud.firestore {
 // Your 'match' blocks with their corresponding 'allow' statements and
 // optional 'function' declarations are contained here
}

Cloud Storage

service firebase.storage {
  // Your 'match' blocks with their corresponding 'allow' statements and
  // optional 'function' declarations are contained here
}

Если вы определяете правила как для Cloud Firestore , так и для Cloud Storage с помощью интерфейса командной строки Firebase , вам придется хранить их в отдельных файлах.

Соответствовать

Блок match объявляет шаблон path , который сопоставляется с путем для запрошенной операции (входящий request.path ). Тело match должно содержать один или несколько вложенных блоков match , allow разрешения или объявлений function . Путь во вложенных блоках match указывается относительно пути в родительском блоке match .

Шаблон path — это имя, подобное каталогу, которое может включать переменные или подстановочные знаки. Шаблон path допускает совпадение сегментов с одним и несколькими путями. Любые переменные, связанные с path , видны в области match или любой вложенной области, где объявлен path .

Совпадения с шаблоном path могут быть частичными или полными:

  • Частичные совпадения: шаблон path представляет собой совпадение префикса request.path .
  • Полные совпадения: шаблон path соответствует всему request.path .

При полном совпадении оцениваются правила внутри блока. При частичном совпадении проверяются вложенные правила match , чтобы определить, завершит ли совпадение какой-либо вложенный path .

Правила в каждом полном match оцениваются, чтобы определить, разрешить ли запрос. Если какое-либо соответствующее правило предоставляет доступ, запрос разрешается. Если ни одно соответствующее правило не предоставляет доступ, запрос отклоняется.

// Given request.path == /example/hello/nested/path the following
// declarations indicate whether they are a partial or complete match and
// the value of any variables visible within the scope.
service firebase.storage {
  // Partial match.
  match /example/{singleSegment} {   // `singleSegment` == 'hello'
    allow write;                     // Write rule not evaluated.
    // Complete match.
    match /nested/path {             // `singleSegment` visible in scope.
      allow read;                    // Read rule is evaluated.
    }
  }
  // Complete match.
  match /example/{multiSegment=**} { // `multiSegment` == /hello/nested/path
    allow read;                      // Read rule is evaluated.
  }
}

Как показано в приведенном выше примере, объявления path поддерживают следующие переменные:

  • Односегментный подстановочный знак: переменная подстановочного знака объявляется в пути путем заключения переменной в фигурные скобки: {variable} . Эта переменная доступна в операторе match как string .
  • Рекурсивный подстановочный знак: рекурсивный или многосегментный подстановочный знак соответствует нескольким сегментам пути на пути или под ним. Этот подстановочный знак соответствует всем путям ниже заданного вами местоположения. Вы можете объявить это, добавив строку =** в конец переменной сегмента: {variable=**} . Эта переменная доступна в операторе match как объект path .

Позволять

Блок match содержит один или несколько операторов allow . Это ваши настоящие правила. Вы можете применить allow правила к одному или нескольким методам. Условия оператора allow должны иметь значение true, чтобы Cloud Firestore или Cloud Storage могли удовлетворить любой входящий запрос. Вы также можете писать операторы allow без условий, например, allow read . Однако если оператор allow не включает условие, он всегда разрешает запрос этого метода.

Если какое-либо из allow правил для метода удовлетворено, запрос разрешается. Кроме того, если более широкое правило предоставляет доступ, Rules предоставляют доступ и игнорируют более детальные правила, которые могут ограничивать доступ.

Рассмотрим следующий пример, где любой пользователь может читать или удалять любые свои файлы. Более детальное правило разрешает запись только в том случае, если пользователь, запрашивающий запись, является владельцем файла и файл имеет формат PNG. Пользователь может удалить любые файлы в подпути — даже если они не являются PNG — поскольку предыдущее правило это разрешает.

service firebase.storage {
  // Allow the requestor to read or delete any resource on a path under the
  // user directory.
  match /users/{userId}/{anyUserFile=**} {
    allow read, delete: if request.auth != null && request.auth.uid == userId;
  }

  // Allow the requestor to create or update their own images.
  // When 'request.method' == 'delete' this rule and the one matching
  // any path under the user directory would both match and the `delete`
  // would be permitted.

  match /users/{userId}/images/{imageId} {
    // Whether to permit the request depends on the logical OR of all
    // matched rules. This means that even if this rule did not explicitly
    // allow the 'delete' the earlier rule would have.
    allow write: if request.auth != null && request.auth.uid == userId && imageId.matches('*.png');
  }
}

Метод

Каждый оператор allow включает в себя метод, который предоставляет доступ для входящих запросов того же метода.

Метод Тип запроса
Удобные методы
read Любой тип запроса на чтение
write Любой тип запроса на запись
Стандартные методы
get Запросы на чтение отдельных документов или файлов
list Чтение запросов на запросы и коллекции
create Запись новых документов или файлов
update Запись в существующие документы базы данных или обновление метаданных файлов.
delete Удалить данные

Вы не можете перекрывать методы чтения в одном и том же блоке match или в противоречивых методах записи в том же объявлении path .

Например, следующие правила потерпят неудачу:

service bad.example {
  match /rules/with/overlapping/methods {
    // This rule allows reads to all authenticated users
    allow read: if request.auth != null;

    match another/subpath {
      // This secondary, more specific read rule causes an error
      allow get: if request.auth != null && request.auth.uid == "me";
      // Overlapping write methods in the same path cause an error as well
      allow write: if request.auth != null;
      allow create: if request.auth != null && request.auth.uid == "me";
    }
  }
}

Функция

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

  • Функции могут содержать только один оператор return . Они не могут содержать никакой дополнительной логики. Например, они не могут выполнять циклы или вызывать внешние службы.
  • Функции могут автоматически получать доступ к функциям и переменным из области, в которой они определены. Например, функция resource get() в service cloud.firestore exists()
  • Функции могут вызывать другие функции, но не могут выполняться рекурсивно. Общая глубина стека вызовов ограничена 20.
  • В версии правил v2 функции могут определять переменные, используя ключевое слово let . Функции могут иметь до 10 привязков, но должны заканчиваться оператором возврата.

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

service cloud.firestore {
  match /databases/{database}/documents {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }

    match /cities/{city} {
      allow read, write: if signedInOrPublic();
    }

    match /users/{user} {
      allow read, write: if signedInOrPublic();
    }
  }
}

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

function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  let isAdmin = exists(/databases/$(database)/documents/admins/$(userId));
  return isAuthor || isAdmin;
}

Обратите внимание, как задание isAdmin обеспечивает поиск коллекции администраторов. Для ленивой оценки, не требуя ненужных поисков, воспользуйтесь преимуществами короткого замыкающего характера && (и) и || (Или) сравнения, чтобы вызвать вторую функцию только в том случае, если isAuthor показан как TRUE (для && сравнения) или false (для сравнения || ).

function isAdmin(userId) {
  return exists(/databases/$(database)/documents/admins/$(userId));
}
function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  // `||` is short-circuiting; isAdmin called only if isAuthor == false.
  return isAuthor || isAdmin(userId);
}

Использование функций в ваших правилах безопасности делает их более поддерживаемыми по мере роста сложности ваших правил.

Cloud Storage

Основные элементы правила в Cloud Firestore и Cloud Storage заключаются в следующем:

  • Объявление service : объявляет продукт Firebase, к которому применяются правила.
  • Блок match : определяет путь в базе данных или ведро для хранения, к которым применяются правила.
  • Заявление allow : обеспечивает условия для предоставления доступа, дифференцированного методами. Поддерживаемые методы включают в себя: get , list , create , update , delete и методы удобства read и write .
  • Дополнительные объявления function : предоставьте возможность объединять и обернуть условия для использования по нескольким правилам.

service содержит один или несколько блоков match с заявлениями allow , которые предоставляют условия, предоставляющие доступ к запросам. Переменные request и resource доступны для использования в условиях правила. Язык Firebase Security Rules также поддерживает function объявления.

Синтаксическая версия

Оператор syntax указывает на версию языка правил Firebase, используемой для написания источника. Последняя версия языка - v2 .

rules_version = '2';
service cloud.firestore {
...
}

Если утверждение rules_version не будет предоставлено, ваши правила будут оцениваться с использованием двигателя v1 .

Услуга

Объявление service определяет, к какому продукту или услуги Firebase применяются ваши правила. Вы можете включить только одно объявление service на исходный файл.

Cloud Firestore

service cloud.firestore {
 // Your 'match' blocks with their corresponding 'allow' statements and
 // optional 'function' declarations are contained here
}

Cloud Storage

service firebase.storage {
  // Your 'match' blocks with their corresponding 'allow' statements and
  // optional 'function' declarations are contained here
}

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

Соответствовать

Блок match объявляет шаблон path , который сочетается с пути для запрошенной операции (входящий request.path ). Тело match должно иметь один или несколько вложенных блоков match , allow операторы или объявления function . Путь в вложенных блоках match относительно пути в родительском блоке match .

Паттерн path -это название, похожее на каталог, которое может включать переменные или подстановочные знаки. Паттерн path позволяет сопоставить сегмент с одним путем и многоцелевой сегмент. Любые переменные, связанные в path , видны в рамках match или в любой вложенной области, где провозглашается path .

Совпадения с шаблоном path могут быть частичными или полными:

  • Частичные совпадения: шаблон path является префиксом Match of request.path .
  • Полные совпадения: шаблон path соответствует всем request.path .

Когда выполняется полное совпадение, оцениваются правила в блоке. Когда частичное совпадение сделано, вложенные правила match проверены, чтобы увидеть, завершит ли какой -либо вложенный path .

Правила в каждом полном match оцениваются, чтобы определить, разрешать ли запрос. Если какое -либо соответствующее правило предоставляет доступ, запрос разрешен. Если нет соответствующего правила, запрос отрицается.

// Given request.path == /example/hello/nested/path the following
// declarations indicate whether they are a partial or complete match and
// the value of any variables visible within the scope.
service firebase.storage {
  // Partial match.
  match /example/{singleSegment} {   // `singleSegment` == 'hello'
    allow write;                     // Write rule not evaluated.
    // Complete match.
    match /nested/path {             // `singleSegment` visible in scope.
      allow read;                    // Read rule is evaluated.
    }
  }
  // Complete match.
  match /example/{multiSegment=**} { // `multiSegment` == /hello/nested/path
    allow read;                      // Read rule is evaluated.
  }
}

Как приведен выше пример, объявления path подтверждают следующие переменные:

  • Односегментный подстановочный знак: переменная подстановочного знака объявляется в пути путем обертывания переменной в кудрявые скобки: {variable} . Эта переменная доступна в операторе match в виде string .
  • Рекурсивный подстановка: рекурсивный или многосегментный, подстановочный знак соответствует нескольким сегментам пути на пути или ниже. Этот подстановочный знак соответствует всем путям под местом, на которое вы его установили. Вы можете объявить его, добавив строку =** в конце переменной сегмента: {variable=**} . Эта переменная доступна в операторе match в качестве объекта path .

Позволять

Блок match содержит одно или несколько allow . Это ваши реальные правила. Вы можете применить allow правил одного или нескольких методов. Условия в соответствии с утверждением allow должны оцениваться до True для Cloud Firestore или Cloud Storage чтобы предоставить любой входящий запрос. Например, вы также можете allow операторы без условий, allow read . Однако, если оператор allow не включает условие, он всегда позволяет запросить этот метод.

Если какое -либо из правил allow для метода будет выполнено, запрос разрешен. Кроме того, если более широкое правило предоставляет доступ, Rules предоставляют доступ и игнорируют какие -либо более детальные правила, которые могут ограничить доступ.

Рассмотрим следующий пример, когда любой пользователь может читать или удалять любой из своих собственных файлов. Более детальное правило разрешает записи только в том случае, если пользователь, запрашивающий файл, владеет файлом, а файл - PNG. Пользователь может удалить любые файлы в подстойке - даже если он не PNGS - потому что более раннее правило позволяет.

service firebase.storage {
  // Allow the requestor to read or delete any resource on a path under the
  // user directory.
  match /users/{userId}/{anyUserFile=**} {
    allow read, delete: if request.auth != null && request.auth.uid == userId;
  }

  // Allow the requestor to create or update their own images.
  // When 'request.method' == 'delete' this rule and the one matching
  // any path under the user directory would both match and the `delete`
  // would be permitted.

  match /users/{userId}/images/{imageId} {
    // Whether to permit the request depends on the logical OR of all
    // matched rules. This means that even if this rule did not explicitly
    // allow the 'delete' the earlier rule would have.
    allow write: if request.auth != null && request.auth.uid == userId && imageId.matches('*.png');
  }
}

Метод

Каждое утверждение allow включает в себя метод, который предоставляет доступ для входящих запросов того же метода.

Метод Тип запроса
Удобные методы
read Любой тип запроса на чтение
write Любой тип запроса на запись
Стандартные методы
get Читать запросы на отдельные документы или файлы
list Прочитать запросы на запросы и коллекции
create Написать новые документы или файлы
update Записать в существующие документы базы данных или обновлять метаданные файла
delete Удалить данные

Вы не можете перекрывать методы чтения в одном и том же блоке match или в противоречивых методах записи в том же объявлении path .

Например, следующие правила потерпят неудачу:

service bad.example {
  match /rules/with/overlapping/methods {
    // This rule allows reads to all authenticated users
    allow read: if request.auth != null;

    match another/subpath {
      // This secondary, more specific read rule causes an error
      allow get: if request.auth != null && request.auth.uid == "me";
      // Overlapping write methods in the same path cause an error as well
      allow write: if request.auth != null;
      allow create: if request.auth != null && request.auth.uid == "me";
    }
  }
}

Функция

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

  • Функции могут содержать только один оператор return . Они не могут содержать никакой дополнительной логики. Например, они не могут выполнять циклы или вызывать внешние службы.
  • Функции могут автоматически получать доступ к функциям и переменным из области, в которой они определены. Например, функция resource get() в service cloud.firestore exists()
  • Функции могут вызывать другие функции, но не могут выполняться рекурсивно. Общая глубина стека вызовов ограничена 20.
  • В версии правил v2 функции могут определять переменные, используя ключевое слово let . Функции могут иметь до 10 привязков, но должны заканчиваться оператором возврата.

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

service cloud.firestore {
  match /databases/{database}/documents {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }

    match /cities/{city} {
      allow read, write: if signedInOrPublic();
    }

    match /users/{user} {
      allow read, write: if signedInOrPublic();
    }
  }
}

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

function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  let isAdmin = exists(/databases/$(database)/documents/admins/$(userId));
  return isAuthor || isAdmin;
}

Обратите внимание, как задание isAdmin обеспечивает поиск коллекции администраторов. Для ленивой оценки, не требуя ненужных поисков, воспользуйтесь преимуществами короткого замыкающего характера && (и) и || (Или) сравнения, чтобы вызвать вторую функцию только в том случае, если isAuthor показан как TRUE (для && сравнения) или false (для сравнения || ).

function isAdmin(userId) {
  return exists(/databases/$(database)/documents/admins/$(userId));
}
function isAuthorOrAdmin(userId, article) {
  let isAuthor = article.author == userId;
  // `||` is short-circuiting; isAdmin called only if isAuthor == false.
  return isAuthor || isAdmin(userId);
}

Использование функций в ваших правилах безопасности делает их более поддерживаемыми по мере роста сложности ваших правил.

Realtime Database

Как указано выше, Rules Realtime Database включают три основных элемента: местоположение базы данных в качестве зеркала структуры JSON базы данных, типа запроса и условия предоставления доступа.

Расположение базы данных

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

  {
    "messages": {
      "message0": {
        "content": "Hello",
        "timestamp": 1405704370369
      },
      "message1": {
        "content": "Goodbye",
        "timestamp": 1405704395231
      },
      ...
    }
  }

Ваши правила должны отражать эту структуру. Например:

  {
    "rules": {
      "messages": {
        "$message": {
          // only messages from the last ten minutes can be read
          ".read": "data.child('timestamp').val() > (now - 600000)",

          // new messages must have a string content and a number timestamp
          ".validate": "newData.hasChildren(['content', 'timestamp']) &&
                        newData.child('content').isString() &&
                        newData.child('timestamp').isNumber()"
        }
      }
    }
  }

Как показано приведенном выше примере, Rules Realtime Database поддерживают переменную A $location в соответствии с сегментами пути. Используйте префикс $ перед сегментом своего пути, чтобы соответствовать вашим правилу с любыми дочерними узлами вдоль пути.

  {
    "rules": {
      "rooms": {
        // This rule applies to any child of /rooms/, the key for each room id
        // is stored inside $room_id variable for reference
        "$room_id": {
          "topic": {
            // The room's topic can be changed if the room id has "public" in it
            ".write": "$room_id.contains('public')"
          }
        }
      }
    }
  }

Вы также можете использовать $variable параллельно с именами постоянных путей.

  {
    "rules": {
      "widget": {
        // a widget can have a title or color attribute
        "title": { ".validate": true },
        "color": { ".validate": true },

        // but no other child paths are allowed
        // in this case, $other means any key excluding "title" and "color"
        "$other": { ".validate": false }
      }
    }
  }

Метод

В Realtime Database существует три типа правил. Два из этих типов правил - read и write - применить метод входящего запроса. Тип правила validate обеспечивает соблюдение структур данных и проверяет формат и содержание данных. Rules .write .validate

Типы правил
.читать Описывает, разрешено ли пользователям читать данные и когда это возможно.
.писать Описывает, разрешена ли запись данных и когда это возможно.
.валидатировать Определяет, как будет выглядеть правильно отформатированное значение, есть ли у него дочерние атрибуты и тип данных.

По умолчанию, если его не разрешает правило, доступ к пути отрицается.

Условия здания

Cloud Firestore

Условие — это логическое выражение, которое определяет, следует ли разрешить или запретить конкретную операцию. Переменные request и resource обеспечивают контекст для этих условий.

Переменная request

Переменная request включает в себя следующие поля и соответствующую информацию:

request.auth

Веб -токен JSON (JWT), который содержит учетные данные аутентификации от Firebase Authentication . auth Token содержит набор стандартных претензий и любые пользовательские претензии, которые вы создаете с помощью Firebase Authentication . Узнайте больше о Firebase Security Rules и Authentication .

request.method

request.method может быть любым из стандартных методов или пользовательского метода. Методы удобства read и write , чтобы упростить правила письма, которые применяются ко всем только для чтения или всем стандартным методам только для записи соответственно.

request.params

request.params включают любые данные, не связанные с request.resource , которые могут быть полезны для оценки. На практике эта карта должна быть пустой для всех стандартных методов и должна содержать данные не ресурсов для пользовательских методов. Службы должны быть осторожны, чтобы не переименовать и не изменять тип любых ключей и значений, представленных как параметры.

request.path

request.path Переход - это путь для целевого resource . Путь относится к услуге. Сегменты пути, содержащие невозможные безопасные символы, такие как / кодируются URL.

Переменная resource

resource является текущим значением в службе, представленной в виде карты пар клавиш. Ссылка на resource в условиях приведет к максимум одному чтению значения из Сервиса. Этот поиск будет учитываться против любой квоты, связанной с обслуживанием, для ресурса. Для get запросов resource будет учитываться только к квоте в отказе.

Операторы и приоритет оператора

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

Учитывая произвольные выражения a и b , поле f и индекс i .

Оператор Описание Ассоциативность
a[i] a() af Индекс, вызов, доступ к полю слева направо
!a -a Единое отрицание справа налево
a/ba%ba*b Мультипликативные операторы слева направо
a+b ab Аддитивные операторы слева направо
a>ba>=ba Реляционные операторы слева направо
a in b Существование в списке или карте слева направо
a is type Сравнение типа, где type может быть Bool, Int, Float, Number, String, List, Map, TimeStamp, продолжительность, путь или латлнг слева направо
a==ba!=b Операторы сравнения слева направо
a && b Условно и слева направо
a || b Условное или слева направо
a ? true_value : false_value Тройное выражение слева направо

Cloud Storage

Условие — это логическое выражение, которое определяет, следует ли разрешить или запретить конкретную операцию. Переменные request и resource обеспечивают контекст для этих условий.

Переменная request

Переменная request включает в себя следующие поля и соответствующую информацию:

request.auth

Веб -токен JSON (JWT), который содержит учетные данные аутентификации от Firebase Authentication . auth Token содержит набор стандартных претензий и любые пользовательские претензии, которые вы создаете с помощью Firebase Authentication . Узнайте больше о Firebase Security Rules и Authentication .

request.method

request.method может быть любым из стандартных методов или пользовательского метода. Методы удобства read и write , чтобы упростить правила письма, которые применяются ко всем только для чтения или всем стандартным методам только для записи соответственно.

request.params

request.params включают любые данные, не связанные с request.resource , которые могут быть полезны для оценки. На практике эта карта должна быть пустой для всех стандартных методов и должна содержать данные не ресурсов для пользовательских методов. Службы должны быть осторожны, чтобы не переименовать и не изменять тип любых ключей и значений, представленных как параметры.

request.path

request.path Переход - это путь для целевого resource . Путь относится к услуге. Сегменты пути, содержащие невозможные безопасные символы, такие как / кодируются URL.

Переменная resource

resource является текущим значением в службе, представленной в виде карты пар клавиш. Ссылка на resource в условиях приведет к максимум одному чтению значения из Сервиса. Этот поиск будет учитываться против любой квоты, связанной с обслуживанием, для ресурса. Для get запросов resource будет учитываться только к квоте в отказе.

Операторы и приоритет оператора

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

Учитывая произвольные выражения a и b , поле f и индекс i .

Оператор Описание Ассоциативность
a[i] a() af Индекс, вызов, доступ к полю слева направо
!a -a Единое отрицание справа налево
a/ba%ba*b Мультипликативные операторы слева направо
a+b ab Аддитивные операторы слева направо
a>ba>=ba Реляционные операторы слева направо
a in b Существование в списке или карте слева направо
a is type Сравнение типа, где type может быть Bool, Int, Float, Number, String, List, Map, TimeStamp, продолжительность, путь или латлнг слева направо
a==ba!=b Операторы сравнения слева направо
a && b Условно и слева направо
a || b Условное или слева направо
a ? true_value : false_value Тройное выражение слева направо

Realtime Database

Условие — это логическое выражение, которое определяет, следует ли разрешить или запретить конкретную операцию. Вы можете определить эти условия в Rules Realtime Database следующими способами.

Предварительно определенные переменные

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

Предопределенные переменные
сейчас Текущее время в миллисекундах со времен Epoch Linux. Это особенно хорошо работает для проверки временных метков, созданных с помощью SDK Firebase.database.servervalue.timestamp.
корень Управляющий правительством, представляющим корневой путь в базе данных Firebase, когда он существует перед попыткой операции.
Ньюдата Управление, представляющее данные, которые будут существовать после попытки операции. Он включает в себя новые данные, написанные и существующие данные.
данные Управляющий правительством, представляющим данные, которые существовали до попытки работы.
$ переменные Путь с подстановочным знаком, используемый для представления идентификаторов и динамичных детских ключей.
авторизация Представляет собой аутентифицированную полезную нагрузку пользователя.

Эти переменные можно использовать в любом месте ваших правил. Например, приведенные ниже правила безопасности убедитесь, что данные, записанные в /foo/ node, должны быть строкой менее 100 символов:

{
  "rules": {
    "foo": {
      // /foo is readable by the world
      ".read": true,

      // /foo is writable by the world
      ".write": true,

      // data written to /foo must be a string less than 100 characters
      ".validate": "newData.isString() && newData.val().length < 100"
    }
  }
}

Правила на основе данных

Любые данные в вашей базе данных могут использоваться в ваших правилах. Используя предварительно определенные переменные root , data и newData , вы можете получить доступ к любому пути, как это было бы до или после события записи.

Рассмотрим этот пример, который позволяет операциям записи до тех пор, пока значение /allow_writes/ node является true , родительский узел не имеет набора флага readOnly , и в недавно написанных данных есть ребенок с foo :

".write": "root.child('allow_writes').val() === true &&
          !data.parent().child('readOnly').exists() &&
          newData.child('foo').exists()"

Правила на основе запросов

Хотя вы не можете использовать правила в качестве фильтров, вы можете ограничить доступ к подмножествам данных, используя параметры запроса в ваших правилах. Используйте query. Выражения в ваших правилах для предоставления прочтения или записи доступа на основе параметров запроса.

Например, в следующем правиле на основе запросов используются правила безопасности на основе пользователей и правила, основанные на запросах, для ограничения доступа к данным в сборе baskets только к корзинам для покупок, которыми владеет активный пользователь:

"baskets": {
  ".read": "auth.uid !== null &&
            query.orderByChild === 'owner' &&
            query.equalTo === auth.uid" // restrict basket access to owner of basket
}

Следующий запрос, который включает параметры запроса в правиле, будет успешным:

db.ref("baskets").orderByChild("owner")
                 .equalTo(auth.currentUser.uid)
                 .on("value", cb)                 // Would succeed

Тем не менее, запросы, которые не включают параметры в правиле, потерпят неудачу с ошибки PermissionDenied :

db.ref("baskets").on("value", cb)                 // Would fail with PermissionDenied

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

Например, следующее правило ограничивает доступ только к первым 1000 результатам запроса, как указано по приоритету:

messages: {
  ".read": "query.orderByKey &&
            query.limitToFirst <= 1000"
}

// Example queries:

db.ref("messages").on("value", cb)                // Would fail with PermissionDenied

db.ref("messages").limitToFirst(1000)
                  .on("value", cb)                // Would succeed (default order by key)

Следующий query. Выражения доступны в Realtime Database Security Rules .

Выражения правил на основе запросов
Выражение Тип Описание
Query.orderbykey
Query.orderbypriority
Query.orderbyvalue
логическое значение Верно для запросов, упорядоченных с помощью ключа, приоритета или значения. Неверно иначе.
Query.orderbychild нить
нулевой
Используйте строку, чтобы представить относительный путь к детскому узлу. Например, query.orderByChild === "address/zip" . Если запрос не заказан детским узлом, это значение является нулевым.
Query.Startat
Query.endat
Query.equalto
нить
число
логическое значение
нулевой
Извлекает границы выполняющего запроса или возвращает NULL, если нет связанного набора.
Query.limittofirst
Query.limittolast
число
нулевой
Извлекает предел выполнения запроса или возвращает NULL, если нет ограничения.

Операторы

Rules Realtime Database поддерживают ряд операторов , которые вы можете использовать для объединения переменных в операторе условия. См. Полный список операторов в справочной документации .

Создание условий

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

Для некоторого руководства создают простые, готовые к производству Rules , см. Основные правила безопасности .