Условия написания правил безопасности Cloud Firestore

Это руководство основано на руководстве по структурированию правил безопасности , чтобы показать, как добавлять условия в Cloud Firestore Security Rules . Если вы не знакомы с основами Cloud Firestore Security Rules , см. руководство по началу работы .

Основным строительным блоком Cloud Firestore Security Rules является условие. Условие — это логическое выражение, которое определяет, следует ли разрешить или запретить определенную операцию. Используйте правила безопасности для написания условий, которые проверяют аутентификацию пользователя, проверяют входящие данные или даже получают доступ к другим частям вашей базы данных.

Аутентификация

Одним из наиболее распространенных шаблонов правил безопасности является управление доступом на основе состояния аутентификации пользователя. Например, ваше приложение может разрешить только вошедшим в систему пользователям записывать данные:

service cloud.firestore {
  match /databases/{database}/documents {
    // Allow the user to access documents in the "cities" collection
    // only if they are authenticated.
    match /cities/{city} {
      allow read, write: if request.auth != null;
    }
  }
}

Другой распространенный шаблон — гарантировать, что пользователи могут читать и записывать только свои собственные данные:

service cloud.firestore {
  match /databases/{database}/documents {
    // Make sure the uid of the requesting user matches name of the user
    // document. The wildcard expression {userId} makes the userId variable
    // available in rules.
    match /users/{userId} {
      allow read, update, delete: if request.auth != null && request.auth.uid == userId;
      allow create: if request.auth != null;
    }
  }
}

Если ваше приложение использует Firebase Authentication или Google Cloud Identity Platform , переменная request.auth содержит информацию об аутентификации для клиента, запрашивающего данные. Для получения дополнительной информации о request.auth см. справочную документацию .

Проверка данных

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

service cloud.firestore {
  match /databases/{database}/documents {
    // Allow the user to read data if the document has the 'visibility'
    // field set to 'public'
    match /cities/{city} {
      allow read: if resource.data.visibility == 'public';
    }
  }
}

Переменная resource ссылается на запрошенный документ, а resource.data — это карта всех полей и значений, хранящихся в документе. Для получения дополнительной информации о переменной resource см. справочную документацию .

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

service cloud.firestore {
  match /databases/{database}/documents {
    // Make sure all cities have a positive population and
    // the name is not changed
    match /cities/{city} {
      allow update: if request.resource.data.population > 0
                    && request.resource.data.name == resource.data.name;
    }
  }
}

Доступ к другим документам

Используя функции get() и exists() , ваши правила безопасности могут оценивать входящие запросы по отношению к другим документам в базе данных. Функции get() и exists() ожидают полностью указанные пути к документам. При использовании переменных для построения путей для get() и exists() вам необходимо явно экранировать переменные с помощью синтаксиса $(variable) .

В приведенном ниже примере переменная database захватывается оператором сопоставления match /databases/{database}/documents и используется для формирования пути:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      // Make sure a 'users' document exists for the requesting user before
      // allowing any writes to the 'cities' collection
      allow create: if request.auth != null && exists(/databases/$(database)/documents/users/$(request.auth.uid));

      // Allow the user to delete cities if their user document has the
      // 'admin' field set to 'true'
      allow delete: if request.auth != null && get(/databases/$(database)/documents/users/$(request.auth.uid)).data.admin == true;
    }
  }
}

Для записей вы можете использовать функцию getAfter() для доступа к состоянию документа после завершения транзакции или пакета записей, но до фиксации транзакции или пакета. Как и get() , функция getAfter() принимает полностью указанный путь к документу. Вы можете использовать getAfter() для определения наборов записей, которые должны выполняться вместе как транзакция или пакет.

Доступ к лимитам вызовов

Существует ограничение на количество вызовов доступа к документам для каждой оценки набора правил:

  • 10 для запросов на отдельные документы и запросов.

  • 20 для многодокументных чтений, транзакций и пакетных записей. Предыдущий предел в 10 также применяется к каждой операции.

    Например, представьте, что вы создаете пакетный запрос на запись с 3 операциями записи, и что ваши правила безопасности используют 2 вызова доступа к документу для проверки каждой записи. В этом случае каждая запись использует 2 из своих 10 вызовов доступа, а пакетный запрос на запись использует 6 из своих 20 вызовов доступа.

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

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

Доступ к звонкам и ценам

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

Пользовательские функции

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

  • Функции могут содержать только один оператор return . Они не могут содержать никакой дополнительной логики. Например, они не могут выполнять циклы или вызывать внешние службы.
  • Функции могут автоматически получать доступ к функциям и переменным из области, в которой они определены. Например, функция, определенная в области действия service cloud.firestore , имеет доступ к переменной resource и встроенным функциям, таким как get() и exists() .
  • Функции могут вызывать другие функции, но не могут рекурсировать. Общая глубина стека вызовов ограничена 10.
  • В правилах версии 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();
    }
  }
}

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

Правила не являются фильтрами

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

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

service cloud.firestore {
  match /databases/{database}/documents {
    // Allow the user to read data if the document has the 'visibility'
    // field set to 'public'
    match /cities/{city} {
      allow read: if resource.data.visibility == 'public';
    }
  }
}

Отклонено : Это правило отклоняет следующий запрос, поскольку результирующий набор может включать документы, visibility которых не является public :

Веб 
db.collection("cities").get()
    .then(function(querySnapshot) {
        querySnapshot.forEach(function(doc) {
            console.log(doc.id, " => ", doc.data());
    });
});

Разрешено : это правило разрешает следующий запрос, поскольку предложение where("visibility", "==", "public") гарантирует, что результирующий набор удовлетворяет условию правила:

Веб 
db.collection("cities").where("visibility", "==", "public").get()
    .then(function(querySnapshot) {
        querySnapshot.forEach(function(doc) {
            console.log(doc.id, " => ", doc.data());
        });
    });

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

Следующие шаги