Cross-service Rules (Rules Language
enhancement). We're excited to deliver one of the most popular feature requests
for Security Rules. Security Rules in Cloud Storage for Firebase now supports
cross-service Rules with two brand new functions, firestore.get()
and firestore.exists(). These functions let you query your
project's Firestore data, similar to the get() and
exists() functions in Firestore Rules.
How can you use it?
Say you have a social media app, and you want to allow users to share
photos with a set of friends. Your Firestore database stores data related
to your users in a collection called users, with a document for
each user’s UID.
Within each document (representing a user), there’s a list
called friends that contains other UIDs. The photos for the
main application are stored in Cloud Storage for Firebase, with each user
having a folder named for their UID.
To only allow each user to view the pictures of their friends, you can add
rules like:
Requests MonitorRules lets you inspect
requests made to your local Firestore Emulator in real-time, including the
request method, path, and how Security Rules were evaluated. Check out
this blog post
for more detail. It's available in the Emulator Suite that shipped in the
Firebase CLI v9.16.0.
How can you use it?
Under the new Firestore > Requests tab of the Emulator UI, you can view recent
requests and new ones as they come in. Click into any of them to view all
the details of the request.
Request Monitor is a great debugging feature generally, but is especially
useful for writing or debugging Security Rules. Clicking on any request will
show the details of the Rules evaluation. Statements that matched and were
evaluated will be highlighted and show the result of the evaluation. And
with all the details of the request, you may notice new access patterns
you want to build into your Security Rules!
Type ChecksRules now checks for common type errors
and warnings in the CLI, the Firebase Console, and the Emulator Suite. Errors will
block using or deploying your rules, but warnings will not. Take a look at the
examples below. Available in Rules Language v1, v2.
How can you use it?
You'll notice new warnings for things like a function that is never called,
when a function is called with the wrong number of arguments, or when a
variable is never used.
You'll also see errors if you hit one of the limits on code complexity that
we use to keep decisions from security rules extremely fast. Some examples
are if there are more than 10 local variables in a function or more than 20
path captures in one path. You'll also see an error if we need you to
resolve ambiguity; for example, if a function is redefined or a variable is
defined multiple times the same scope.
We hope the new errors and warnings help avoid common mistakes in rules
code. Let us know how they work for you!
Rules Playground You can now debug your Firestore and Storage
rules in the console by hovering over expressions in the Rules Playground.
Check out the documentation or example below for more
details.
How can you use it?
To use the Playground Debugger, start by running a simulation in the Rules
Playground. Then hover over either an expression in the rules or part of the
request in the right side bar. If you hover over part of the request in the
side bar, then the rule that used that information to make a decision will
be highlighted. If you hover on a rule, the parts of the request that caused
the decision will be highlighted.
The Rules Playground can't capture all test cases; keep using the
emulator suite for advanced cases. Use the
Rules Playground as a way to experiment or proof-of-concept new rules.
Map Diffs (Rules Language enhancement). Map Diffs
give the difference between maps. Since request and
resource objects are structured as maps, this is great for diffing
old and new data. Take a look at the
documentation and the examples below.
Available in Rules Language v1, v2.
How can you use it?
To use it in rules:
// Returns a MapDiff object
map1.diff(map2)
The MapDiffobject has the following methods:
addedKeys() // a set of strings of keys that are in after but not before
removedKeys() // a set of strings of keys that are in before but not after
changedKeys() // a set of strings of keys that are in both maps but have different values
affectedKeys() // a set of strings that's the union of addedKeys() + removedKeys() + updatedKeys()
unchangedKeys() // a set of strings of keys that are in both maps and have the same value in both
A practical example:
// This rule only allows updates where "a" is the only field affected
allow update: if request.resource.data.diff(resource.data).affectedKeys().hasOnly(["a"]);
Map.diff() doesn't require you to know in advance what all the fields will
be, so hopefully you can write more future-proof rules.
Local Variables (Rules Language enhancement). Local
variables are now supported in Security Rules! Create a local variable in
rules functions by using the keyword let. Take a look at the
documentation and the examples
below.
Available in Rules Language v2.
How can you use it?
Up to ten local variables can be created inside functions, and the function
still needs to end with a return statement.
For example, a function in Security Rules that determines the length of the
hypotenuse of a right triangle could use local variables:
rules_version = "2";
function length_of_hypotenuse(a, b) {
let a2 = math.pow(a, 2);
let b2 = math.pow(b, 2);
let c2 = a2 + b2;
let c = math.sqrt(c2);
return c;
}
(We also implemented math.pow and math.sqrt so we could use this example.)
Ternary Operators (Rules Language enhancement). If
your Security Rules contain complex control flow, you'll appreciate that there's
now a Ternary Operator in Rules for Firestore and Storage. It works just as
you'd expect: condition ? true case : false case. Take a look at
the documentation
and the examples below.
Available in Rules Language v1, v2.
How can you use it?
In this example, the ternary operator sets the path to look up group
membership, and then the function returns the result of an exist call:
function isGroupMember(group, visibility) {
let membership = visibility == "adminsOnly"
? /databases/$(db)/documents/admins/$(request.auth.uid)
: /databases/$(db)/documents/$(group)/$(request.auth.uid);
return exists(membership);
}
Set type (Rules Language enhancement). Sets are now
a supported type in Firebase Security Rules! This is great for enforcing required and optional
fields. Lists can be converted into Sets by calling myList.toSet(). Available
in Firebase Security Rules Language v1, v2.
How can you use it?
What can you do with Sets? Mostly compare to and diff against other Sets:
mySet == myOtherSet #Comparing a set to another type returns false.
mySet.size()
mySet.hasAll(myOtherSet) # Can also be passed a List
mySet.hasOnly(myOtherSet) # Can also be passed a List
mySet.hasAny(myOtherSet) # Can also be passed a List
mySet.union(myOtherSet)
mySet.intersection(myOtherSet)
mySet.difference(myOtherSet)
Here's an example of using Sets to ensuring that a document only has
fields "a", "b", and "c":
Rule evaluation metrics in Stackdriver. Rule evaluation
metrics are now exported from Firebase into Stackdriver for Cloud Firestore, the
Realtime Database, and Cloud Storage! This lets you set up monitoring and
alerting around authorization requests for your app. Available in Rules
Language v1, v2.
How can you use it?
Three metrics are available in Stackdriver:
Allowed Requests, when the rules grant access
Denied Requests
Errored Requests
When you roll out a new version of your app or security rules, you can now
monitor the performance of your Rules evaluations. The alerts
available through Stackdriver let you configure notifications to
stay on top of your data security. Be sure to read the docs for
Cloud Firestore,
Realtime Database,
and Cloud Storage.
Map get (Rules Language enhancement). Fetching values
within a map just got easier with get. It takes two arguments: the first is
the key within the Map, and the second is a default value to return if the key
doesn't exist. Check out the documentation
and the following examples. Available in Rules Language v1, v2.
How can you use it?
In this example, the Map has a key "foo", so a call to get
returns the corresponding value "1":
{ "foo": 1, "bar": 2 }.get("foo", 7) => 1
Here, since the Map doesn't have key "baz", the default value "7" is returned:
{ "foo": 1, "bar": 2 }.get("baz", 7) => 7
How is this different than Map indexing, like {"foo": 1}["foo"] => 1?
Indexing and gets will both let you fetch a field from a document or other Map,
including nested fields. Gets also let you provide a default value,
which can mean less code to write and maintain in your Rules.
To demonstrate the syntax for get on a nested Map , here's an example
that allows the client to read a data item if it has been tagged as
"published". The rule takes a Rulesrequest object (a Map); it
fetches the value for resource.data.visibility; it checks if that value is
"published". If the value is null, get returns the default value "hidden",
the string comparison fails, and read access is denied:
allow read: if request.get(["resource", "data", "visibility"], "hidden") == "published";
Hashing (Rules Language enhancement). Ever want to
hash a value in Firebase Security Rules, either to obscure content that you don't want in
plaintext or to avoid handling something unwieldy? Now that that Hashing is
available in Firebase Security Rules, you can! Take a look at the
documentation and the examples below.
Available in Rules Language v1, v2.
For example, previously, if the version of an email in Firestore was hashed
with SHA-256, you wouldn't be able to compare that email to the plaintext email
sent with the auth object. Now you can:
Alternatively, if you have a field in a document for users to store their
novellas, you may want to have a shorter identifier for that very long string:
match /novellas/{hash} {
allow write: if hash == hashing.sha256(request.resource.data.
novella.utf8()) && resource == null
}
Strings are treated as UTF-8-encoded bytes, and the return value is a
Bytes type:
String replace (Rules Language enhancement). Sometimes a String in your Rules isn't exactly
in the form you need it. Now you have String.replace() to do some light cleanup.
It works like you would guess: "myString".replace("my", "your") => "yourString".
This function is described in the documentation
and another example is shown below. Available in Firebase Security Rules Language v1, v2.
Another example?
This is an example of removing the leading "+" from phone numbers, to have a
canonical version of the number to do other things with:
request.auth.token.phone_number.replace('+', '')
This feature was requested from StackOverflow, so keep asking us for things!