Как использовать условия в правилах безопасности Firebase Cloud Storage

В этом руководстве, которое дополняет статью основной синтаксис языка Firebase Security Rules, рассказывается, как добавлять условия в Firebase Security Rules для Cloud Storage.

Основной элемент Cloud Storage Security Rules – это условие. Условие – это логическое выражение, которое определяет, разрешена или запрещена определенная операция. Для простых правил в качестве условий отлично подходят литералы true и false. Однако язык Firebase Security Rules для Cloud Storage позволяет создавать более сложные условия, которые могут:

• Проверьте аутентификацию пользователей
• Проверка входящих данных

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Cloud Storage data.

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

Firebase Security Rules для Cloud Storage интегрируется с Firebase Authentication, чтобы обеспечить надежную аутентификацию пользователей в Cloud Storage. Это позволяет детально управлять доступом на основе утверждений токена Firebase Authentication.

Когда аутентифицированный пользователь выполняет запрос к Cloud Storage, переменная request.auth заполняется его uid (request.auth.uid), а также утверждениями JWT Firebase Authentication (request.auth.token).

Кроме того, при использовании специальной аутентификации в поле request.auth.token появляются дополнительные утверждения.

Если запрос выполняет неаутентифицированный пользователь, переменная request.auth имеет значение null.

Используя эти данные, можно использовать аутентификацию для защиты файлов несколькими распространенными способами:

• Общедоступные: игнорировать request.auth
• Аутентифицированный частный: убедитесь, что request.auth не является null
• Личные данные пользователя: проверьте, что request.auth.uid соответствует пути uid.
• Частная группа: проверьте утверждения специального токена на соответствие выбранному утверждению или прочитайте метаданные файла, чтобы узнать, существует ли поле метаданных.

Открытый профиль

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

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

Доступ ограничен

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

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

Личные пользователи

Наиболее распространенный вариант использования request.auth – предоставление отдельным пользователям детализированных разрешений на доступ к их файлам, от загрузки фото профиля до чтения личных документов.

Поскольку файлы в Cloud Storage имеют полный "путь" к файлу, все, что требуется, чтобы сделать файл контролируемым пользователем, – это уникальная идентифицирующая пользователя информация в префиксе названия файла (например, uid пользователя), которую можно проверить при оценке правила:

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

Частная группа

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

• Создайте специальный токен Firebase Authentication, который содержит дополнительную информацию об участнике группы (например, идентификатор группы).
• Добавьте информацию о группе (например, идентификатор группы или список авторизованных uid) в метаданные файла.

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

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

Запросить оценку

Загрузки, скачивания, изменения метаданных и удаления оцениваются с помощью request, отправляемого в Cloud Storage. Помимо уникального идентификатора пользователя и полезной нагрузки Firebase Authentication в объекте request.auth, как описано выше, переменная request содержит путь к файлу, в котором выполняется запрос, время получения запроса и новое значение resource, если запрос является записью.

Объект request также содержит уникальный идентификатор пользователя и полезную нагрузку Firebase Authentication в объекте request.auth, о котором рассказывается в разделе Безопасность на уровне пользователя.

Полный список свойств объекта request приведен ниже.

Оценка ресурсов

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

Firebase Security Rules для Cloud Storage предоставляет метаданные файла в объекте resource, который содержит пары "ключ-значение" метаданных, представленных в объекте Cloud Storage. Эти свойства можно проверить в запросах read или write, чтобы убедиться в целостности данных.

В запросах write (например, на загрузку, обновление метаданных и удаление) помимо объекта resource, который содержит метаданные файла, находящегося по пути запроса, вы также можете использовать объект request.resource, который содержит подмножество метаданных файла, которые будут записаны, если запись разрешена. Эти два значения можно использовать для обеспечения целостности данных или применения ограничений приложения, таких как тип или размер файла.

Полный список свойств объекта resource приведен ниже.

request.resource содержит все эти данные, за исключением generation, metageneration, etag, timeCreated и updated.

Улучшить с помощью Cloud Firestore

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

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

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

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{club}/files/{fileId} {
      allow read: if club in
        firestore.get(/databases/(default)/documents/users/$(request.auth.id)).data.memberships
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{userId}/photos/{fileId} {
      allow read: if
        firestore.exists(/databases/(default)/documents/users/$(userId)/friends/$(request.auth.id))
    }
  }
}

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

Чтобы отключить эту функцию, удалите роль IAM, как описано в статье Управление и развертывание Firebase Security Rules.

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

Firebase Security Rules для Cloud Storage также можно использовать для проверки данных, включая проверку имени и пути файла, а также свойств метаданных файла, таких как contentType и size.

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

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

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

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

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

service firebase.storage {
  match /b/{bucket}/o {
    // 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 /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

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

Дальнейшие действия

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

Узнайте, как работать с основными сценариями использования, а также о рабочем процессе разработки, тестирования и развертывания правил:

• Создайте правила для распространенных сценариев.
• Чтобы закрепить знания, изучите ситуации, в которых нужно выявлять и избегать небезопасных правил.
• Протестируйте правила с помощью эмулятора Cloud Storage и специальной библиотеки тестирования правил безопасности.
• Ознакомьтесь с доступными методами развертывания Security Rules.