Docs Home → Atlas App Services
Role-based Permissions
On this page
Note
The content in this section only applies when Atlas Device Sync is not enabled. For information about configuring permissions when using Sync, see Sync Permissions Overview.
Overview
You secure your App's data by defining roles that are automatically assigned to incoming user requests. Each role has fine-grained data access permissions and dynamic conditions that determine when the role applies.
What are Permissions?
A permission is a status that Atlas App Services assigns to individual users to control what they can and cannot do in your app. App Services 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. App Services automatically assigns roles to the user at request time. Each role includes an Apply When expression that determines when App Services should assign the role to a user as well as a set of document-level and field-level permissions that apply to the role.
App Services 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, App Services 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
managesarrays, 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 App Services Assigns Roles
App Services dynamically assigns roles for every request. The user is assigned a separate role, or no role, for each document that matches the incoming query.
First, your App evaluates and applies filters and then runs the query.
Example
This request would cause App Services 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" } } );
For each document returned by the query, your App evaluates possible
roles in role order and assigns the first applicable
role, if any. A role applies to a given document if its Apply When
expression evaluates to true when run against
the document.
The set of roles that a user may play for a given request depends on the collection they're accessing. If the collection has a set of collection-level roles defined, then a user may play any of those roles. If there are no collection-level rules, the request falls back to the data source's default roles.
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:
Define Roles & Permissions
You can configure your app's data access rules from the App Services UI or by deploying configuration files with Realm CLI:
Apply When Expressions
A role's Apply When expression is a rule expression that determines when a given user has the role for a specific document. The expression is evaluated for each document that an incoming query matches.
You can use expression variables to make roles dynamic. For example, you
can use %%user to refer to the specific user that
issued the request or %%root to reference the current
document. This lets you customize your data access permissions on a
per-user, per-document basis.
Document-Level Permissions
A role's document-level permissions determine which actions that affect the entire document a user with the role can perform. A role can have any of the following document-level permissions:
Insert: The role can insert new documents.
Delete: The role can delete existing documents.
Search: The role can find the document in Atlas Search results.
Field-Level Permissions
A role's field-level permissions determine whether or not a user with the role can read or write individual fields within the document.
You can define field-level permissions for specific fields as well as default read/write permissions for any additional fields that you don't explicity define.
Role Order
The roles for a given collection each have a position that determines the order in which they are evaluated and applied. Each role's apply when expression is evaluated in role order until a role applies or no roles remain.
A user may only have one role per document in a given query. Role order determines which role applies in the event that multiple roles' apply when expressions are true.