Securing your data
Ensure your users can only access and modify authorised data using Security Rules.
Setting your Security Rules
Navigate to the Security tab in the Database section of the Sphere Kit Dashboard.
Following that, click the New revision button to write a new draft of the security rules. An editor will appear in the centre panel and tools to test your rules will appear on the right panel. You can use the test panel to simulate authentication state or the request/target to test if your rules work correctly.
If you would like to log errors that occurred while your rules were being evaluated (runtime errors) during actual requests to the database, click the Rule logs button. Logs will appear as errors are thrown and are kept for up to 14 days.
Use this feature in debugging environments only because user data may be logged!
Writing Security Rules
Rules can be represented as JSON. Start with a blank object.
{}Match paths
Next, specify the match paths for each rule group. You can specify as many match paths as you want (subject to the operation limit).
Matching rules will be ORed together (i.e. if one rule matches and the other does not match, the operation will be allowed).
When parts of a path are put in curly braces, it matches any value for that path segment (i.e. any document in mycollection). Additionally, document becomes a variable with the name of the document as the value.
{
"mycollection/{document}": {
...
}
}Specify an asterisk (*) in after the path variable name to match all subpaths. The variable path becomes the whole subpath.
{
"mycollection/{path*}": {
...
}
}Rule types
Within a rule group, you can specify different rules for each rule type. Rule types are one of: add, update, get, delete. Rule types can be combined to share the same rules using commas.
{
"mycollection/{document}": {
"get": {
...
},
"add,update,delete": {
...
}
}
}Variable expressions
Variable expressions access a certain value, either stored in a variable or from the database. They start with the prefix $$. To access fields within an object, use <object>.<field>
For example, $$request.user.level or $$currentMillis.
Here are the variables that are available by default when rules are being evaluated:
request
user (available if authenticated)
uid (string)
metadata (additional metadata set by Achievements APIs, object)
isBanned (boolean, optional)
achievements (list of achievement IDs obtained)
body (available if provided)
target
path (string)
name (string)
data (for update and delete: available if document exists, for add: never available, for get: always available)
currentMillis (number)
null
If something is not available, it will be undefined and can be checked using the $exists operator.
Reference variables
You can also access other documents as a variable using the syntax $$ref(mycollection/mydocument).<field>. You can even embed variables in the reference path like this:
$$ref(mycollection/{$$request.user.uid}).
The value of the reference variable is similar to that of target.
path (string)
name (string)
data (available if document exists)
Document data is cached for the rest of the rule processing operation, or throughout a batch write.
Rule operations
Rule operations is the logic that defines whether an operation should be allowed. They can be top-level (evaluating to a value without being operated on a variable), or on-value (evaluating to a boolean upon operation on a variable).
Note that in all operations, the key of an operations object should be either a variable reference, an operator or a literal string.
Value expressions
These expressions evaluate to values that can be used with other expressions to create conditions.
On-value operations
These expressions evaluate to booleans, with the key being a variable expression and the value being a dictionary with the operations. If you would like multiple operations on the same variable expression, either put multiple dictionaries in an $and operator, or put the operations within the dictionary value of the key. See Example 2 in the Examples section.
Implicit operations
When both the key and the value of a rule object is not an on-value operator, an implicit equal operation is performed between the resolved key and value. This is equivalent to performing the $eq operation.
Example:
{
"$$request.body.number": {
"$add": [2, "$$ref(constants/game).data.magicNumber"]
}
}
// is equivalent to
{
"$$request.body.number": {
"$eq": {
"$add": [2, "$$ref(constants/game).data.magicNumber"]
}
}
}Additional notes
There is a maximum of 1000 operations for security rules.
GeometryCollection GeoJSON objects are not supported for security rules.
Examples
A set of rules that restricts players to only get location documents where the treasure box is near them.
{
"locations/{document}": {
"get": {
"$$target.data.location": {
"$nearSphere": {
"$geometry": {
"type": "Point",
"coordinates": [103.7749, 1.3338]
},
"$maxDistance": 100
}
}
}
}
}A set of rules that allows players to update their own weapons, but only allowed weapons, and only if
skillLevelis greater than 10 but lesser than 20.
// Method 1 (preferred)
{
"players/{document}": {
"get": true,
"update": {
"$$request.body.weapons": {
"$all": ["sword", "shield"]
},
"$$request.body.skillLevel": {
"$gt": 10,
"$lt": 20
}
}
}
}
// Method 2 (more flexible)
{
"players/{document}": {
"get": true,
"update": {
"$$request.body.weapons": {
"$all": ["sword", "shield"]
},
"$and": [
{
"$$request.body.skillLevel": {
"$gt": 10
}
},
{
"$$request.body.skillLevel": {
"$lt": 20
}
}
]
}
}
}A set of rules that ensures a power levels list has an element with at least 20 when the players are updating their document.
{
"players/{document}": {
"get": true,
"update": {
"$$request.body.powerLevels": {
"$elemMatch": {
"$gte": 20
}
}
}
}
}Last updated