Role-based Permissions
On this page
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.
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.
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.
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.
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
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 Document-level read permissions take priority over any field-level
permissions. If a role has document-level To define a default fallback alongside field-level rules, use
| ||||||||
write Expression Default: false | An expression that evaluates to Document-level write permissions take priority over any field-level
permissions. If a role has document-level To define a default fallback alongside field-level rules, use
Important Implicit Read Permission Any time a role has Note MongoDB Expansions You can use MongoDB expansions, like | ||||||||
insert Expression Default: true | An expression that evaluates to
Note Document-level | ||||||||
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 Important Realm performs | ||||||||
fields Document Default: {} | A document where the value of each field defines the role's field-level
Note Permission Priority Document-level | ||||||||
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 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
| ||||||||
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. |