How to manage authorization and privileges in MongoDB

Introduction

Authorization is an essential part of user management and access control that defines the policies for what each user is allowed to do on the system. Deciding on what policies are appropriate and implementing them in your databases ensures that users can interact with the resources they require while protecting against inappropriate behavior.

In this guide, we'll go over how authorization works in MongoDB. We'll take a look at how MongoDB conceptualizes access management, what types of privileges can be granted to users, and how to attach policies to user accounts.

Prerequisites

To follow along with this guide, you'll need an account on a MongoDB server with the appropriate privileges.

To adjust the configuration of MongoDB and enable authorization on the database, you need root level access on the server.

Additionally, within MongoDB, you'll need an account that has at least the userAdmin role so that role-based authorization policies can be set. Roles that include the userAdmin role, listed from most narrowly focused to the broadest level of privileges are:

• userAdmin
• dbOwner
• userAdminAnyDatabase
• root

How does authorization work in MongoDB?

Authorization and privilege management in MongoDB is implemented using Role-Based Access Control (RBAC). In this system, different levels of access are associated with individual roles. To give a user permission to perform an action, you grant them membership to a role that has the appropriate privileges.

Roles in MongoDB can be nested. This means that roles can be granted to other roles. A role that contains another role inherits all of the child role's privileges. This makes it possible to create new roles that have the desired privileges by combining roles appropriately.

Privileges themselves are defined by a combination of an action and a resource. The action component describes the type of behavior that is permitted by the privilege, while the resource indicates the target or scope of the action.

What resources are available in MongoDB?

The target or scope of an action is known as a resource within MongoDB's access control model. Each action can only be applied to certain types of resources. When configuring privileges, you specify the exact resources for which the privilege should be scoped.

We can go over the available resources in order from the narrowest focus to the broadest.

Privileges can be most narrowly defined by scoping them to a specific collection within a specific database within the cluster. Within the same databases, different collections can specify different privileges. This allows you to implement granular policies for different types of data.

The next largest resource you can enact policies against is a database. Managing privileges on the database level allows you to provide general policy that will effect the database as a whole and all of the collections within.

You can also set policies that apply to collections of the same name across all databases. This allows you to use naming conventions to implement access control for specific collections throughout your system. A broader version of this is to apply policy to all databases and non-system collections on the system.

Finally, you can apply policy against the entire cluster. Actions targeting the cluster affect the general system instead of the data it is managing directly. Policies on the cluster level tend to be focused on administrative operations.

What actions are available in MongoDB?

There are a large number of actions available within MongoDB are related to general usage, database management, and system management. In general, actions correspond to one or more commands or methods within MongoDB.

To view the list of actions available in MongoDB as well as their function, expand the section below:

What roles are available in MongoDB by default?

MongoDB includes a number of useful roles that combine similar privileges together. These roles allow you to grant and revoke privileges to database resources in a concise way.

To view the list of actions available in MongoDB as well as their function, expand the section below:

How to enable authorization in MongoDB

Before MongoDB can use authorization to manage user privileges, you must enable the functionality on your server or cluster. To do so, you must log in to your server with root or other administrative privileges.

Note: Before enabling authorization, double check to make sure that you have access to at least one role with the privileges necessary to manage roles.

Modify the MongoDB server's configuration by opening the /etc/mongod.conf file in a text editor as an administrator. This command will open the file using the text editor defined in the EDITOR environment variable and fall back to vi, which is available on almost all systems:

sudo ${EDITOR:-vi} /etc/mongod.conf

The MongoDB configuration file uses the YAML serialization format to define the configuration. Uncomment or add a security: section key to the file. Beneath this key, indent a line using spaces (tabs are not permitted in YAML) and set authorization to enabled:

. . .
security:
  authorization: enabled
. . .

Save and close the file when you are finished.

To enable the new settings, restart your MongoDB server process. If your MongoDB server is running on a Linux host, the operation will look like this:

sudo systemctl restart mongod.service

Once the process restarts, MongoDB's authorization framework should be enabled within the database.

Viewing privileges and roles

Before you begin assigning roles to users, it is a good idea to get familiar with how to view information about privileges and roles within the system.

To view all of the roles available on the system, including all built-in roles and their associated privileges, use the db.getRoles() method with the showPrivileges and showBuiltinRoles options set to true:

db.getRoles({
    rolesInfo: 1,
    showPrivileges: true,
    showBuiltinRoles: true
})

The returned list will include a whole list of nested information about each of the roles and the privileges they have on various resources throughout the system.

To get information about a specific role, use the db.getRole() method instead. You must be on the database where the user is defined before executing the command:

use admin
db.getRole(
    "root",
    {
        showPrivileges: true,
        showBuiltinRoles: true
    }
)

To check which roles have been granted to each user, change to the database you are interested in and use the db.getUsers() method:

use admin
db.getUsers()

To check on the roles associated with a specific user, use db.getUser() instead:

use admin
db.getUser("root")

Assigning and revoking roles from users

To grant additional privileges to a user, you must grant them access to an existing role.

The db.grantRolesToUser() method allows you to specify additional roles that you want to add to a user. Its first argument is the user you wish to grant additional privileges to and the second argument is an array of additional roles you wish to add:

db.grantRolesToUser(
    "sally",
    [
        "read",
        "backup"
    ]
)

If the roles are defined in the current database, you can use the shorthand above that specifies the role by name without mentioning a database.

To grant roles associated with a different database or to be more explicit, specify roles as a document defining the role and db instead:

db.grantRolesToUser(
    "sally",
    [
        { role: "read", db: "sales"},
        { role: "readWrite", db: "callLogs"}
    ]
)

To revoke roles from a user, you can use the companion method called db.revokeRolesFromUser(). The argument syntax works exactly the same, but this time, the command removes the roles from the specified account.

To remove roles defined in the current database you can use the role names without mentioning the database:

db.revokeRolesFromUser(
    "sally",
    [
        "read",
        "backup"
    ]
)

To specify roles that are associated with other databases, use the long form by specifying the role and db in a document:

db.revokeRolesFromUser(
    "sally",
    [
        { role: "read", db: "sales"},
        { role: "readWrite", db: "callLogs"}
    ]
)

Creating and managing custom roles

There are times when the system's built-in roles do not adequately match up with the types of permissions you need to assign. In these cases, you can create your own custom roles.

db.createRole({
    role: "salesMonitor",
    privileges: [],
    roles: [
        {
            role: "read",
            db: "sales"
        }
    ],
})

db.createRole({
    role: "salesMonitor",
    privileges: [
        {
            resource: { db: "sales", collection: "" },
            actions: [ "find" ]
        }
    ],
    roles: []
})

db.getRole(
    "salesMonitor",
    {
        showPrivileges: true
    }
)

db.grantPrivilegesToRole(
    "salesMonitor",
    [
        { 
            resource: { db: "sales", collection: "" },
            actions: [ "listCollections" ]
        }
    ]
)

db.revokePrivilegesFromRole(
    "salesMonitor",
    [
        { 
            resource: { db: "sales", collection: "" },
            actions: [ "listCollections" ]
        }
    ]
)

db.grantRolesToRole(
    "salesMonitor",
    [
        "read"
    ]
)

db.revokeRolesFromRole(
    "salesMonitor",
    [
        "read"
    ]
)

db.updateRole(
    "salesMonitor",
    {
        privileges: [],
        roles: [
            {
                role: "read",
                db: "sales"
            }
        ]
    }
)

db.dropRole()

Conclusion

In this article, we covered a lot of ground about how MongoDB implements access control and privilege management. We took a look at the conceptual underpinnings of the system, saw the roles, actions, and resources available for administrators to manage, and then learned about how to use the roles system to configure authorization across the system.

These skills are necessary to provide users with access to the resources they need to complete their required tasks while limiting exposure to unrelated parts of the system. Learning how to define and leverage roles increases your ability to offer fine grained access control on the MongoDB systems you manage.

FAQ