Configure Custom Database Roles

On this page

Add Custom Roles

Modify Custom Roles
Delete Custom Roles
Assign Custom Roles
Considerations

You can create custom roles in Atlas when the built-in roles don't describe your desired set of privileges. Atlas applies each database user's custom roles together with:

Any built-in roles you assign when you add a database user or modify a database user.
Any specific privileges you assign when you add a database user or modify a database user.

You can assign multiple custom roles to each database user.

Note

Free Cluster and Shared Cluster Limitation

Changes to custom roles might take up to 30 seconds to deploy in M0 free clusters and M2/M5 shared clusters.

Add Custom Roles

The following procedure shows how to create a custom role through the Atlas UI. To create custom roles through the Atlas Administration API, see Create a Custom Role.

Open the Add Custom Role dialog.

In the Security section of the left navigation, click Database Access.
Click the Custom Roles tab.
Click Add New Custom Role.

Enter role information.

Field	Description
Custom Role Name	Name of your custom role. Important The specified role name can only contain letters, digits, underscores, and dashes. Additionally, you cannot specify a role name which meets any of the following criteria: Is a name already used by an existing custom role in the project Is a name of any of the built-in roles Is `atlasAdmin` Starts with `xgen-`
Action or Role	Privileges granted by the role. Click the dropdown to view the list of available privilege actions and roles. Atlas groups the actions and roles into the following categories: `Collection Actions`, `Database Actions and Roles`, `Global Actions and Roles`, `Custom Roles` (if any) Select the action(s)/role(s) from a single category. Once you select an action/role, Atlas disables the other categories with the following exception. If you select an action/role from the Global Actions and Roles, you can still select actions/roles from Custom Roles. To grant actions and roles from a different category, click Add an action or role to add a new row. Atlas disables actions not available to any cluster version in your project. Custom roles are defined at the project level, and must be compatible with each MongoDB version used by your project's clusters.
Database	Database on which the selected actions and roles are granted, if applicable. This field is required for all roles and actions under the Collection Actions and Database Actions and Roles categories.
Collection	Collection within the specified database on which the actions and roles are granted, if applicable. This field is required for all roles and actions under Collection Actions.

To grant the same set of privileges on multiple databases and collections, click Add a database or collection.

Click Add Custom Role.

Modify Custom Roles

The following procedure shows how to modify custom roles through the Atlas UI. To modify custom roles through the Atlas Administration API, see Update a Custom Role.

In the Security section of the left navigation, click Database Access. The Custom Roles tab displays.
Click Edit next to the role you want to modify. You can modify the following components of the role:
- The action(s)/role(s) the custom role inherits.
- The database(s)/collection(s) on which those privileges apply.
Click Update Custom Role to save the changes.

Delete Custom Roles

The following procedure shows how to delete custom roles through the Atlas UI. To delete custom roles through the Atlas Administration API, see Delete a Custom Role.

In the Security section of the left navigation, click Database Access. The Custom Roles tab displays.
Click Delete next to the role you want to delete.
Click Delete in the dialog to confirm deletion.

You cannot delete a custom role in the following scenarios:

When deleting the role would leave one or more child roles with no parent roles or actions.
When deleting the role would leave one or more database users with no roles.

Assign Custom Roles

You can assign custom roles in the Atlas UI when you add a database user or modify a database user. To assign custom roles through the Atlas Administration API, see Create a Database User or Update a Database User.

Considerations

You can assign up to 20 custom roles to a single database user and can create up to 100 custom roles per project. If you require more custom roles per database user or per project, contact Atlas support.
Atlas rolls back any role modifications not made through the UI or API. You must use the Atlas UI or API to add, modify, or delete custom roles on Atlas database deployments.
Atlas audits the creation, deletion, and updates of custom MongoDB roles in the project's Activity Feed.
If you assign multiple roles to a user and those roles grant conflicting permissions for an object, Atlas honors the highest permissions within any role.
Example
You create two custom roles and assign both to User A:
- The first custom role grants only read privileges on your database. It also grants bypassDocumentValidation on your database.
- The second role grants dbAdmin privileges on your database. It doesn't grant bypassDocumentValidation, which is an implicit denial of bypass permissions.
User A would have all of the dbAdmin privileges for your database, since dbAdmin is the higher database access permission. User A would also have bypassDocumentValidation, since bypassDocumentValidation is the higher bypass permission.

← Configure Database Users Set Up Passwordless Authentication with AWS IAM →