Configure Rules for Writing/Reading Events

Overview

Ingrain is a service that allows you to add user activity logging without a backend (you can still use one if you wish to). Therefore, rules should be configured to ensure that the requests on behalf of the user that originates from the frontend is legitimate, i.e. the user is allowed to send the payload.

Access rule is a JSON object containing filters. The syntax is based on Mongodb's filters. It compares the JWT that represents the end user with the payload to make sure that the user is authorized to make the request.

JWT

This is the user's JWT that you will be sending in the Authorization header as a bearer token. The structure is the payload of the JWT. To refer to the token in the rules, use token. For example, {{ token.sub }} means to use the value of token.sub at runtime. The double brackets ({{ }}) indicates that the variable within it should be interpolated with the actual value at runtime.

Payload Properties

In write requests, the payload would be the event in the request body. In read requests, the payload is the database rows. Both of these correspond to the AppUserEvent type, which means that the properties in AppUserEvent are available for rules checking.

For more details, refer to REST APIs or expand the details below.

See AppUserEvent

Properties	Type	Description
actorId	String	ID of the user who performed the action.
actorDisplayName	String	User's name to display in Ingrain's UI components.
actorMetadata	Any | null	Additional metadata for the user. This can be any JSON object. Do not store any sensitive or confidential information here. Fields in this object are also available when defining access control rules.
entityId	String	ID of the entity which the action is performed on.
entityName	String	Unique name of the entity, e.g. "personal-token", "task".
entityDisplayLabel	String	Entity's name to display in Ingrain's UI components, e.g. "Personal Token", "Task".
entityMetadata	Any | null	Additional metadata for the entity. This can be any JSON object. Do not store any sensitive or confidential information here. Fields in this object are also available when defining access control rules.
appUserOrgId	String | null	Use this to store your user's team/org/group ID if your application has such concepts. This is a common use case and hence this field was created as a convenience over storing it in actorMetadata.
entityPropName	String | null	The property of the entity that was changed, e.g. "name", "owner".
action	CREATE | UPDATE | DELETE | VIEW	The action performed.
oldValue	String | null	The old value. Do not store any sensitive or confidential information here. If the updated entity is something confidential, for example an access token, the value should not be sent.
newValue	String | null	The new (updated) value. Do not store any sensitive or confidential information here. If the updated entity is something confidential, for example an access token, the value should not be sent.

Examples

Write Example

{
  "appUserOrgId": {
    "$in": "{{ token.org_memberships }}"
  },
  "actorId": "{{ token.sub }}"
}

Explanation:

• token is the JWT token representing the app user that is sent with the request.
• The payload's appUserOrgId must be in one of the user's org_memberships, i.e. a user can only write data for an organization they are a member of.
• The actorId must be equal to the user's ID (token.sub), i.e. a user can only write data for themselves.

Read Example

{
  "appUserOrgId": {
    "$in": "{{ token.org_memberships }}"
  }
}

Explanation:

• token is the JWT token representing the app user that is sent with the request.
• The event's appUserOrgId must be in one of the user's org_memberships, i.e. a user can only read data that belongs to an organization they are a member of.

Common Operators

Operators	Notes
$and	Logical AND operator. Value should be an array of expression. Reference.
$not	Negation. Reference.
$or	Logical OR operator. Reference.
$eq, $gt, $ne, $in, etc.	See https://www.mongodb.com/docs/manual/reference/operator/query-comparison/ for more details. Note For $in operator, if the operand variable points to a JSON object, the variable will be interpolated with an array of the object's keys. For example, given the expression "$in": "{{ token.org_memberships }}", if token.org_memberships has the following value {"org1": "admin", "org2": "member"} , after interpolation at runtime, the query would become "$in": ["org1", "org2"].