Firebase Security Rules for Cloud Storage are used to determine who has read and write access
to files stored in Cloud Storage, as well as how files are structured
and what metadata they contain. Storage Security Rules are composed of rules that
consider the request
and resource
to allow or deny a desired action, such
as uploading a file or retrieving file metadata. These reference docs cover
the types of rules, the properties of a request
and a resource
, the data
types used by Storage Security Rules, and how errors occur.
Rule
A rule
is an expression that is evaluated to determine if a request
is
allowed to perform a desired action.
Types
Allow
allow
rules consist of a method, such as read
or write
, as well as
an optional condition. When a rule is executed, the condition is evaluated, and
if the condition evaluates to true
, the desired method is allowed; otherwise,
the method is denied. An allow
rule with no condition always allows the
desired method.
// Always allow method allow <method>; // Allow method if condition is true allow <method>: if <condition>;
Currently, allow
is the only supported type of rule.
Request Methods
Read
The read
method covers all requests where file data or metadata is read,
including file downloads and file metadata reads.
// Always allow reads allow read; // Allow reads if condition evaluates to true allow read: if <condition>;
Write
The write
method covers all requests where file data or metadata is written,
including file uploads, file deletes, and file metadata updates.
// Always allow writes allow write; // Allow writes if condition evaluates to true allow write: if <condition>;
Match
Rules are executed when a user request
(such as a file upload or download)
matches a file path covered by a rule. A match
consists of a path and a body,
which must contain at least one allow
rule. If no path is matched, the request
is rejected.
You can match
a fully named path, or you can insert wildcards to match all
paths that fit a certain pattern.
Path Segments
single_segment
You can use single path segments to create a rule that matches a file stored in Cloud Storage.
// Allow read at "path" if condition evaluates to true match /path { allow read: if <condition>; }
Multiple path segments and nested paths are also allowed:
// Allow read at "path/to/object" if condition evaluates to true match /path { match /to { match /object { allow read: if <condition>; } } }
{single_segment_wildcard}
If you want to apply a rule to multiple files at the same path, you can use a
wildcard path segment to match all files at a certain path. A wildcard variable
is declared in a path by wrapping a variable in curly braces: {variable}
.
This variable is accessible within the match statement as a string
.
// Allow read at any path "/*", if condition evaluates to true match /{single_path} { // Matches "path", "to", or "object" but not "path/to/object" allow read: if <condition>; }
Multiple path segments and nested paths may also have wildcards:
// Allow read at any path "/path/*/newPath/*", if condition evaluates to true match /path/{first_wildcard} { match /newPath/{second_wildcard} { // Matches "path/to/newPath/newObject" or "path/from/newPath/oldObject" allow read: if <condition>; } }
{multi_segment_wildcard=**}
If you want to match any number of path segments at or below a path, you can use a multi segment wildcard, which will match all requests to and below the location. This can be useful for providing a user their own free form storage space, or creating rules that match many different path segments (such as creating a publicly readable set of files, or requiring authentication for all writes).
A multi segment wildcard path is declared similarly to a single segment
wildcard, with the addition of the =**
at the end of the variable:
{variable=**}
. A multi-segment wildcard variable is available within the match
statement as a path
object.
// Allow read at any path "/**", if condition evaluates to true match /{multi_path=**} { // Matches anything at or below this, from "path", "path/to", "path/to/object", ... allow read: if <condition>; }
Request
The request
variable is provided within a condition to represent the
request being made at that path. The request
variable has a number of
properties which can be used to decide whether to allow the incoming request.
Properties
auth
When an authenticated user performs a request against Cloud Storage,
the auth
variable is populated with the user's uid
(request.auth.uid
) as
well as the claims of the Firebase Authentication JWT (request.auth.token
).
request.auth.token
contains some or all of the following keys:
Field | Description |
---|---|
email |
The email address associated with the account, if present. |
email_verified |
true if the user has verified they have access to the email address. Some providers automatically verify email addresses they own. |
phone_number |
The phone number associated with the account, if present. |
name |
The user's display name, if set. |
sub |
The user's Firebase UID. This is unique within a project. |
firebase.identities |
Dictionary of all the identities that are associated with this user's account. The keys of the dictionary can be any of the following: email , phone , google.com , facebook.com , github.com , twitter.com . The values of the dictionary are arrays of unique identifiers for each identity provider associated with the account. For example, auth.token.firebase.identities["google.com"][0] contains the first Google user ID associated with the account. |
firebase.sign_in_provider |
The sign-in provider used to obtain this token. Can be one of the following strings: custom , password , phone , anonymous , google.com , facebook.com , github.com , twitter.com . |
If using custom authentication, request.auth.token
also contains any custom
claims specified by the developer.
When an unauthenticated user performs a request, request.auth
is null
.
// Allow requests from authenticated users allow read, write: if request.auth != null;
path
The path
variable contains the path that a request
is being performed
against.
// Allow a request if the first path segment equals "images" allow read, write: if request.path[0] == 'images';
resource
The resource
variable contains the metadata of a file being uploaded or the
updated metadata for an existing file. This is related to the
resource
variable, which contains the current file metadata at
the requested path, as opposed to the new metadata.
// Allow a request if the new value is smaller than 5MB allow read, write: if request.resource.size < 5 * 1024 * 1024;
request.resource
contains the following properties from resource
:
Property |
---|
name |
bucket |
metadata |
size |
contentType |
time
The time
variable contains a timestamp representing the current server time
a request is being evaluated at. You can use this to provide time-based access
to files, such as: only allowing files to be uploaded until a certain date,
or only allowing files to be read up to an hour after they were uploaded.
// Allow a read if the file was created less than one hour ago allow read: if request.time < resource.timeCreated + duration.value(1, 'h');
Many functions are provided to write rules using timestamps and durations.
Resource
The resource
variable contains file metadata for files in
Cloud Storage, such as the file name, size, creation time, and
custom metadata.
Properties
name
A string containing the full name of the file, including the path to the file.
// Allow reads if the resource name is "path/to/object" allow read: if resource.name == 'path/to/object'
bucket
A string containing the Google Cloud Storage bucket this file is stored in.
// Allow reads of all resources in your bucket allow read: if resource.bucket == '<your-cloud-storage-bucket>'
generation
A int containing the Google Cloud Storage object generation of the file. Used for object versioning.
// Allow reads if the resource matches a known object version allow read: if resource.generation == <known-generation>
metageneration
A int containing the Google Cloud Storage object metageneration of the file. Used for object versioning.
// Allow reads if the resource matches a known object metadata version allow read: if resource.metageneration == <known-generation>
size
An int containing the file size in bytes.
// Allow reads if the resource is less than 10 MB allow read: if resource.size < 10 * 1024 * 1024;
timeCreated
A timestamp representing when the file was created.
// Allow reads if the resource was created less than an hour ago allow read: if resource.timeCreated < request.time + duration.value(60, "m")
updated
A timestamp representing when the file was last updated.
// Allow reads if the resource was updated less than an hour ago allow read: if resource.updated < request.time + duration.value(60, "m")
md5Hash
A string containing the MD5 hash of the file.
// Allow writes if the hash of the uploaded file is the same as the existing file allow write: if request.resource.md5Hash == resource.md5Hash;
crc32c
A string containing the crc32c hash of the file.
// Allow writes if the hash of the uploaded file is the same as the existing file allow write: if request.resource.crc32c == resource.crc32c;
etag
A string containing the etag of the file.
// Allow writes if the etag matches a known object etag allow write: if resource.etag == <known-generation>
contentDisposition
A string containing the content disposition of the file.
// Allow reads if the content disposition matches a certain value allow read: if resource.contentDisposition == 'inlined';
contentEncoding
A string containing the content encoding of the file.
// Allow reads if the content is encoded with gzip allow read: if resource.contentEncoding == 'gzip';
contentLanguage
A string containing the content language of the file.
// Allow reads if the content language is Japanese allow read: if resource.contentLanguage == 'ja';
contentType
A string containing the content type of the file.
// Allow reads if the content type is PNG. allow read: if resource.contentType == 'image/png';
metadata
A Map<String, String>
containing additional developer provided metadata
fields.
// Allow reads if a certain metadata field matches a desired value allow read: if resource.metadata.customProperty == 'customValue';
Service
The service
is the first declaration in a Storage Security Rules file, and
specifies which service these rules will apply to.
Name
name
The name of the service rules will be apply to. The only current value is
firebase.storage
.
// Specify the service name service firebase.storage { match /b/{bucket}/o { ... } }
Data Types
null
The null
data type represents a value not existing.
allow read: if request.auth != null;
bool
The bool
type represents a boolean true
or false
value.
allow read: if true; // always succeeds allow write: if false; // always fails
Comparison
Boolean values can be compared using the ==
operators !=
.
Boolean Operations
Ope |
---|