Navigation

Define Sync Rules

Overview

In order to control who can sync, read, and write data, MongoDB Realm allows you to configure sync rules. Sync rules enforce two essential data access principles:

  • Users can only sync and read a realm that they are allowed to see.
  • Users can only sync and make changes to a realm that they are allowed to write to.

Rules are bundled into sync roles, which are then associated with a user to determine whether that user can sync, read, or write a given realm. You can edit roles in the MongoDB Realm UI or import them using the Realm CLI.

Rules and Realms

Rules apply to entire realms. That is, you can either sync an entire realm or none of it. This level of access control strikes a balance between suitability for most applications and scalability of Realm Sync.

Example

Consider an app that manages a chain of stores. By using the individual store ID as the partition key, we divide each store’s data into its own realm. We can grant the manager of each store write access only to the store they manage. In other words, the manager gets permission to modify any object within that realm.

However, with the store ID as partition key, we cannot grant write access to only part of a store. If we needed to grant access to specific sections of the store, we would instead design the app to use section IDs as the partition keys. How you intend to grant access should inform how you partition your data into realms.

Users and Sync Roles

A sync role is a set of realm-level permissions that MongoDB Realm evaluates when determining whether a user may sync a given realm. You select a property of the user object that MongoDB Realm uses to determine whether that user may sync the realm.

There are two initial roles:

  • Read-only: the user may sync the realm and read the data.
  • Read/Write: the user may sync the realm, read the data, and modify the data.

You may define custom roles with a rules expression. In a sync rules expression, access the partition key value with the %%partition expression expansion.

Example

Suppose the store management application uses custom JWT authentication. In order to control who can read and write store data, we provide the user object with two custom properties:

  • Store_List: an array of IDs of the stores that the user can read from.
  • Managed_Stores: an array of IDs of the stores that the user manages and can modify.

By adding store IDs to these arrays on the user object, we can:

  • Grant an employee read-only access to their own store.
  • Grant a manager read/write access to their own store, and read-only access to other stores.
  • Grant a regional manager read/write access to many stores.

The roles part of the cluster configuration file would look like this:

{
  "roles": [
    {
      "name": "Read-Write Role",
      "apply_when": {
        "StoreID" : "%%user.Managed_Stores"
      },
      "insert": true,
      "delete": true,
      "write": true
    },
    {
      "name": "Read Only",
      "apply_when": {
        "StoreID": "%%user.Store_List"
      },
      "insert": false,
      "delete": false,
      "read": true
    }
  ],
  ...
}

Procedure

1
2

Edit the Synced Cluster

Sync rules are scoped a synced MongoDB cluster. Select Define Permissions to edit permissions.

3

Select a Sync Rule Template

You can choose to apply a rule template to the cluster to simplify the process of configuring role permissions. Each template is a pre-configured set of roles and permissions that represents a common use case and data access pattern.

4

Create a New Role

Depending on the rule template you selected, there will already be one or more pre-configured roles on the synced cluster. You can use these roles as they are, tweak them to fit your use case, or add additional roles to cover more cases.

To add an additional role, click New Role. Enter a Name for the new role on the role configuration screen.

5

Define the Role’s “Apply When” Condition

A role’s Apply When condition determines whether or not the role applies to a particular partition for the user that issued a query.

Enter a JSON Expression in the role’s Apply When box. The expression should evaluate to true when the role applies to a given document.

6

Add Additional Roles

Repeat the previous step for any additional roles that you want to configure.

7

Save the Updated Sync Rules

Once you have finished defining roles for the synced cluster, click Save. Realm will immediately begin using the roles you defined for all incoming sync requests on the cluster.

1

Export Your Realm Application

To define roles and permissions with realm-cli, export an application directory for your application.

You can export your application from the Export tab of the Settings page in the Realm UI, or by running the following command from an authenticated instance of realm-cli:

realm-cli export --app-id=<App ID>
2

Add a Rule Configuration File

The sync rules for a cluster are configured in the configuration file of the cluster:

touch services/<cluster name>/config.json

The configuration file should have the following general form:

{
  "roles": [],
  "filters": [],
  "schema": {}
}
3

Add One or More Roles

Add a document to the roles array for each role that you want to configure. Role documents have the following form:

{
  "name": "<Role Name>",
  "apply_when": <JSON Expression>,
  "read": <boolean>,
  "write": <boolean>
}
Field Description
name Required. The name of the role. Limited to 100 characters or fewer.
apply_when Required. A JSON expression that determines when this role applies to a given partition.
read Optional. Default: false. A boolean that, if true, indicates that the role has permission to sync and read all objects in a partition.
write Optional. Default: false. A boolean that, if true, indicates that the role has permission to sync and write to all objects in a partition.
4

Import Your Application Directory

Once you have added your role configurations to the cluster sync configuration file, all that’s left is to import the rule.

Ensure that the rule configuration file is saved, then navigate to the root of the exported application directory. Log in to MongoDB Atlas with realm-cli:

realm-cli login --api-key="<my api key>" --private-api-key="<my private api key>"

Once you’re logged in, import the directory:

realm-cli import

Once the import completes, Realm will immediately begin using the roles you defined for all incoming requests to sync that partition.

Summary

  • Sync rules allow you to control who can read and write on which realm.
  • Roles are collections of permissions that realm evaluates to determine whether a user may sync a realm.
  • You can define rules in the Realm UI or by importing them with Realm CLI.