Docs Menu

Docs HomeAtlas App Services

Sync Permissions Overview

On this page

  • Session Roles
  • Type-Specific and Default Roles
  • Document-Level Permissions
  • Field-Level Permissions
  • Expressions
  • Role Configuration Files
  • Permission Changes

Atlas Device Sync enforces data access rules for all requests to a synced cluster. Sync rules are dynamic JSON expressions that specify a given user's ability to view and modify synced data.

The way Device Sync rules work depends on whether you are using Flexible Sync (recommended) or the older Partition-Based Sync mode. This page documents Flexible Sync permissions. To configure Partition-Based Sync permissions, refer to Partition-Based Sync Permissions.

For examples of how you might configure permissions for common scenarios, refer to Flexible Sync Permissions Guide.

Important

Non-Sync Rules

This page describes data access rules for synced clusters. Non-synced cluster use a different rules model that sync rules override. If sync is enabled for a cluster, any non-sync rules defined for the cluster do not apply.

If your app does not use sync, check out MongoDB Collection Rules for more information on rules for non-synced clusters.

A session role determines which permissions apply for the duration of a Flexible Sync session.

Tip

See also:

For a guide to setting up Flexible Sync with common permissions models, see Flexible Sync Permissions Guide.

When a user begins a session by opening a synced realm, session roles are evaluated and applied to the user for each synced object type. A user may only have one role for each type, so session roles apply in a priority order. If no session role applies for an object type, the user cannot read or write any objects of that type.

A session role stays assigned for the duration of the session. If something relevant to a user's session roles changes in the middle of the user's session, the user is not assigned an updated role until they start a new session. For example, if the user's metadata or the role's "apply when" expression changes, the user continues to use their existing session role until the next time they start the app.

Tip

You can think of session roles as a way to group read and write expressions to organize your code. Most apps only need one (default) session role with per-document logic defined in the session role's read and write expressions.

Roles may be either type-specific roles that apply to a single object type that you identify by name or default roles that apply to all objects regardless of their type. You use expressions to determine when a role applies and to define dynamic field-level permissions for a specific role.

You can use type-specific roles alongside default roles. This example shows applying a custom rule to the Employees collection. This app also links to a Store collection that is not listed in the configuration, and has no custom type-specific rule, so it evaluates to the default role.

Sync attempts to find a matching session role by traversing the session roles in descending order. List the most specific custom session roles first, getting gradually more general, so the user "falls through" to the correct session role. If no type-specific role applies, and you have defined a default role that does apply, the user gets the default role permissions.

{
"rules": {
"Employees": [
{
"name": "employeeWriteSelf",
"applyWhen": {},
"read": {},
"write": {
"employee_id": "%%user.id"
}
}
]
},
"defaultRoles": [
{
"name": "admin",
"applyWhen": {
"%%user.custom_data.isGlobalAdmin": true
},
"read": {},
"write": {}
},
{
"name": "owner",
"applyWhen": {
"%%true": {
"%function": {
"name": "isOwner",
"arguments": [
"%%user.id"
]
}
}
},
"read": {},
"write": {
"owner_id": "%%user.custom_data.ownerId"
}
},
{
"name": "shoppers",
"applyWhen": {},
"read": {},
"write": false
}
]
}

You can define read and write permissions for a role that apply to an entire object. A user with document-level read permission for an object type can access all fields in an object of that type. Similarly, document-level write permissions allow a user to modify all fields.

If a user does not have read permission for an object type, no objects of that type are included in sync query results.

When you need more granularity than document-level permissions, you can configure field-level permissions that determine whether a user can read or write individual fields of an object type. You can define permissions for specific fields as well as a set of permissions that apply to fields without specific permissions.

Expressions in a role can only refer to the queryable fields of your data model.

You can use expansions to define dynamic "apply when" expressions and field-level permissions. Expansions let you refer to user metadata, including custom user data, and can call functions to handle complex logic. However, because session roles are determined at the start of a session -- that is, before any query for specific documents -- you can't refer to a document or its field values to determine whether a session role applies.

The following table describes support for expression expansions in flexible sync roles:

Expansion
Can Use in "Apply When"?
Can Use in Read & Write Rules?
Yes
Yes
Yes
Yes with an important caveat
No
No
Yes
Yes with an important caveat
No. These expansions refer to the document. App Services evaluates "apply when" expressions at session start, so there's no document to evaluate.
No. These expansions might access non-queryable fields of the document, which is not possible.
No
No
Yes
Yes
Yes
No. App Services expands the expansions at the start of the session, so the function would not operate on a per-document basis.
Yes
Yes
Yes
Yes. However, note that you cannot currently have an array field as a queryable field on a document.
Yes
Yes

Important

App Services causes a client reset if anything about the session role changed since the previous session.

At the start of a session, App Services expands all expansions in the "apply when", read, and write expressions and stores the result. This has the following implications:

  • If the value changes during a session, App Services continues to use the value as it was at the time of session start.

  • On the next session, if the value is different from what it was at the start of this session, App Services causes a client reset.

  • You cannot use the %function operator in read and write rules. Functions would not operate on a per-document basis.

  • You cannot store permissions information (such as "which document IDs may this user access?") in the user object.

You use JSON configuration files to define session roles. For more information, see Sync Configuration File Reference.

Example

The following role configuration describes a team administrator:

{
"name": "TeamAdmin",
"applyWhen": { "%%user.custom_data.isAdmin": true },
"read": {},
"write": { "teamId": "%%user.custom_data.teamId" },
"fields": {
"address": {
"fields": {
"zipCode": {
"write": false,
"read": true
}
},
"additional_fields": {
"write": true
}
},
"name": {}
},
"additional_fields": {
"write": false,
"read": false
}
}

The following table explains the effect of each part of the Role:

Role JSON
Effect
"read": {}
May access any document for reading.
"write": { "teamId": "%%user.custom_data.teamId" }
May access a document for writing if the document's teamId field equals the user's custom data teamId. This requires teamId to be declared as a queryable field in the Sync configuration.
"fields": {
"address": {
"fields": {
"zipCode": {
"write": false,
"read": true
}
},
"additional_fields": {
"write": true
}
},
"name": {}
},
May write to any field of the address embedded object except zipCode. May also write to the name field.
"additional_fields": {
"write": false,
"read": false
}
May not read or write any other fields despite having document-level access to the document.

If a user's permissions have changed since the last Sync session, Sync triggers a client reset and re-downloads all data with the new permissions applied.

A user's permissions might change in the following situations:

A client reset will not be triggered under the following cases:

  • Adding a new collection to a App Services Schema and defining permissions for the new namespace or using default roles. This will not trigger a client reset because permissions have not been applied previously.

  • Configuring custom permissions for the new collection in the same draft as the new schema. Conversely, deploying a draft with permission changes after you deploy the schema will lead to a client reset, since default permissions were applied in the initial deployment.

←  Sync SettingsFlexible Sync Permissions Guide →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.