Define Roles And Permissions¶

On this page

Overview
Procedure

Overview¶

The MongoDB service uses a strict rules system that prevents all operations unless they are specifically allowed. Stitch determines if each operation is allowed dynamically when it receives the request from the client based on roles that you define.

Roles are sets of document-level and field-level CRUD permissions and are chosen individually for each document associated with a query. This guide walks through configuring one or more roles for a collection.

Important

You must define at least one role before you can successfully query a collection.

Note

This guide requires a linked MongoDB Atlas cluster.

Procedure¶

Stitch UI
Import/Export

1

Navigate to the MongoDB Rules Screen¶

You can create and manage roles and permissions from the MongoDB rules screen in the Stitch UI. To get to the rules screen, click Rules beneath MongoDB Clusters in the left-hand navigation.

2

Add a MongoDB Collection Namespace¶

Data access roles and permissions are scoped to individual collections in a linked MongoDB cluster. To define roles and permissions for a collection, you need to create the collection namespace in the Stitch UI.

Find the linked cluster that you want to define access permissions for in the rules sidebar and click its context menu (…). Select Add Database/Collection.

Add a Database/Collection button on the collection rules screen.

3

Configure the Collection Namespace¶

Enter the Database Name and Collection Name of the MongoDB collection that you want to use.

4

Select a Collection Rule Template¶

You can choose to apply a rule template to the collection to simplify the process of configuring role permissions. Each template is a pre-configured set of roles and permissions that represents a common use case and data access pattern. You can also select No template, which creates a default role that can insert and delete documents but cannot read or update any fields.

Once you have selected and configured a template, click Add Collection.

A list of available collection rule templates.

Note

Templates do not rely on hard-coded field names, so when you select a template you will need to map certain fields in your documents to the template’s fields. For example, the Users can only read and write their own data template requires that each document in the collection contains the ID of the user that owns it. If you select that template, you will need to specify the name of the field that contains the user id.

Additional fields for a collection rule template.

5

Create a New Role¶

Depending on the rule template you selected, there will already be one or more pre-configured roles in the collection. You can use these roles as they are, tweak them to fit your use case, or add additional roles to cover more cases.

To add an additional role, click New Role. Enter a Name for the new role on the role configuration screen.

6

Define the Role’s “Apply When” Condition¶

A role’s Apply When condition determines whether or not the role applies to a particular document for the user that issued a query.

Enter a JSON Expression in the role’s Apply When box. The expression should evaluate to true when the role applies to a given document.

7

Define Document-Level Permissions¶

Document-level permissions determine a role’s ability to insert and delete entire documents in the collection. Check the Document-Level Permissions boxes next to the operations the role has permission to execute.

Once you have defined the role’s document-level permissions, click Done Editing.

A MongoDB Role's Document-Level Permissions

8

Define Field-Level Permissions¶

Field-level permissions determine if a role can read and write to specific fields within a given document. You can define the field-level permissions for a role in that role’s column on the Rules page.

To define permissions for all fields:

Click Add Field, enter the field name, then click the green check next to the input box to confirm the name. In the new field’s row, check the Read and Write boxes to indicate whether the role can read or write to the field.

A role with permission to read and write to specific fields

To define permissions for a specific field:

Click Add Field, enter the field name, then click the green check next to the input box to confirm the name. In the new field’s row, check the Read and Write boxes to indicate whether the role can read or write to the field.

To define default permissions for unlisted fields:

Check the Read and Write boxes for All Additional Fields to indicate the role’s read and write privileges for any fields that aren’t specifically configured.

A role with permission to read any unspecified fields

9

Add Additional Roles¶

Repeat steps 5 through 8 of this procedure for any additional roles that you want to configure.

Note

Stitch evaluates roles in order from left-to-right. A user can only have one role per document, so once Stitch finds a role that applies to the current document it skips evaluating any remaining roles and immediately begins evaluating a role for the next document in the query.

10

Save the Updated Collection Rules¶

Once you have finished defining roles for the collection, click Save. Stitch will immediately begin using the roles you defined for all incoming queries on the collection.

1

Export Your Stitch Application¶

To define roles and permissions with stitch-cli you need to export an application directory for your application.

You can export your application from the Export tab of the Settings page in the Stitch UI, or by running the following command from an authenticated instance of stitch-cli:

copy

stitch-cli export --app-id=<App ID>

2

Add a Rule Configuration File¶

The rules for a MongoDB collection are configured in the rules subdirectory of the linked cluster’s service directory. The rules configuration file is a JSON file with the same name as the collection namespace.

For example, the rules for the collection app.users in the mongodb-atlas cluster are defined in the file /services/mongodb-atlas/rules/app.users.json.

If you have not configured rules for the collection, add a configuration file for it to the rules directory:

copy

touch services/<cluster name>/rules/<db>.<collection>.json

The configuration file should have the following general form:

copy

{
  "database": "",
  "collection": "",
  "roles": [],
  "filters": [],
  "schema": {}
}

Set the database and collection values to the database and collection the role applies to.

Note

This guide focuses on creating roles for the collection. Check out the other configuration guides to learn how to create filters and enforce document schemas.

3

Add One or More Roles¶

Add a document to the roles array for each role that you want to configure. Role documents have the following form:

copy

{
  "name": "<Role Name>",
  "apply_when": <JSON Expression>,
  "insert": <boolean>,
  "delete": <boolean>,
  "read": <boolean>,
  "write": <boolean>,
  "fields": {
    "<Field Name>": {
      "read": <boolean>,
      "write": <boolean>
    },
    ...
  },
  "additional_fields": {
    "read": <boolean>,
    "write": <boolean>
  }
}

Field	Description
`name`	Required. The name of the role. Limited to 100 characters or fewer.
`apply_when`	Required. A JSON expression that determines when this role applies to a given document.
`insert`	Optional. Default: `false`. A boolean that, if `true`, indicates that the role has permission to insert a new document. This document-level permission does not override any field-level permissions configured in `fields`, i.e. the role must have permission to write to all inserted fields in addition to insert permission.
`delete`	Optional. Default: `false`. A boolean that, if `true`, indicates that the role has permission to delete a new document.
`read`	Optional. Default: `false`. A boolean that, if `true`, indicates that the role has permission to read all fields in a document. This document-level read permission overrides any field-level permissions configured in `fields`.
`write`	Optional. Default: `false`. A boolean that, if `true`, indicates that the role has permission to write to all fields in a document. Further, write permissions require matching read permissions, so if this is `true`, then `read` is also `true`. These document-level read and write permissions override any field-level permissions configured in `fields`.
`fields`	Required. A document where each field matches the name of a field in a collection document. The value of each field is a document that specifies read and write permissions for the field. Example copy "fields": { "id": { "read": true, "write": false }, }
`additional_fields`	Optional. Default: `{ "read": false, "write": false }`. A document that specifies the role’s default read and write permissions for any fields that are not explicitly defined. copy "additional_fields": { "read": true, "write": false }

4

Import Your Application Directory¶

Once you’ve added your role configurations to the collection rule configuration file, all that’s left is to import the rule.

Ensure that the rule configuration file is saved then navigate to the root of the exported application directory. Log in to MongoDB Atlas with stitch-cli:

copy

stitch-cli login --username="<MongoDB Cloud Username>" --api-key="<MongoDB Cloud API Key>"

Once you’re logged in, import the directory:

copy

stitch-cli import

Once the import completes, Stitch will immediately begin using the roles you defined for all incoming queries on the collection.

← Link a MongoDB Atlas Cluster Filter Incoming Queries →