Understand Security Rules

Security Rules Language

Security rules are based on a flexible and powerful custom language that can support various levels of complexity and granularity. We can set specific or general rules according to the specific needs of our application. The security rules language uses a JSON structure, where key represents the operation type, and value is the condition for allowing the operation, which can be a boolean or an expression string. The syntax of the expression string is similar to the Javascript language; it is a single logical expression or multiple logical expressions combined with AND/OR operators. When the expression is evaluated, it determines whether the operation is allowed.

Since security rules are a new custom language, there is a learning curve. Please read this guide to better understand this rule language as you delve into more complex rules.

Basic Structure

Cloud Database

Security rules are based on a JSON structure, where value is a boolean or a JavaScript-like expression:

{
    "read": true,
    "write": <<condition>>,
    "create": true,
    "update": false,
    "delete": <<condition>>
}

It contains several key concepts.

• Operation Type: The JSON key represents the operation type for permission control. create, delete, read, and update correspond to the create, delete, read, and update operations on a collection. write is a shorthand for configuring write permissions (create, delete, update) to a collection. If create, delete, or update operations are not configured, the write configuration will be applied.
• Rule: The JSON value is the rule condition, which can be a boolean value or a logical expression (or a group of expressions). When the condition evaluates to true, it indicates that the operation is allowed.

By default, when encountering an undefined operation type, access to that operation is denied.

Cloud Storage

Security rules are based on a JSON structure, where value is a boolean or a JavaScript-like expression:

{
    "read": true,
    "write": <<condition>>,
}

It contains several key concepts.

• Operation Type: The JSON key represents the operation type for permission control. read and write correspond to the read and write operations on cloud storage files.
• Condition: The JSON value is the rule condition, which can be a boolean value or a logical expression (or a group of expressions). When the condition evaluates to true, it indicates that the operation is allowed.

By default, when encountering an undefined operation type, access to that operation is denied.

Cloud Function

Cloud Function Security Rules are based on a JSON structure with a unique hierarchy. The top-level key represents the function name, and the value is the permission configuration for the corresponding function, also in JSON format. The child configuration's key is the operation name (invoke), and the value is a boolean or a JavaScript-like expression:

{
  "*": {
    "invoke": "auth!==null"
  },
  "function1": {
    "invoke": false
  },
  "function3": {
    "invoke": true
  }
}

It contains several key concepts.

• Function name: The top-level key in JSON represents the function name, used to match and retrieve configuration for a specific function. The special * acts as a wildcard for all function names. When no specific function is matched, the configuration for * will be applied. Cloud Function Security Rules must include the * configuration.
• Operation Type: The sub-configuration JSON key under the function name represents the operation type. Currently, only invoke is supported and it must be invoke.
• Condition: The sub-configuration JSON value is the rule condition, which can be a boolean value or a logical expression (or a group of expressions). When the condition evaluates to true, it indicates that the operation is allowed. The expression only supports auth!=null.

Constructing conditions

Conditions can be boolean values or expression strings. The syntax of expression strings is similar to the Javascript language; they consist of either a single logical expression or multiple logical expressions combined using AND/OR operators. The evaluation result of the expression determines whether the operation is permitted.

Cloud Database

Predefined Variables

Variable	Type	Description
now	number	The current time, expressed in milliseconds since the Linux epoch.
auth	Auth	After a user logs in, provides uid (the user's unique ID) and loginType (login type). If the user is not logged in, it is null.
doc	Object	Represents the current record object when requesting data. Referencing doc in a condition will result in at most one read of this value from the service. This query will count against all service-related quotas for the resource.
request	Request	Represents the request object, which can be used to access request-related values.

Auth

Field Name	Type	Description
loginType	string	Login method
uid	string	The user's unique id. This value is not present in requests from WeChat Mini Programs.
openid	string	The user's openid, which only has a value when using WeChat login

LoginType Enum

Enum Value	Login Method Description
WECHAT_PUBLIC	WeChat Official Account
WECHAT_OPEN	WeChat Open Platform
ANONYMOUS	Anonymous login
EMAIL	Email Login
CUSTOM	Custom Login

Request

Field Name	Type	Description
data	object	Request data, present when the operation type is create or update, indicating that the request passes in a data object

Variables can be used in rule expressions. Through doc and request.data, you can obtain the current value of the data and the value passed in the request. For example, in an order collection, to protect the order amount from being tampered with, the following rule can be used:

{
    // ... //
    "update": "doc.price == request.data.price || request.data.price == undefined"
    // ... //
}

Built-in Methods

Currently only supports the get function. The only parameter must be database.collection.documentID. It accesses data from other documents to determine whether the user operation complies with security rules.

Cloud Storage

Predefined Variables

Variable	Type	Description
now	number	The current time, expressed in milliseconds since the Linux epoch.
auth	Auth	After a user logs in, provides uid (the user's unique ID) and loginType (login type). If the user is not logged in, it is null.
resource	Resource	Represents the metadata of the requested file. Referencing resource in a condition will result in at most one read of this value from the service.

Auth

Field Name	Type	Description
loginType	string	Login method
uid	string	The user's unique id. This value is not present in requests from WeChat Mini Programs.
openid	string	The user's openid, which only has a value when using WeChat login

LoginType Enum

Enum Value	Login Method Description
WECHAT_PUBLIC	WeChat Official Account
WECHAT_OPEN	WeChat Open Platform
ANONYMOUS	Anonymous login
EMAIL	Email Login
CUSTOM	Custom Login

Resource

Field Name	Type	Description
openid	string	File private ownership identifier, marks the owner id
path	string	The relative path of the file in cloud storage. The path does not include the bucket name. Format: path/image.jpg. The path must not start with path indicators such as ./, /, or .

Variables can be used in rule expressions. For example, files in the public directory are readable by all users, but users are restricted to writing data that belongs to themselves, and only the owner can modify it.

{
    "read": "/^public\\//.test(resource.path)",
    "write": "resource.openid == auth.uid"
}

Special Methods

Storage security rules support a special syntax that allows the introduction of regular expression objects via literals (e.g., /^reg\$/) within the rules. By invoking the test method on the regular expression object, you can verify whether parameters match the regular expression.

Note

1. When evaluating the result of test in a rule expression, it must be explicitly compared with true or false. For example, read: "/^public/.test('public') == true", rather than directly writing the expression read: "/^public/.test('public')".
2. Since security rule expressions are embedded within strings, if the regular expression involves characters that require escaping, multiple levels of escaping are necessary. For example: to match the string test/image, the regular expression would be /^test\/image/. When configured in a rule expression, it should be written as "/^test\\/image/.test('test/image')".

Cloud Function

Predefined Variables

Variable	Type	Description
auth	-	In function security rules, auth has only two states: null or non-null. Accessing member values of auth is not supported.

Operators

Operator	Description	Example	Description
==	Equal to	auth.uid == 'zzz'	The user's uid is zzz
!=	Not equal to	auth.uid != 'zzz'	The user's uid is not zzz
>	Greater than	a>10	The value of a is greater than 10
>=	Greater than or equal to	a>=10	The value of a is greater than or equal to 10
<	Less than	a&lt;10	The value of a is less than 10
<=	Less than or equal to	a<=10	The value of a is less than or equal to 10
in	In the set	auth.uid in ['zzz','aaa']	The user's uid is one of ['zzz','aaa']
!(xx in [])	Not in the set, using the in syntax as in !(a in [1,2,3])	!(auth.uid in ['zzz','aaa'])	The user's uid is not any of ['zzz','aaa']
&&	And	auth.uid == 'zzz' && a&gt;10	The user's uid is zzz and the value of a is greater than 10
||	Or	auth.uid == 'zzz' \|\| a>10	The user's uid is zzz or the value of a is greater than 10
.	Object property accessor	auth.uid	The user's uid
[]	Bracket notation property access	a[auth.uid] == 'zzz'	The value of the property in object a with the key being the user's uid is 'zzz'