Docs Menu

Role-based Permissions

On this page

  • Overview
  • What are Permissions?
  • What are Roles?
  • Why Define a Role?
  • How Realm Assigns Roles
  • Role Configuration
Note

The content in this section only applies when Realm Sync is not enabled. For information about configuring permissions when using Sync, see Sync Rules and Permissions.

Overview

What are Permissions?

A permission is a status that Realm assigns to individual users to control what they can and cannot do in your app. Realm uses both document-level and field-level permissions:

  • Document-level permissions control whether a user can insert, delete, modify, and search for a specific document in a MongoDB collection. These permissions always apply to the entire document regardless of the content.
  • Field-level permissions control whether a user can read or write the data in specific fields of a document. These permissions only affect the field they apply to, which means that a user may have read or write access to only a subset of the entire document.

What are Roles?

A role is a named set of permissions that a user may have for documents in a MongoDB collection. Each role represents a possible relationship between a user and an individual document. A user may play at most one role per document in a request.

You define the roles a user can play for the documents in a collection. Realm automatically assigns roles to the user at request time. Each role includes an Apply When expression that determines when Realm should assign the role to a user as well as a set of document-level and field-level permissions that apply to the role.

Realm only commits operations that a user is authorized to do based on their assigned roles. If a role does not have permission to read a document or some of its fields, Realm omits the document or fields from the results.

Example

Consider a collection named employees where each employee has their own document with all of their employment data. This collection might have two roles: Employee and Manager.

  • If a user requests their own document, their role is Employee. An employee can read and write their own data but can't create or delete their own documents.
  • If a user requests a document for someone whose name is listed in the user's manages arrays, their role is Manager. A manager can read and write their direct reports' data and can create and delete their documents.
  • If a user is neither an Employee nor a Manager for a given document, then they have no role and cannot read, write, or search that document.

Why Define a Role?

A role carries a specific set of permissions that you might expose to your app's users. A user may play at most one role for each document, so each distinct set of permissions that you need requires you to define a named role that encapsulates those permissions.

The exact roles and permissions that you define will vary based on your app's data and requirements. To determine good roles for a collection, consider your data from the perspective of your app's users and what it might mean to them.

Example

In addition to Employee and Manager roles, you might add a Teammate role to the employees collection to represent a user on the same team as the document's employee. Teammates can read each other's data but cannot modify it.

{
  "name": "Teammate",
  "apply_when": { "team": "%%user.data.team" },
  "insert": false,
  "delete": false,
  "read": true,
  "write": false,
  "search": true,
  "fields": {},
  "additional_fields": {
    "read": true,
    "write": false
  }
}

How Realm Assigns Roles

Realm dynamically assigns roles for every request. A user may play different roles between documents in the same request and their role for a given document may differ between requests.

When Realm receives a MongoDB request, it applies filters to the request and then runs the filtered request query. Realm evaluates and assigns roles individually for each document that this query matches and returns.

Example

This request would cause Realm to evaluate a role for every document in the restaurants collection where the city field is set to "Chicago":

db.restaurants.updateMany(
  { "city": "Chicago" },
  { "$set": { "city": "Chicago, IL" } }
);

A role applies to a given document if its Apply When expression evaluates to true when run against the document.

  • If one or more roles apply to a given document, Realm assigns only the first matching role based on the order in which the roles are defined.
  • If no roles apply to a document, then Realm prevents the user from reading, writing, or searching the document in any way.
Example

An employee will always be on their own team, so both the Employee and Teammate roles apply to them for their own document. However, they can only one play one role, so we want to use Employee because it's more specific.

To configure this, specify Employee earlier than Teammate in the collection's role definitions:

Role Configuration

Note

To learn how to configure and deploy a role in your app, see Define Roles And Permissions.

For examples of expressions and roles for common scenarios, see Rule Templates & Examples.

You define roles for specific collections in your linked cluster.

A role configuration has the following form:

{
   "name": "<Role Name>",
   "apply_when": { Expression },
   "insert": { Expression },
   "delete": { Expression },
   "read": { Expression },
   "write": { Expression },
   "search": { Expression },
   "fields": {
      "<Field Name>": {
         "read": { Expression },
         "write": { Expression },
         "fields": { Embedded Fields }
      },
      ...
   },
   "additional_fields": {
     "read": { Expression },
     "write": { Expression }
   },
}
Field
Description
name
string
The name of the role. Role names identify and distinguish between roles in the same collection. Limited to 100 characters or fewer.
apply_when
Expression
An expression that evaluates to true when this role applies to a user for a specific document.
read
Expression
Default: false

An expression that evaluates to true if the role has permission to read all fields in the document.

Document-level read permissions take priority over any field-level permissions. If a role has document-level read permissions, it applies to all fields in the document and cannot be overridden.

To define a default fallback alongside field-level rules, use additional_fields instead.

write
Expression
Default: false

An expression that evaluates to true if the role has permission to add, modify, or remove all fields in the document.

Document-level write permissions take priority over any field-level permissions. If a role has document-level write permissions, it applies to all fields in the document and cannot be overridden.

To define a default fallback alongside field-level rules, use additional_fields instead.

Important
Implicit Read Permission

Any time a role has write permission for a particular scope it also has read permission even if that is not explicitly defined.

Note
MongoDB Expansions

You can use MongoDB expansions, like %%root and %%prevRoot, in write JSON expressions.

insert
Expression
Default: true

An expression that evaluates to true if the role has permission to insert a new document into the collection.

Note

Document-level insert permission does not imply that a role can insert any document. The role must also have write permission for all fields in an inserted document for the insert to succeed.

delete
Expression
Default: true
An expression that evaluates to true if the role has permission to delete a document from the collection.
search
Expression
Default: true

An expression that evaluates to true if the role has permission to search the collection using Atlas Search.

Important

Realm performs $search operations as a system user and enforces field-level rules on the returned search results. This means that a user may search on a field for which they do not have read access. In this case, the search is based on the specified field but no returned documents include the field.

fields
Document
Default: {}

A document where the value of each field defines the role's field-level read and write permissions for the corresponding field in a queried document.

"fields": {
  "<Field Name>": {
     "read": { Expression },
     "write": { Expression },
     "fields": <Fields Document>
  },
  ...
}
Note
Permission Priority

Document-level read or write permissions override all field-level permissions of the same type. If permissions are defined for a field that contains an embedded document, those permissions override any permissions defined for the document's embedded fields.

fields.<Field Name>.read
Expression
Default: false
An expression that evaluates to true if the role has permission to read the field.
fields.<Field Name>.write
Expression
Default: false
An expression that evaluates to true if the role has permission to add, modify, or remove the field.
fields.<Field Name>.fields
Document
Default: {}

A fields document that defines read and write permissions for fields that are embedded within this field in a queried document.

See the Field-level Permissions for Embedded Documents role pattern for more information.

additional_fields
Document
Default: {}

A document that defines the role's field-level read and write permissions for any fields in a queried document that don't have explicitly defined permissions.

"additional_fields": {
  "read": { Expression },
  "write": { Expression }
}
additional_fields.read
Expression
Default: false
An expression that evaluates to true if the role has permission to read any field that does not have a field-level permission definition.
additional_fields.write
Expression
Default: false
An expression that evaluates to true if the role has permission to add, modify, or remove any field that does not have a field-level permission definition.
←  RulesFilters →

On this page

Give Feedback
MongoDB logo
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center

Support

Social

© 2022 MongoDB, Inc.