Cloud Firestore

Basic structure

Firebase Security Rules inCloud Firestore andCloud Storage use the following structure andsyntax:

service <<name>> {  // Match the resource path.  match <<path>> {    // Allow the request if the following conditions are true.    allow <<methods>> : if <<condition>>  }}

The following key concepts are important to understand as you build the rules:

• Request: The method or methods invoked in theallow statement. These aremethods you're allowing to run. The standard methods are:get,list,create,update, anddelete. Theread andwrite convenience methodsenable broad read and write access on the specified database or storage path.
• Path: The database or storage location, represented as aURI path.
• Rule: Theallow statement, which includes a condition that permits arequest if it evaluates to true.

Security rules version 2

As of May 2019, version 2 of theFirebase security rules is nowavailable. Version 2 of the rules changes the behavior ofrecursivewildcards{name=**}. You must use version 2 if you plan tousecollection group queries. You must opt-in toversion 2 by makingrules_version = '2'; the first line in your securityrules:

rules_version = '2';service cloud.firestore {  match /databases/{database}/documents {

servicecloud.firestore{ match/databases/{database}/documents{   match/cities/{city}{     allowread,write:if<condition>;//Explicitlydefinerulesforthe'landmarks'subcollection     match/landmarks/{landmark}{       allowread,write:if<condition>;   }   } }}

servicecloud.firestore{ match/databases/{database}/documents{   match/cities/{city}{   match/landmarks/{landmark}{     allowread,write:if<condition>;     }   } }}

servicecloud.firestore{ match/databases/{database}/documents{   match/cities/{city}/landmarks/{landmark}{   allowread,write:if<condition>;   } }}

servicecloud.firestore{match/databases/{database}/documents{//Matchesanydocumentinthe'cities'collection.match/cities/{city}{allowread,write:iffalse;}//Matchesanydocumentinthe'cities'collection.match/cities/{document}{allowread,write:iftrue;}}}

servicecloud.firestore{match/databases/{database}/documents{//Matchesanydocumentinthecitiescollectionaswellasanydocument//inasubcollection.match/cities/{document=**}{allowread,write:if<condition>;}}}

rules_version='2';servicecloud.firestore{match/databases/{database}/documents{//Matchesanydocumentinthecitiescollectionaswellasanydocument//inasubcollection.match/cities/{city}/{document=**}{allowread,write:if<condition>;}}}

rules_version='2';servicecloud.firestore{match/databases/{database}/documents{//Matchesanydocumentinthesongscollectiongroupmatch/{path=**}/songs/{song}{allowread,write:if<condition>;}}}

If you usecollection group queries, you must useversion 2, seesecuring collection group queries.

Security rule limits

As you work with security rules, note the following limits:

Cloud Storage

Basic structure

Firebase Security Rules inCloud Firestore andCloud Storage use the following structure andsyntax:

service <<name>> {  // Match the resource path.  match <<path>> {    // Allow the request if the following conditions are true.    allow <<methods>> : if <<condition>>  }}

The following key concepts are important to understand as you build the rules:

• Request: The method or methods invoked in theallow statement. These aremethods you're allowing to run. The standard methods are:get,list,create,update, anddelete. Theread andwrite convenience methodsenable broad read and write access on the specified database or storage path.
• Path: The database or storage location, represented as aURI path.
• Rule: Theallow statement, which includes a condition that permits arequest if it evaluates to true.

Matching paths

Cloud Storage Security Rulesmatch the file paths used to access files inCloud Storage. Rules canmatch exact paths or wildcard paths, andrules can also be nested. If no match rule allows an request method, or thecondition evaluates tofalse, the request is denied.

Exact matches

// Exact match for "images/profilePhoto.png"match/images/profilePhoto.png{allowwrite:if<condition>;}// Exact match for "images/croppedProfilePhoto.png"match/images/croppedProfilePhoto.png{allowwrite:if<other_condition>;}

Nested matches

// Partial match for files that start with "images"match/images{// Exact match for "images/profilePhoto.png"match/profilePhoto.png{allowwrite:if<condition>;}// Exact match for "images/croppedProfilePhoto.png"match/croppedProfilePhoto.png{allowwrite:if<other_condition>;}}

Wildcard matches

Rules can also be used tomatch a pattern using wildcards. A wildcard is anamed variable that represents either a single string such asprofilePhoto.png, or multiple path segments, such asimages/profilePhoto.png.

A wildcard is created by adding curly braces around the wildcard name, like{string}. A multiple segment wildcard can be declared by adding=** to thewildcard name, like{path=**}:

// Partial match for files that start with "images"match/images{// Exact match for "images/*"// e.g. images/profilePhoto.png is matchedmatch/{imageId}{// This rule only matches a single path segment (*)// imageId is a string that contains the specific segment matchedallowread:if<condition>;}// Exact match for "images/**"// e.g. images/users/user:12345/profilePhoto.png is matched// images/profilePhoto.png is also matched!match/{allImages=**}{// This rule matches one or more path segments (**)// allImages is a path that contains all segments matchedallowread:if<other_condition>;}}

// Another way to restrict the name of a filematch/images/{imageId}{allowread:ifimageId=="profilePhoto.png";}

Therequest object also contains the user's unique ID and theFirebase Authentication payload in therequest.auth object, which will beexplained further in theAuthenticationsection of the docs.

A full list of properties in therequest object is available below:

Resource evaluation

When evaluating rules, you may also want to evaluate the metadata of the filebeing uploaded, downloaded, modified, or deleted. This lets you createcomplex and powerful rules that do things like only allow files with certaincontent types to be uploaded, or only files greater than a certain size to bedeleted.

Firebase Security Rules forCloud Storage provides file metadata in theresourceobject, which contains key/value pairs of the metadata surfaced in aCloud Storage object. These properties can be inspected onread orwrite requests to ensure data integrity.

Onwrite requests (such as uploads, metadata updates, and deletes), inaddition to theresource object, which contains file metadata for the filethat exists at the request path, you also have the ability to use therequest.resource object, which contains a subset of the file metadata to bewritten if the write is allowed. You can use these two values to ensure dataintegrity or enforce application constraints such as file type or size.

A full list of properties in theresource object is available:

request.resource contains all of these with the exception ofgeneration,metageneration,etag,timeCreated, andupdated.

Security Rules limits

As you work with security rules, note the following limits:

Full Example

Putting it all together, you can create a full example of rules for an imagestorage solution:

servicefirebase.storage{match/b/{bucket}/o{match/images{//Allowwritefilestothepath"images/*",subjecttotheconstraints://1)Fileislessthan5MB//2)Contenttypeisanimage//3)Uploadedcontenttypematchesexistingcontenttype//4)Filename(storedinimageIdwildcardvariable)islessthan32charactersmatch/{imageId}{allowread;allowwrite:ifrequest.resource.size <5*1024*1024                    &&request.resource.contentType.matches('image/.*')                    &&request.resource.contentType==resource.contentType                    &&imageId.size() <32}}}}

Realtime Database

Basic structure

InRealtime Database,Firebase Security Rules consist of JavaScript-like expressions contained in aJSON document.

They use the following syntax:

{  "rules": {    "<<path>>": {    // Allow the request if the condition for each method is true.      ".read": <<condition>>,      ".write": <<condition>>,      ".validate": <<condition>>    }  }}

There are three basic elements in the rule:

• Path: The database location. This mirrors your database's JSON structure.
• Request: These are the methods the rule uses to grant access. Thereadandwrite rules grant broad read and write access, whilevalidate rulesact as a secondary verification to grant access based on incoming or existingdata.
• Condition: The condition that permits a request if it evaluates to true.

How rules apply to paths

InRealtime Database,Security Rules apply atomically, meaning that rules athigher-level parent nodes override rules at more granular child nodes andrules at a deeper node can't grant access to a parent path. Youcan't refine or revoke access at a deeper path in your database structure ifyou've already granted it for one of the parent paths.

Consider the following rules:

{  "rules": {     "foo": {        // allows read to /foo/*        ".read": "data.child('baz').val() === true",        "bar": {          // ignored, since read was allowed already          ".read": false        }     }  }}

This security structure allows/bar/ to be read from whenever/foo/ contains a childbaz with valuetrue.The".read": false rule under/foo/bar/ has noeffect here, since access cannot be revoked by a child path.

While it may not seem immediately intuitive, this is a powerful part of therules language and allows for very complex access privileges to be implementedwith minimal effort. This is particularly useful foruser-based security.

However,.validate rules do not cascade. All validate rulesmust be satisfied at all levels of the hierarchy for a write to be allowed.

Additionally, because rules do not apply back to a parent path, read or writeoperation fail if there isn't a rule at the requested location or at a parentlocation that grants access. Even if every affected child path is accessible,reading at the parent location will fail completely. Consider this structure:

{  "rules": {    "records": {      "rec1": {        ".read": true      },      "rec2": {        ".read": false      }    }  }}

Without understanding that rules are evaluated atomically, it might seemlike fetching the/records/ path would returnrec1but notrec2. The actual result, however, is an error:

vardb=firebase.database();db.ref("records").once("value",function(snap){//successmethodisnotcalled},function(err){//errorcallbacktriggeredwithPERMISSION_DENIED});

FIRDatabaseReference*ref=[[FIRDatabasedatabase]reference];[[_refchild:@"records"]observeSingleEventOfType:FIRDataEventTypeValuewithBlock:^(FIRDataSnapshot*snapshot){// success block is not called}withCancelBlock:^(NSError*_Nonnullerror){// cancel block triggered with PERMISSION_DENIED}];

varref=FIRDatabase.database().reference()ref.child("records").observeSingleEventOfType(.Value,withBlock:{snapshotin// success block is not called},withCancelBlock:{errorin// cancel block triggered with PERMISSION_DENIED})

FirebaseDatabasedatabase=FirebaseDatabase.getInstance();DatabaseReferenceref=database.getReference("records");ref.addListenerForSingleValueEvent(newValueEventListener(){@OverridepublicvoidonDataChange(DataSnapshotsnapshot){// success method is not called}@OverridepublicvoidonCancelled(FirebaseErrorfirebaseError){// error callback triggered with PERMISSION_DENIED});});

curl https://docs-examples.firebaseio.com/rest/records/# response returns a PERMISSION_DENIED error

Since the read operation at/records/ is atomic, and there's no read rule that grants access to all of the data under/records/, this will throw aPERMISSION_DENIED error. If we evaluate this rule in the security simulator in ourFirebase console, we can see that the read operation was denied:

Attempt to read /records with auth=Success(null)    /    /recordsNo .read rule allowed the operation.Read was denied.

The operation was denied because no read rule allowed access to the/records/ path, but note that the rule forrec1 was never evaluated because it wasn't in the path we requested. To fetchrec1, we would need to access it directly:

vardb=firebase.database();db.ref("records/rec1").once("value",function(snap){// SUCCESS!},function(err){// error callback is not called});

FIRDatabaseReference*ref=[[FIRDatabasedatabase]reference];[[refchild:@"records/rec1"]observeSingleEventOfType:FEventTypeValuewithBlock:^(FIRDataSnapshot*snapshot){// SUCCESS!}];

varref=FIRDatabase.database().reference()ref.child("records/rec1").observeSingleEventOfType(.Value,withBlock:{snapshotin// SUCCESS!})

FirebaseDatabasedatabase=FirebaseDatabase.getInstance();DatabaseReferenceref=database.getReference("records/rec1");ref.addListenerForSingleValueEvent(newValueEventListener(){@OverridepublicvoidonDataChange(DataSnapshotsnapshot){// SUCCESS!}@OverridepublicvoidonCancelled(FirebaseErrorfirebaseError){// error callback is not called}});

curl https://docs-examples.firebaseio.com/rest/records/rec1# SUCCESS!

Location variable

Realtime DatabaseSecurity Rules support a$locationvariable to match path segments. Use the$ prefix in front of your pathsegment to match your rule to any child nodes along the path.

{"rules":{"rooms":{//Thisruleappliestoanychildof/rooms/,thekeyforeachroomid//isstoredinside$room_idvariableforreference"$room_id":{"topic":{//Theroom's topic can be changed if the room id has "public" in it".write":"$room_id.contains('public')"}}}}}

You can also use the$variable in parallel with constant pathnames.

  {    "rules": {      "widget": {        // a widget can have a title or color attribute        "title": { ".validate": true },        "color": { ".validate": true },        // but no other child paths are allowed        // in this case, $other means any key excluding "title" and "color"        "$other": { ".validate": false }      }    }  }