MongoDB agent

The MongoDB agent is a service beside the deployment. It keeps MongoDB's own access control in step with the signed policies of a mongodb data service: one role per user that holds exactly what the policies give the user. MongoDB then checks every command itself, and the agent stands in no client's way. The distribution ships it as the runnable JAR agents/mongodb/grantforge-agent-mongodb-<version>.jar; it needs Java 17 or later.

The repository's Testcontainers integration tests run the agent, and the JAR as shipped, against replica sets of MongoDB 6.0, 7.0, 8.0 and 9.0 and a 9.0 sharded cluster, and read the audit log of Percona Server for MongoDB 7.0 and 8.0. This does not certify every other release; the agent refuses deployments older than 6.0. For the service plugin see MongoDB.

How it works

• One role per user holds what GrantForge gives. For each user the policies give something, the agent keeps a role named after it in admin, grantforge_alice for alice, and grants it to every MongoDB user of that name, such as alice@admin and alice@sales. rolesInfo shows what GrantForge gives alice. The agent changes no other role.
• A change happens in one step. updateRole replaces a role's privileges at once, so a user never holds both the old and the new, or neither.
• Whole databases where nothing below is decided otherwise. An access type a policy allows on all of a database, with no policy that could take it away below it, is granted on the database, so collections created later have it at once. Otherwise it is granted collection by collection, and new collections are covered at the next sync.
• Never more than the policies allow. MongoDB's privilege to drop a database is the privilege to drop every collection in it. The agent grants it only where the policies give that too; otherwise it withholds it and logs, once, which user cannot do what and why.
• The policies of the present moment. Each sync plans from the policies as they apply at that moment, so validity periods start and end on time, and from the users, databases and collections MongoDB has, so new ones are covered at the next sync.
• MongoDB roles are groups. A policy for a group applies to users that hold a MongoDB role of that name, together with the groups GrantForge puts them in.
• Changes by hand are undone. At every sync the agent compares its roles with the plans and sets right privileges changed by hand, roles they were made to inherit, grants of a role to someone else, and roles nobody needs. When nothing changed, it sends nothing.
• Roles outside GrantForge are read for what they give. MongoDB adds up what all of a user's roles give, so the agent cannot take away what a user holds through another role. MongoDB says what every role gives, built-in and inherited ones too, so the agent warns, once each, of a role such as readWrite@hr that gives what a policy denies, naming the user, the access and the policy. It also warns of users who can administer users, and so give themselves anything, of users with root or every action on every resource, and of a server that checks no authorization at all.
• Accesses come from the audit log or the profiler. See Reporting accesses below. Each event says whether GrantForge decided, that is whether the policies decide as MongoDB did, or a role outside it allowed the command. An aggregation is reported for each collection its $lookup, $graphLookup and $unionWith stages read and its $out and $merge stages write. Events name the command and its namespace, never its arguments, which can hold documents and passwords.

Deployment

1. Add a mongodb data service and its policies. Open Data authorization → Agents, choose the service and issue an agent token. It is shown once, so save it in a file only the agent's account can read.

2. Create the agent's MongoDB user. It creates and changes roles and reads users and roles, with userAdminAnyDatabase; lists collections, with a role that holds only that; and reads the server's options and the profiler, with clusterMonitor. userAdminAnyDatabase can give itself anything, so guard this user as you guard an administrator. The name of the listing role must not start with the agent's role prefix.

   const admin = db.getSiblingDB("admin");
   admin.createRole({ role: "agent_inventory", roles: [],
     privileges: [{ resource: { db: "", collection: "" }, actions: ["listCollections"] }] });
   admin.createUser({ user: "grantforge", pwd: passwordPrompt(),
     roles: ["userAdminAnyDatabase", "clusterMonitor", "agent_inventory"] });

3. To report accesses, set up one of the sources under Reporting accesses below.

4. Write a settings file, changing the example addresses, paths and names:

   grantforge.server.url=https://grantforge.example.com
   grantforge.token.file=/etc/grantforge/mongodb-agent.token
   grantforge.instance=mongodb-agent-1
   grantforge.cache.dir=/var/lib/grantforge/mongodb-agent
   grantforge.mongodb.uri=mongodb://db1.internal:27017,db2.internal:27017/?replicaSet=rs0
   grantforge.mongodb.user=grantforge
   grantforge.mongodb.password.file=/etc/grantforge/mongodb-agent.password

   These paths are on the agent's machine, and the cache directory must be writable. The password file is read as UTF-8, with surrounding white space removed.

5. Start the agent, for example as a systemd service:

   java -jar agents/mongodb/grantforge-agent-mongodb-<version>.jar /etc/grantforge/mongodb-agent.properties

   Replace <version> with the distribution's version. Settings given as java -Dgrantforge.…=… -jar … take precedence over the file. On SIGTERM the agent stops cleanly and sends or spools pending events; MongoDB keeps what it was given.

6. Move existing grants to policies: roles granted outside GrantForge keep applying beside the agent's. Create the matching policies, then revoke those roles. The agent's warnings point out those that give what a policy denies.

Reporting accesses

The audit log is read from files, so run the agent on the node or give it a directory that collects them. The tests read Percona Server's audit log, which has the format of MongoDB Enterprise's. A mongos has no profiler, so a sharded cluster reports accesses only from the audit log.

MongoDB refuses a command as a whole without saying which of its collections was the reason, so a refusal is reported for those the policies deny, or for the first when they deny none.

Users, groups and roles

Policies name MongoDB users by their user name. A name defined in several databases is one user, and the agent's role is granted to all of them. Groups are the MongoDB roles a user holds and the groups GrantForge puts it in. Roles are the roles GrantForge gives the user.

Decisions and limits

• Without a snapshot the agent changes nothing. A token bound to a service not in use, or to a service whose type is not mongodb, grants nothing: the agent drops its roles, and MongoDB's own remain.
• While the agent is not running MongoDB keeps what it last received, and policy changes wait for it. A change reaches MongoDB within the refresh and sync intervals; a mongos applies it once its user cache has expired, by default within 30 seconds (userCacheInvalidationIntervalSecs).
• MongoDB's privileges name databases and collections exactly, so a wildcard in a policy is granted for what exists. A database exists once it has a collection: until then, create on a database that a policy names has nothing to be granted on.
• Users defined nowhere in MongoDB, such as those LDAP authorization maps to roles by itself, are not seen, and the agent keeps no role for them.
• A privilege on a database as a whole covers its collections but not its system. collections, and MongoDB's own databases are left to MongoDB.
• Renaming collections and MongoDB's other administrative actions are no access types: they stay with roles outside GrantForge.
• MongoDB filters no rows and masks no fields by role; a view gives a restricted reading.

Related guides

• MongoDB
• Data services, policies and agents