Query Roles¶
Overview¶
A MongoDB service role is a group of document-level and field-level CRUD permissions that MongoDB Realm evaluates and enforces for each document that matches an incoming request.
Roles define what the user who issued a query is allowed to do with a particular document, including which fields they can read and write to and whether or not they can insert or delete entire documents. Every role is associated with a specific collection in a linked cluster, and any collection can include multiple roles.
Role Evaluation Process¶
When MongoDB Realm receives a query request, it determines which documents
in the collection the query applies to and evaluates a separate role for
each document. To assign a role to a document, MongoDB Realm steps through
each role definition in order and evaluates the Apply When
JSON expression that you defined for
the role. If a role's Apply When expression evaluates to
true
, MongoDB Realm assigns the role to the current document and moves
on to the next document. If the expression evaluates to false
, MongoDB Realm
evaluates the next role definition. If no roles apply to a document,
MongoDB Realm withholds the entire document and prevents any modifications.
Query Role Configuration¶
{ "name": "<Role Name>", "apply_when": <JSON Expression>, "insert": <Boolean|JSON Expression>, "delete": <Boolean|JSON Expression>, "read": <Boolean|JSON Expression>, "write": <Boolean|JSON Expression>, "search": <Boolean|JSON Expression>, "fields": { "<Field Name>": { "read": <Boolean|JSON Expression>, "write": <Boolean|JSON Expression>, "fields": <Fields Document> }, ... }, "additional_fields": { "read": <Boolean|JSON Expression>, "write": <Boolean|JSON Expression> }, }
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
name String | The name of the role. Role names are useful for identifying and distinguishing between roles. Limited to 100 characters or fewer. | ||||||||
apply_when Document | A JSON Expression that
evaluates to true when this role should be applied. | ||||||||
read Boolean or Document Default: false | A boolean or JSON Expression
that evaluates to Document-level read permissions take priority over any
field-level permissions. If a role has a document-level | ||||||||
write Boolean or Document Default: false | A boolean or JSON Expression
that evaluates to Document-level write permissions take priority over any
field-level permissions. If a role has a document-level Important Implicit Read Permission Any time a role has Note MongoDB Expansions You can use MongoDB expansions, like | ||||||||
insert Boolean or Document Default: true | A boolean or JSON Expression
that evaluates to Note Document-level | ||||||||
delete Boolean or Document Default: true | A boolean or JSON Expression
that evaluates to true if the role has permission to delete a
document from the collection. | ||||||||
search Boolean or Document Default: true | A boolean or JSON 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 Boolean or Document Default: false | A boolean or JSON Expression
that evaluates to true if the role has permission to read
the field. | ||||||||
fields.<Field Name>.write Boolean or Document Default: false | A boolean or JSON 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 Boolean or Document Default: false | A boolean or JSON 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 Boolean or Document Default: false | A boolean or JSON 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. |
Role Templates¶
This section demonstrates patterns for common use cases that you might encounter when you define roles for your collection.
Apply When Expressions¶
MongoDB Realm determines if a role applies to a given document by evaluating the Apply When expression that you define for each role.
This section contains Apply When templates for common
scenarios. To apply an expression to a role, find the scenario that most
closely matches your use case and then copy and paste the provided
template into the Apply When field of the role. You may need
to modify placeholder values (denoted by <angle brackets>
) in the
template to match your collection.
You can use the Apply When expressions on this page for external services as well as in MongoDB roles.
The User Is the Document Owner¶
This expression evaluates to true
if the active user's unique id
value matches the value of the specified field.
{ "<Owner ID Field>": "%%user.id" }
An Array Field Contains the User's ID¶
This expression evaluates to true
if the active user's unique id
value matches one or more values in the specified array field.
{ "<Array Field>": "%%user.id" }
The User Has An Email Address¶
This expression evaluates to true
if the active user has any email
address listed in their internal user object.
{ "%%user.data.email": { "%exists": true } }
The User Has A Specific Email Address¶
This expression evaluates to true
if the active user's email address
matches the specified email address.
{ "%%user.data.email": "<Email Address>" }
A Field Contains the User's Email Address¶
This expression evaluates to true
if the active user's email address
matches the value the specified field.
{ "%%root.email": "%%user.data.email" }
An Array Field Contains the User's Email Address¶
This expression evaluates to true
if the active user's email address
matches one or more string values in the specified array field.
{ "<Array Field>": "%%user.data.email" }
A Field Satisfies a Complex Condition¶
This expression evaluates to true
if the Function isAuthorizedUser
returns true
when passed the
active user's id value.
You can call any MongoDB Realm Function from a JSON expression using the
%function
operator.
{ "%%true": { "%function": { "name": "isAuthorizedUser", "arguments": ["%%user.id"] } } }
CRUD Permissions¶
MongoDB Realm uses a role's permissions configuration to determine if the active user can insert or delete a document as well as which fields in the document they can read and write.
This section contains templates that define role permissions for
common scenarios. To apply a set of permissions to a role, find the
scenario that most closely matches your use case. Update the role's
permissions table to match the provided screenshot or copy and paste the
provided template into the collection's advanced mode configuration. Make sure that you modify
any placeholder values (denoted by <angle brackets>
) in the template
to match your needs.
The Role Can Read All Fields but Cannot Write¶
To allow a role to read any field, set the document-level read
field
to true
.
![]() |
|
The Role Can Read & Write All Fields¶
To allow a role to read or write any field, set the document-level
write
field to true
. Document-level writes require read
permission, so the role will be able to read all fields.
![]() |
|
The Role Can Read All Fields & Write to Specific Fields¶
To allow a role to read all fields, set the document-level read
field to true
. To specify a field that the role can write to, set
the write
field to true
in the field's configuration document,
which is embedded in the fields
document.
![]() |
|
The Role Can Read & Write All Fields but Cannot Insert New Documents¶
To allow a role to read or write any field, set the document-level
write
field to true
. Document-level writes require read
permission, so the role will be able to read all fields.
To prevent the role from inserting new documents, set the document-level
insert
field to false
.
![]() ![]() |
|
The Role Cannot Write to Specific Fields¶
To allow a role to write to any field except for those you specify, set
the corresponding field-level write
fields to false
in the
fields
document and set the additional_fields.write
field to
true
.
![]() |
|
Advanced Role Patterns¶
The use cases described in this section require you to use advanced functionality that is not supported by the default collection rules editor in the Realm UI. To use this template, convert to advanced mode or import a collection rule configuration with Realm CLI.
Insert-Only Roles¶
To allow a role to insert new documents but otherwise prevent them from
reading or modifying any data, set insert
to true
and set the
value of document-level write
to a JSON expression that evaluates to true
only if the
document didn't exist prior to the operation.
{ "name": "insertOnly", "apply_when": <JSON Expression>, "delete": false, "insert": true, "write": { "%%prevRoot": { "%exists": false } }, "additional_fields": {} }
You must specify a JSON expression for write
to prevent users
from reading data. To insert a document a role must also have write
permission for all fields in the document; however, setting write
directly to true
would also give the role read permission. The
JSON expression ensures that the role only has read permission for
the initial document insert.
Field-level Permissions for Embedded Documents¶
To allow a role to read or write some but not all fields of an embedded
document, add embedded documents that match the path of the embedded
field to the fields
document.
{ "name": "canReadEmbeddedField", "apply_when": {}, "delete": true, "insert": true, "fields": { "someEmbeddedDocument": { "fields": { "someEmbeddedField": { "read": true, "write": true } } } }, "additional_fields": {} }
MongoDB Realm applies any read
and write
permissions defined for a
given field to all embedded fields that the field contains regardless
of any permissions defined for those fields.