Sync Rules and Permissions

Read Permissions

A user with read permissions for a given partition can view all fields of any object in the corresponding synced realm. Read permissions do not permit a user to modify data.

Write Permissions

A user with write permissions for a given partition can modify the value of any field of any object in the corresponding synced realm. Write permissions require read permissions, so any user that can modify data can also view that data before and after it's modified.

Global Permissions

You can define global permissions that apply to all users for all partitions. This is, in essence, a choice to not implement user-specific permissions in favor of universal read or write permissions that apply to all users.

To define a global read or write permission, specify a boolean value or a JSON expression that always evaluates to the same boolean value.

true

false

{ "%%true": true }

Permissions for Specific Partitions

You can define permissions that apply to a specific partition or a groups of partitions by explicitly specifying their partition values.

{ "%%partition": "PUBLIC" }

{
  "%%partition": {
    "$in": [
      "PUBLIC (NA)",
      "PUBLIC (EMEA)",
      "PUBLIC (APAC)"
    ]
  }
}

Permissions for Specific Users

You can define permissions that apply to a specific user or a group of users by explicitly specifying their ID values.

{ "%%user.id": "5f4863e4d49bd2191ff1e623" }

{
  "%%user.id": {
    "$in": [
      "5f4863e4d49bd2191ff1e623",
      "5f48640dd49bd2191ff1e624",
      "5f486417d49bd2191ff1e625"
    ]
  }
}

Permissions Based on User Data

You can define permissions that apply to users based on specific data defined in their custom user data document, metadata fields, or other data from an authentication provider.

{ "%%user.custom_data.readPartitions" : "%%partition" }

{ "%%user.data.writePartitions" : "%%partition" }

Function Rules

You can define complex dynamic permissions by evaluating a function that returns a boolean value. This is useful for permission schemes that require you to access external systems or other custom logic that you cannot express solely in JSON expressions.

{
  "%%true": {
    "%function": {
      "name": "canReadPartition",
      "arguments": ["%%partition"]
    }
  }
}

// canReadPartition
exports = async (partition) => {
  const cluster = context.services.get("mongodb-atlas");
  const permissions = cluster
    .db("myApp")
    .collection("permissions");
  const { canRead } = await permissions.findOne({ partition });
  return canRead.includes(context.user.id);
}

Read Permissions

A user with read permissions for a given collection can view all fields of any object matching the client-side query. Read permissions do not permit a user to modify data.

Write Permissions

A user with write permissions for a given collection can modify the value of any field of any object matching the client-side query. Write permissions require read permissions, so any user that can modify data can also view that data before and after it's modified.

Admin Read/Write, User Write Self

In this permission strategy, users with the admin role can read and write any document. Users who do not have the admin role can read any document, but can only write their own data.

{
  "Employees": [{
        "name": "admin",
        "applyWhen": { "%%user.custom_data.isAdmin": true},
        "read": {}, // evaluates to the same as true
        "write": {}
      },
      {
        "name": "self",
        "applyWhen": {},
        "read": {},
        "write": {"employee_id": "%%user.id"}
      }
   ]
}

Document Owner Read Only

In this permission strategy, users can read only their own documents. Users cannot write, even to their own documents.

{
  "Employees": [{
        "name": "everyone",
        "applyWhen": {},
        "read": {"owner_id": "%%user.id"},
        "write": false
      }
  ]
}

Global Admin, Department Admin, Department Member

In this permission strategy, users with the globalAdmin session role can read and write to any document. Users with the departmentAdmin session role can read any document, but can only write to documents in their department. Users with the departmentMember session role can read any document in their department, but can't write to any documents. Members can only read documents in their own departments; they cannot read documents for other departments.

{
 "Employees": [{
     "name": "globalAdmin",
     "applyWhen": {
       "%%user.custom_data.isGlobalAdmin": true
     },
     "read": {},
     "write": {}
   },
   {
     "name": "departmentAdmin",
     "applyWhen": {
       "%%user.custom_data.isLocalAdmin": true
     },
     "read": {},
     "write": {
       "department": "%%user.custom_data.department"
     }
   },
   {
     "name": "departmentMember",
     "applyWhen": {},
     "read": {
       "department": "%%user.custom_data.department"
     },
     "write": false
   }
 ]
}

Custom and Default Roles

This permission strategy combines custom and default roles. The custom session role applies to the Employees collection. The Store collection is not listed in the configuration, and has no custom session role, so it also evaluates to the default role.

Sync attempts to find a matching session role by traversing the session roles in descending order. List the most specific custom session roles first, getting gradually more general, so the user "falls through" to the correct session role. If no role applies, and you have defined a default role, the user gets the default role permissions.

 {
  "rules": {
    "Employees": [
      {
        "name": "employeeWriteSelf",
        "applyWhen": {},
        "read": {},
        "write": {
          "employee_id": "%%user.id"
        }
      }
    ]
  },
  "defaultRoles": [
    {
      "name": "admin",
      "applyWhen": {
        "%%user.custom_data.isGlobalAdmin": true
      },
      "read": {},
      "write": {}
    },
    {
      "name": "owner",
      "applyWhen": {
        "%%true": {
          "%function": {
            "name": "isOwner",
            "arguments": [
              "%%user.id"
            ]
          }
        }
      },
      "read": {},
      "write": {
        "owner_id": "%%user.custom_data.ownerId"
      }
    },
    {
      "name": "shoppers",
      "applyWhen": {},
      "read": {},
      "write": false
    }
  ]
}