Firebase Security Rules for Cloud Storage Reference

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. Cloud 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 Cloud 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:

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:

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';

firestore.get and firestore.exists

The firestore.get() and firestore.exists() functions allow you to access documents in Cloud Firestore to evaluate complex authorization criteria.

The firestore.get() and firestore.exists() functions both expect fully-specified document paths. When using variables to construct paths for firestore.get() and firestore.exists(), you need to explicitly escape variables using the $(variable) syntax.

firestore.get

Get the contents of a Cloud Firestore document.

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.uid)).data.memberships
    }
  }
}

firestore.exists

Check if a Cloud Firestore document exists.

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.uid))
    }
  }
}

Service

The service is the first declaration in a Cloud 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

The Rules language allows you to check type using the is operator.

// For example
a is null
a is string

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

Operations short circuit, and can return either true, false, or an Error.

allow read: if true || false;   // always succeeds, short circuits at true
allow write: if false && true; // always fails, short circuits at false

int and float

The int and float types represent numbers. Ints are: 0, 1, -2, etc. , while floats are: 1.0, -2.0, 3.33, etc.

Ints are signed 64-bit values, and floats are 64-bit IEEE 754 compliant values. Values of type int will be coerced to float when used in comparisons and arithmetic operations with a float value.

Comparison

Ints and floats can be compared and ordered using the ==, !=, >, <, >=, and <= operators.

Arithmetic

Ints and floats can be added, subtracted, multiplied, divided, moduloed, and negated:

Mathematical functions

Firebase Security Rules for Cloud Storage also provides a number of mathematics helper functions to simplify expressions:

string

Comparison

Strings can be lexographically compared and ordered using the ==, !=, >, <, >=, and <= operators.

Concatenation

Strings can be concatenated using the + operator.

// Concatenate a file name and extension
'file' + '.txt'

Index and Range

The index operator, string[], returns a string that contains the character at the provided index in the string.

// Allow reads of files that begin with 'a'
match /{fileName} {
  allow read: if fileName[0] == 'a';
}

The range operator, string[i:j], returns a string that contains the characters between the specified indices, from i (inclusive) until j (exclusive). If i or j are not specified, they default to 0 and the size of the string, respectively, but at least i or j must be specified for the range to be valid.

// Allow reads of files that begin with 'abcdef'
match /{fileName} {
  allow read: if fileName[0:6] == 'abcdef';
}

The index and range operators will yield an error if the indices provided exceed the string bounds.

size

Returns the number of characters in the string.

// Allow files with names less than 10 characters
match /{fileName} {
  allow write: if fileName.size() < 10;
}

matches

Performs a regular expression match, returns true if the string matches the given regular expression. Uses Google RE2 syntax.

// Allow writes to files which end in ".txt"
match /{fileName} {
  allow write: if fileName.matches('.*\\.txt')
}

split

Splits a string according to a provided regular expression and returns a list of strings. Uses Google RE2 syntax.

// Allow files named "file.*" to be uploaded
match /{fileName} {
  allow write: if fileName.split('.*\\..*')[0] == 'file'
}

path

Paths are directory-like names with optional pattern matching. The presence of a forward slash / denotes the start of a path segment.

path

Converts a string argument to a path.

// Allow reads on a specific file path
match /{allFiles=**} {
  allow read: if allFiles == path('/path/to/file');
}

timestamp

Timestamps are in UTC, with possible values beginning at 0001-01-01T00.00.00Z and ending at 9999-12-31T23.59.59Z.

Comparison

Timestamps can be compared and ordered using the ==, !=, >, <, >=, and <= operators.

Arithmetic

Timestamps support addition and subtraction between timestamps and durations as follows:

date

A timestamp value containing the year, month, and day only.

// Allow reads on the same day that the resource was created.
allow read: if request.time.date() == resource.timeCreated.date()

year

The year value as an int, from 1 to 9999.

// Allow reads on all requests made before 2017
allow read: if request.time.year() < 2017

month

The month value as an int, from 1 to 12.

// Allow reads on all requests made during the month of January
allow read: if request.time.month() == 1;

day

The current day of the month as an int, from 1 to 31.

// Allow reads on all requests made during the first day of each month
allow read: if request.time.day() == 1;

time

A duration value containing the current time.

// Allow reads on all requests made before 12PM
allow read: if request.time.time() < duration.time(12, 0, 0, 0);

hours

The hours value as an int, from 0 to 23.

// Allow reads on all requests made before 12PM
allow read: if request.time.hours() < 12;

minutes

The minutes value as an int, from 0 to 59.

// Allow reads during even minutes of every hour
allow read: if request.time.minutes() % 2 == 0;

seconds

The seconds value as an int, from 0 to 59.

// Allow reads during the second half of each minute
allow read: if request.time.seconds() > 29;

nanos

The fractional seconds in nanos as an int.

// Allow reads during the first 0.1 seconds of each second
allow read: if request.time.nanos() < 100000000;

dayOfWeek

The day of the week, from 1 (Monday) to 7 (Sunday).

// Allow reads on weekdays (Monday to Friday)
allow read: if request.time.dayOfWeek() < 6;

dayOfYear

The day of the current year, from 1 to 366.

// Allow reads every fourth day
allow read: if request.time.dayOfYear() % 4 == 0;

toMillis

Returns the current number of milliseconds since the Unix epoch.

// Allow reads if the request is made before a specified time
allow read: if request.time.toMillis() < <milliseconds>;

duration

Duration values are represented as seconds plus fractional seconds in nanoseconds.

Comparison

Durations can be compared and ordered using the ==, !=, >, <, >=, and <= operators.

Arithmetic

Durations support addition and subtraction between timestamps and durations as follows:

seconds

The number of seconds in the current duration. Must be between -315,576,000,000 and +315,576,000,000 inclusive.

nanos

The number of fractional seconds (in nanoseconds) of the current duration. Must be beween -999,999,999 and +999,999,999 inclusive. For non-zero seconds and non-zero nanonseconds, the signs of both must be in agreement.

duration.value

Durations can be created using the duration.value(int magnitude, string units) function, which creates a time duration from the given magnitude and unit.

// All of these durations represent one hour:
duration.value(1, "h")
duration.value(60, "m")
duration.value(3600, "s")

Possible units are:

duration.time

Durations can be created using the duration.time(int hours, int minutes, int seconds, int nanoseconds) function, which creates a time duration of the given hours, minutes, seconds, and nanoseconds.

// Create a four hour, three minute, two second, one nanosecond duration
duration.time(4, 3, 2, 1)

list

A list contains an ordered array of values, which can of type: null, bool, int, float, string, path, list, map, timestamp, or duration.

Given x and y of type list and i and j of type int

Creation

To create a list, add values between brackets:

// Create a list of strings
['apples', 'grapes', 'bananas', 'cheese', 'goats']

Comparison

Lists can be compared using the == operators !=. Equality of two lists requires all values to be equal.

Index and Range

The index operator, list[], returns the item at the provided index in the list.

// Allow reads of all files that begin with 'a'
match /{fileName} {
  allow read: if fileName[0] == 'a';
}

The range operator, list[i:j], returns all items in a list between the specified indices, from i (inclusive) until j (exclusive). If i or j are not specified, they default to 0 and the size of the list, respectively, but at least i or j must be specified for the range to be valid.

// Allow reads of all files that begin with 'abcdef'
match /{fileName} {
  allow read: if fileName[0:6] == 'abcdef';
}

in

Returns true if the desired value is present in the list or false if not present.

// Allow read if a filename has the string 'txt' in it
match /{fileName} {
  allow read: if 'txt' in fileName.split('\\.');
}

join

Combines a list of strings into a single string, separated by the given string.

// Allow reads if the joined array is 'file.txt'
allow read: if ['file', 'txt'].join('.') == 'file.txt';

size

The number of items in the list.

// Allow read if there are three items in our list
allow read: if ['foo', 'bar', 'baz'].size() == 3;

hasAll

Returns true if all values are present in the list.

// Allow read if one list has all items in the other list
allow read: if ['file', 'txt'].hasAll(['file', 'txt']);

map

A map contains key/value pairs, where keys are strings and values can be any of: null, bool, int, float, string, path, list, map, timestamp, or duration.

Creation

To create a map, add key/value pairs between braces:

// Create a map of strings to strings
{
  'mercury': 'mars',
  'rain': 'cloud',
  'cats': 'dogs',
}

Comparison

Maps can be compared using the == operators !=. Equality of two maps requires all keys are present in both maps and all values are equal.

Index

Values in a map are accessed by using either bracket or dot notation:

// Access custom metadata properties
allow read: if resource.metadata.property == 'property'
allow write: if resource.metadata['otherProperty'] == 'otherProperty'

If a key is not present, an error will be returned.

in

Returns true if the desired key is present in the map or false if not present.

// Allow reads if a property is present in the custom metadata
allow read: if property in resource.metadata;

size

The number of keys in the map.

// Allow reads if there's exactly one custom metadata key
allow read: if resource.metadata.size() == 1;

keys

A list of all keys in the map.

// Allow reads if the first metadata key is 'myKey'
allow read: if resource.metadata.keys()[0] == 'myKey';

values

A list of all values in the map, in key order.

// Allow reads if the first metadata value is 'myValue'
allow read: if resource.metadata.values()[0] == 'myValue';

Errors

Error Evaluation

Firebase Security Rules for Cloud Storage continue evaluation when errors are encountered. This is useful because conditional && and || expressions may absorb an error if the conditional would otherwise short-circuit to false or true respectively. For instance:

Common places where errors are raised are: division by zero, accessing values in a list or map that don't exist, and passing values of the incorrect type to a function.

// Error if resource.size is zero
allow read: if 1000000 / resource.size;

// Error, key doesn't exist
allow read: if resource.metadata.nonExistentKey == 'value';

// Error, no unit 'y' exists
allow read: if request.time < resource.timeCreated + duration.value(1, 'y');