Permissions in ContentGrid operate on the level of entities. By default, all permissions are denied and you cannot read or write any data. In order to grant a permission, you must define a policy. A policy is created for a particular entity and states that certain operations are allowed on that entity under certain conditions. For instance, a policy might say that the read operation is allowed on the invoice entity if the user has the bookkeeping attribute.
The currently supported operations are:
Create: The creation of an entity. Policies involving entity attributes are evaluated against the attributes that you send. This corresponds to http POST.
Read: Covers both reading a specific entity referred by id, as well as listing all visible entities. If you’re getting an entity by id but you don’t meet all the conditions, you will get a “Not Found” error. If you’re listing all entities, the list will be filtered down to the entities for which you meet the conditions. This corresponds to http GET and http HEAD.
Update: Updating the attributes and relations of an entity. If there are policies specifying conditions on the attributes, you must meet the conditions both before and after the update to the attributes. This corresponds to http PUT and http PATCH.
Delete: Deleting an entity. This corresponds to http DELETE.
A policy has a list of conditions. If this list is empty, the operation in the policy is simply allowed. Otherwise, all the conditions have to match for the policy to allow access.
For instance, you can have two policies for the blog entity. The first policy has the operation READ and no conditions. The second policy has the operations CREATE and UPDATE, but also has a condition stating that the user must have the blogger attribute equal to true. The consequences of these policies are that anyone can read (and list) blog entities, but only people marked as bloggers can write them.
A condition consists of three parts:
A left value: This is the value that you want to check. It can be an entity attribute, a user attribute, or a constant.
A comparison operator: This is the symbol that defines the type of comparison you want to make. For example, if you want to check whether the left value is equal to the right value, you would use the equals operator. If you want to check whether the left value is a list that contains the right value, you would use the contains operator.
A right value: This is the value that you want to compare the left value to. It can be an entity attribute, a user attribute, or a constant.
There are three types of values that can be used in a condition:
Entity attribute: This refers to an attribute of the entity being accessed, or to an attribute of an entity that has a relation to the entity being accessed. For example, if you have a policy that controls access to a report, you could use the report’s confidentiality level as a value. If you have a policy that controls access to an employee’s information, you can use the employee’s relation to their department to ensure that only people in a particular department are visible.
User attribute: This refers to a characteristic of the user who is trying to access the resource. For example, if you have a policy that controls access to files private to a particular department, you can verify that the user is a member of the department to which the file belongs.
Constant: This is a fixed value that you define in the condition. It can be of subtype boolean, number, or string. It is useful as the right value side of a comparison where the left value is an entity attribute or user attribute. For example, if you have a policy that says admins can see everything, you could use a constant value of true as the right value in a condition where the left value is user.is_admin.
Allowing access to users of certain department: user.department equals "Sales"
Allow access when attribute category has a certain value: entity.category equals "Published"
Allow access where attribute vat matches the user attribute: entity.vat equals user.vat
Following the relation belongs_to to party, using the attribute department on party:
entity.belongs_to.department equals "Bookkeeping"
These are the comparison operators that you can use in a condition:
equals (=)
Used for any type of value, to check that the left value is equal to the right value
not equals (≠)
Used for any type of value, to check that the left value is different from the right value
greater than (>)
Used for numeric types or date types, to check that the left value is greater (or later in time) than the right
greater or equals (≥)
Used for numeric types or date types, to check that the left value is greater or equal (or later in time) than the right
less than (<)
Used for numeric types or date types, to check that the left value is smaller (or earlier in time) than the right
less than or equals (≤)
Used for numeric types or date types, to check that the left value is smaller or equal (or earlier in time) than the right
contains (∋)
Used with a collection as the type of the left value, to check that the right value appears in the collection
in (∈)
Used with a collection as the type of the right value, to check that the left value appears in the collection