Navigation

Define Roles And Permissions

The MongoDB service uses a strict rules system that prevents all operations unless they are specifically allowed. MongoDB Realm determines if each operation is allowed dynamically when it receives the request from the client based on roles that you define.

Roles are sets of document-level and field-level CRUD permissions and are chosen individually for each document associated with a query. This guide walks through configuring one or more roles for a collection.

Important

You must define at least one role before you can successfully query a collection.

Important
Sync Rules

This page describes data access rules for clusters where Realm Sync is not enabled. Synced clusters use a different rules model, which takes precedence over non-sync rules. If sync is enabled for a cluster, any non-sync rules defined for the cluster do not apply.

For more information on data access rules for synced clusters, see Define Sync Rules.

Note

This guide requires a linked MongoDB Atlas cluster. Roles and permissions do not apply to a linked Data Lake as you can only access a Data Lake from a system function.

1

You can create and manage roles and permissions from the MongoDB rules screen in the Realm UI. To get to the rules screen, click Rules beneath Data Access in the left navigation menu.

2

Data access roles and permissions are scoped to individual collections in a linked MongoDB cluster. To define roles and permissions for a collection, you need to create the collection namespace in the Realm UI.

Find the linked cluster that you want to define access permissions for in the rules sidebar and click its context menu (...). Select Add Database/Collection.

Add a Database/Collection button on the collection rules screen.
3

Enter the Database Name and Collection Name of the MongoDB collection that you want to use.

Collection namespace inputs.
4

You can choose to apply a rule template to the collection 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. You can also select No template, which creates a default role that can insert and delete documents but cannot read or update any fields.

Once you have selected and configured a template, click Add Collection.

A list of available collection rule templates.
Note

Templates do not rely on hard-coded field names, so when you select a template you will need to map certain fields in your documents to the template's fields. For example, the Users can only read and write their own data template requires that each document in the collection contains the ID of the user that owns it. If you select that template, you will need to specify the name of the field that contains the user id.

Additional fields for a collection rule template.
5

Depending on the rule template you selected, there will already be one or more pre-configured roles in the collection. 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.

6

A role's Apply When condition determines whether or not the role applies to a particular document 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.

A MongoDB Role's Apply When Expression
7

Document-level permissions determine a role's ability to insert, delete, and search documents in the collection. To define the role's Document-Level Permissions, check the box for each operation that the role has permission to execute.

Once you have defined the role's document-level permissions, click Done Editing.

A MongoDB Role's Document-Level Permissions
8

Field-level permissions determine if a role can read and write to specific fields within a given document. You can define the field-level permissions for a role in that role's column on the Rules page.

To define permissions for all fields:

Click Add Field, enter the field name, then click the green check next to the input box to confirm the name. In the new field's row, check the Read and Write boxes to indicate whether the role can read or write to the field.

A role with permission to read and write to specific fields

To define permissions for a specific field:

Click Add Field, enter the field name, then click the green check next to the input box to confirm the name. In the new field's row, check the Read and Write boxes to indicate whether the role can read or write to the field.

A role with permission to read and write to specific fields

To define default permissions for unlisted fields:

Check the Read and Write boxes for All Additional Fields to indicate the role's read and write privileges for any fields that aren't specifically configured.

A role with permission to read any unspecified fields
9

Repeat steps 5 through 8 of this procedure for any additional roles that you want to configure.

Note

Realm evaluates roles in order from left-to-right. A user can only have one role per document, so once Realm finds a role that applies to the current document it skips evaluating any remaining roles and immediately begins evaluating a role for the next document in the query.

10

Once you have finished defining roles for the collection, click Save. Realm will immediately begin using the roles you defined for all incoming queries on the collection.

Give Feedback