Google is committed to advancing racial equity for Black communities. See how.

Use conditions in Firebase Storage Security Rules

This guide builds on the learn the core syntax of the Firebase Security Rules language guide to show how to add conditions to your Firebase Security Rules for Cloud Storage.

The primary building block of Storage Security Rules is the condition. A condition is a boolean expression that determines whether a particular operation should be allowed or denied. For basic rules, using true and false literals as conditions works prefectly well. But the Firebase Security Rules for Cloud Storage language gives you ways to write more complex conditions that can:

  • Check user authentication
  • Validate incoming data

Authentication

Firebase Security Rules for Cloud Storage integrates with Firebase Authentication to provide powerful user based authentication to Google Cloud Storage. This allows for granular access control based on claims of a Firebase Authentication token.

When an authenticated user performs a request against Google Cloud Storage, the request.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).

Additionally, when using custom authentication, additional claims are surfaced in the request.auth.token field.

When an unauthenticated user performs a request, the request.auth variable is null.

Using this data, there are several common ways to use authentication to secure files:

  • Public: ignore request.auth
  • Authenticated private: check that request.auth is not null
  • User private: check that request.auth.uid equals a path uid
  • Group private: check the custom token's claims to match a chosen claim, or read the file metadata to see if a metadata field exists

Public

Any rule that doesn't consider the request.auth context can be considered a public rule, since it doesn't consider the authentication context of the user. These rules can be useful for surfacing public data such as game assets, sound files, or other static content.

// 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");
}

Authenticated private

In certain cases, you may want data to be viewable by all authenticated users of your application, but not by unauthenticated users. Since the request.auth variable is null for all unauthenticated users, all you have to do is check the request.auth variable exists in order to require authentication:

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

User private

By far the most common use case for request.auth will be to provide individual users with granular permissions on their files: from uploading profile pictures to reading private documents.

Since files in Google Cloud Storage have a full "path" to the file, all it takes to make a file controlled by a user is a piece of unique, user identifying information in the filename prefix (such as the user's uid) that can be checked when the rule is evaluated:

// 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;
}

Group private

Another equally common use case will be to allow group permissions on an object, such as allowing several team members to collaborate on a shared document. There are several approaches to doing this:

  • Mint a Firebase Authentication custom token that contains additional information about a group member (such as a group ID)
  • Include group information (such as a group ID or list of authorized uids) in the file metadata

Once this data is stored in the token or file metadata, it can be referenced from within a rule:

// 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 Evaluation

Uploads, downloads, metadata changes, and deletes are evaluated using the request sent to Google Cloud Storage. In addition to the user's unique ID and the Firebase Authentication payload in the request.auth object as described above, the request variable contains the file path where the request is being performed, the time when the request is received, and the new resource value if the request is a write. HTTP headers and authentication state are also included.

The request object also contains the user's unique ID and the Firebase Authentication payload in the request.auth object, which will be explained further in the User-Based Security section of the docs.

A full list of properties in the request object is available below:

Property Type Description
auth map<string, string> When a user is logged in, provides uid, the user's unique ID, and token, a map of Firebase Authentication JWT claims. Otherwise, it will be null.
params map<string, string> Map containing the query parameters of the request.
path path A path representing the path the request is being performed at.
resource map<string, string> The new resource value, present only on write requests.
time timestamp A timestamp representing the server time the request is evaluated at.

Resource Evaluation

When evaluating rules, you may also want to evaluate the metadata of the file being uploaded, downloaded, modified, or deleted. This allows you to create complex and powerful rules that do things like only allow files with certain content types to be uploaded, or only files greater than a certain size to be deleted.

Firebase Security Rules for Cloud Storage provides file metadata in the resource object, which contains key/value pairs of the metadata surfaced in a Google Cloud Storage object. These properties can be inspected on read or write requests to ensure data integrity.

On write requests (such as uploads, metadata updates, and deletes), in addition to the resource object, which contains file metadata for the file that currently exists at the request path, you also have the ability to use the request.resource object, which contains a subset of the file metadata to be written if the write is allowed. You can use these two values to ensure data integrity or enforce application constraints such as file type or size.

A full list of properties in the resource object is available below:

Property Type Description
name string The full name of the object
bucket string The name of the bucket this object resides in.
generation int The GCS object generation of this object.
metageneration int The GCS object metageneration of this object.
size int The size of the object in bytes.
timeCreated timestamp A timestamp representing the time an object was created.
updated timestamp A timestamp representing the time an object was last updated.
md5Hash string An MD5 hash of the object.
crc32c string A crc32c hash of the object.
etag string The etag associated with this object.
contentDisposition string The content disposition associated with this object.
contentEncoding string The content encoding associated with this object.
contentLanguage string The content language associated with this object.
contentType string The content type associated with this object.
metadata map<string, string> Key/value pairs of additional, developer specified custom metadata.

request.resource contains all of these with the exception of generation, metageneration, etag, timeCreated, and updated.

Validate data

Firebase Security Rules for Cloud Storage can also be used for data validation, including validating file name and path as well as file metadata properties such as contentType and 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/.*');
    }
  }
}

Custom functions

As your Firebase Security Rules become more complex, you may want to wrap sets of conditions in functions that you can reuse across your ruleset. Security rules support custom functions. The syntax for custom functions is a bit like JavaScript, but Firebase Security Rules functions are written in a domain-specific language that has some important limitations:

  • Functions can contain only a single return statement. They cannot contain any additional logic. For example, they cannot execute loops or call external services.
  • Functions can automatically access functions and variables from the scope in which they are defined. For example, a function defined within the service firebase.storage scope has access to the resource variable, and for Cloud Firestore only, built-in functions such as get() and exists().
  • Functions may call other functions but may not recurse. The total call stack depth is limited to 10.
  • In version rules2, functions can define variables using the let keyword. Functions can have any number of let bindings, but must end with a return statement.

A function is defined with the function keyword and takes zero or more arguments. For example, you may want to combine the two types of conditions used in the examples above into a single 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();
    }
  }
}

Using functions in your Firebase Security Rules makes them more maintainable as the complexity of your rules grows.

Next steps

After this discussion of conditions, you've got a more sophisticated understanding of Rules and are ready to:

Learn how to handle core use cases, and learn the workflow for developing, testing and deploying Rules: