Custom role creation in MongoDB - Deep Dive

Overview - Custom role creation

What is it?

Custom role creation in MongoDB means making your own set of permissions to control what users can do. Instead of using built-in roles, you define exactly which actions are allowed on which resources. This helps tailor security to your application's needs. It is done by specifying privileges and roles in a role document.

Why it matters

Without custom roles, you must rely on predefined roles that might give too many or too few permissions. This can lead to security risks or hinder productivity. Custom roles let you follow the principle of least privilege, giving users only what they need. This protects your data and helps meet compliance requirements.

Where it fits

Before learning custom role creation, you should understand MongoDB basics, user authentication, and built-in roles. After mastering custom roles, you can explore advanced security topics like auditing, encryption, and role-based access control (RBAC) best practices.

Mental Model

Core Idea

A custom role in MongoDB is a tailored permission set that defines exactly what actions a user can perform on specific database resources.

Think of it like...

Creating a custom role is like making a personalized keyring with keys only for the doors you want someone to open, instead of giving them a master key to the whole building.

┌─────────────────────────────┐
│        Custom Role          │
├─────────────┬───────────────┤
│ Privileges  │ Resources     │
│ - action 1  │ - database 1  │
│ - action 2  │ - collectionA │
│ ...         │ ...           │
└─────────────┴───────────────┘
        ↓
┌─────────────────────────────┐
│       Assigned to User       │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding MongoDB Roles

Concept: Learn what roles are and how they control access in MongoDB.

MongoDB uses roles to manage permissions. Each role has privileges that allow actions like reading or writing data. Built-in roles cover common needs, like 'read' or 'dbAdmin'. Roles are assigned to users to control what they can do.

Result

You understand that roles are sets of permissions assigned to users to control database access.

Knowing roles are collections of permissions helps you see why customizing them can improve security.

2

Foundation

Basics of Privileges and Actions

Concept: Privileges define what actions can be done on which resources.

A privilege has two parts: an action and a resource. Actions are operations like 'find', 'insert', or 'dropCollection'. Resources specify where the action applies, such as a database or collection. Together, they form the building blocks of roles.

Result

You can identify what actions and resources make up a privilege.

Understanding privileges as action-resource pairs clarifies how roles control specific operations.

3

Intermediate

Creating a Simple Custom Role

🤔Before reading on: do you think you can create a role that only allows reading from one collection? Commit to your answer.

Concept: Learn how to define a custom role with specific privileges using the createRole command.

To create a custom role, use the db.createRole() method. You specify the role name, the privileges (actions and resources), and optionally inherited roles. For example, a role that allows only 'find' on 'mydb.mycollection' looks like this: { role: 'readMyCollection', privileges: [ { resource: { db: 'mydb', collection: 'mycollection' }, actions: ['find'] } ], roles: [] } This role can then be assigned to users.

Result

A new role exists that restricts users to reading only one collection.

Knowing how to create a role with precise privileges lets you enforce fine-grained access control.

4

Intermediate

Assigning Custom Roles to Users

🤔Before reading on: do you think assigning a custom role to a user is different from assigning a built-in role? Commit to your answer.

Concept: Learn how to assign your custom role to a user to grant permissions.

After creating a custom role, assign it to a user with db.grantRolesToUser(). For example: use admin db.grantRolesToUser('alice', [{ role: 'readMyCollection', db: 'admin' }]) This gives user 'alice' the permissions defined in 'readMyCollection'.

Result

User 'alice' can now perform only the actions allowed by the custom role.

Understanding role assignment shows how permissions flow from roles to users.

5

Intermediate

Combining Custom and Built-in Roles

🤔Before reading on: do you think a user can have multiple roles with combined permissions? Commit to your answer.

Concept: Users can have multiple roles, and permissions combine to allow more actions.

You can assign multiple roles to a user, including built-in and custom roles. MongoDB merges all privileges from assigned roles. For example, a user can have 'read' on one database and a custom role for admin tasks on another. This flexibility helps tailor access.

Result

Users can have a mix of permissions from different roles.

Knowing that roles combine helps design layered security with minimal privilege overlap.

6

Advanced

Using Inherited Roles in Custom Roles

🤔Before reading on: do you think custom roles can include other roles inside them? Commit to your answer.

Concept: Custom roles can inherit privileges from other roles to avoid repetition.

When creating a custom role, you can specify existing roles in the 'roles' array. This means your custom role includes all privileges from those roles plus any new privileges you add. For example: { role: 'customAdmin', privileges: [ ... ], roles: [{ role: 'readWrite', db: 'admin' }] } This role has all 'readWrite' privileges plus custom ones.

Result

Custom roles can build on existing roles, making management easier.

Understanding inheritance reduces duplication and simplifies role maintenance.

7

Expert

Security Implications and Best Practices

🤔Before reading on: do you think giving broad privileges in custom roles is safe? Commit to your answer.

Concept: Learn how to design custom roles securely and avoid common pitfalls.

Custom roles should follow the principle of least privilege: grant only necessary actions on needed resources. Avoid using 'anyResource' or broad actions like 'dropDatabase' unless absolutely required. Regularly audit roles and user assignments. Use role inheritance carefully to prevent privilege escalation. Also, understand that some actions require cluster-level privileges, which need special handling.

Result

You can create secure custom roles that protect your data and comply with policies.

Knowing security best practices prevents accidental data exposure and strengthens your MongoDB deployment.

Under the Hood

MongoDB stores role definitions in the admin database's system.roles collection. When a user authenticates, MongoDB merges all privileges from assigned roles into an effective permission set. Each privilege is an action-resource pair checked at runtime before allowing operations. This check happens inside the database engine, ensuring only authorized actions proceed.

Why designed this way?

MongoDB's role-based access control was designed to be flexible and extensible. Built-in roles cover common cases, but custom roles allow fine-tuning for diverse applications. Storing roles as documents allows easy updates and inheritance. The action-resource model balances granularity and simplicity, avoiding overly complex permission systems.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│  Role Docs    │──────▶│ Privilege Set │──────▶│ Permission    │
│ (system.roles)│       │ (actions +    │       │ Check at      │
│               │       │  resources)   │       │ Runtime       │
└───────────────┘       └───────────────┘       └───────────────┘
         ▲                      ▲                      ▲
         │                      │                      │
         │                      │                      │
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ User Assigned │──────▶│ Role Merging  │──────▶│ Effective     │
│ Roles        │       │ (combine all) │       │ Permissions   │
└───────────────┘       └───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think a custom role automatically grants all privileges of the roles it inherits? Commit yes or no.

Common Belief: A custom role that inherits other roles replaces those roles' privileges with its own privileges.

Reality: A custom role that inherits other roles combines its own privileges with all privileges from the inherited roles.

Why it matters: Misunderstanding inheritance can lead to unexpected permissions, causing security holes or access issues.

Quick: Do you think assigning a custom role to a user immediately grants cluster-wide admin rights? Commit yes or no.

Common Belief: Any custom role can grant cluster-wide admin rights if assigned to a user.

Reality: Custom roles only grant cluster-wide rights if explicitly given cluster-level privileges; otherwise, they are limited to specified databases or collections.

Why it matters: Assuming all custom roles are powerful can cause over-trusting users or misconfiguring security.

Quick: Do you think you can create a custom role without specifying any privileges? Commit yes or no.

Common Belief: A custom role can be created without privileges and still grant access.

Reality: A custom role without privileges grants no permissions unless it inherits roles that have privileges.

Why it matters: Creating empty roles expecting access leads to confusion and failed operations.

Quick: Do you think MongoDB roles control network access to the database? Commit yes or no.

Common Belief: MongoDB roles control who can connect to the database server over the network.

Reality: MongoDB roles control what authenticated users can do inside the database, not network-level access, which is managed separately.

Why it matters: Confusing network access with role permissions can cause security gaps or misconfigured firewalls.

Expert Zone

1

Custom roles can include privileges that affect cluster-wide resources, but these require careful assignment to avoid privilege escalation.

2

Role inheritance merges privileges but does not override; conflicts are additive, which can unintentionally broaden access.

3

Some actions require multiple privileges or specific resource scopes, so partial privileges may not work as expected.

When NOT to use

Avoid custom roles when simple built-in roles suffice, as custom roles add complexity and maintenance overhead. For very dynamic or temporary permissions, consider using MongoDB's temporary roles or external access control systems.

Production Patterns

In production, teams create layered roles: base roles for common permissions, custom roles for project-specific needs, and audit roles for monitoring. Roles are version-controlled and reviewed regularly. Automation scripts manage role creation and assignment to ensure consistency.

Connections

Role-Based Access Control (RBAC)

Custom role creation in MongoDB is a specific implementation of RBAC principles.

Understanding RBAC helps grasp why MongoDB separates privileges into roles and assigns them to users for scalable security.

Operating System User Permissions

Both MongoDB custom roles and OS user permissions control access to resources using roles and privileges.

Knowing OS permissions clarifies how MongoDB roles similarly restrict actions, reinforcing the principle of least privilege.

Security Policy Design

Custom role creation builds on security policy design concepts like least privilege and separation of duties.

Learning security policy design outside databases helps create safer, more maintainable MongoDB roles.

Common Pitfalls

#1 Granting overly broad privileges in a custom role.

Wrong approach:

db.createRole({ role: 'allAccess', privileges: [{ resource: { anyResource: true }, actions: ['anyAction'] }], roles: [] })

Correct approach:

db.createRole({ role: 'readOnly', privileges: [{ resource: { db: 'mydb', collection: '' }, actions: ['find'] }], roles: [] })

Root cause:

Misunderstanding the scope of 'anyResource' and 'anyAction' leads to excessive permissions.

#2 Creating a custom role without specifying any privileges or inherited roles.

Wrong approach:

db.createRole({ role: 'emptyRole', privileges: [], roles: [] })

Correct approach:

db.createRole({ role: 'readRole', privileges: [{ resource: { db: 'mydb', collection: '' }, actions: ['find'] }], roles: [] })

Root cause:

Assuming a role exists without privileges grants access, but it actually grants none.

#3 Assigning a custom role to a user without specifying the correct database for the role.

Wrong approach:

db.grantRolesToUser('bob', [{ role: 'readMyCollection', db: 'wrongDB' }])

Correct approach:

db.grantRolesToUser('bob', [{ role: 'readMyCollection', db: 'admin' }])

Root cause:

Confusing the database where the role is defined with the database where the user exists causes assignment failure.

Key Takeaways

Custom roles in MongoDB let you define precise permissions by specifying actions on resources.

Roles are collections of privileges that can inherit from other roles, combining permissions.

Assigning roles to users controls what they can do inside the database, enforcing security.

Following least privilege and auditing roles regularly prevents security risks.

Understanding role inheritance and privilege scope is key to avoiding unintended access.