skip to content

What does MongoDB's security.authorization setting turn on, and when does the localhost exception close?

level: middleimportance: should knowfreq 40%

answer

  1. off by default on a mongod
  2. enforcement, and a bootstrap problem
  3. what else implies it
  4. loopback, with nobody in admin
  5. the first user ends it

basics

~20 s

security.authorization: enabled makes a mongod enforce roles, so clients can do only what they have been granted; the default is disabled. The localhost exception lets a loopback client create the first user, and closes once a user or role exists in admin.

solid answer

~50 s

`security.authorization` defaults to `disabled`, where any client can do anything. Set to `enabled`, or with `--auth`, a client can do only what its roles grant, and a client that has not logged in has no data access. It is a `mongod` setting, and `security.keyFile` implies it. A replica set member refuses `enabled` unless it also has a `keyFile` or `clusterAuthMode: x509`. The localhost exception solves the bootstrap problem: while no user or role exists in `admin`, a loopback connection may create the first user and run replica set setup, but it cannot read data. Creating that user ends the exception, and the server does not check that the user is an administrator, so give it `userAdminAnyDatabase`. `enableLocalhostAuthBypass`, default `true` and startup-only, can turn the exception off. In 9.0 a miscased value such as `Enabled` is rejected at startup; older builds silently left authorization disabled.

code

yaml · 2 lines
yaml
setParameter:
  enableLocalhostAuthBypass: false

go deeper

for a junior

Recall that authorization is off by default and that security.authorization or --auth turns it on. Know the localhost exception exists so that someone can create the first user.

for a middle

Explain what the exception allows, when it closes, and that keyFile implies authorization. Mention that a replica set member refuses authorization without a keyFile or x509 member authentication.

for a senior

Warn about the failures: a first user without admin rights locks everyone out, a miscased value on an older build leaves the server open, and an arbiter keeps the exception open.

for a principal

Decide whether production keeps the exception at all. Turning off enableLocalhostAuthBypass removes a loopback path on every host, but provisioning must then create the first user before enforcement, so make that part of the build.

## What the setting changes **Authorization** means the server checks every operation against what the client has been granted. `security.authorization` is the switch, and its default is `disabled`, which surprises people who assume a database starts locked. | Value | What a client can do | |---|---| | `disabled` (default) | access any database and perform any action | | `enabled` | access only the resources and actions its roles grant | With `enabled`, users have to authenticate, and a client that has not logged in has no data access. The setting exists only on `mongod`. A `mongos` gets its security from the member authentication settings, so turning on access control for a sharded cluster is not a matter of setting this on the router. Since 9.0.0, and in 8.3.9, 8.2.13, 8.0.30 and 7.0.41, the value is case-sensitive: `mongod` rejects anything other than exactly `enabled` or `disabled` at startup. On earlier builds, `Enabled` was silently ignored and left authorization **off**, with nothing to tell you except an open server. ## What else turns it on - `--auth` on the command line is the same switch. - `security.keyFile` implies authorization, and `security.clusterAuthMode` sets it too. - `security.transitionToAuth` forces client authorization off while a deployment moves to internal authentication, so members accept both authenticated and unauthenticated connections. During that window, clients can read, write and administer any database, so give every service its credentials before the last restart, which starts rejecting unauthenticated connections. On a replica set, the options are also tied together. A member started with `security.authorization: enabled` and neither a `keyFile` nor `clusterAuthMode: x509` refuses to start, with the message that `security.keyFile` is required. Members have to prove themselves to each other once clients must. ```yaml security: authorization: enabled keyFile: /etc/mongodb/keyfile replication: replSetName: shop-rs ``` ## The bootstrap problem Enabling authorization on an empty deployment raises an obvious question: nobody can log in, so who creates the first user? The **localhost exception** is the answer. It opens only when all of these hold: 1. Access control is enabled. 2. The connection arrives over the loopback interface. Anything that can open such a connection on that host qualifies, so this is also a reason to limit who can log in to the machine. 3. No user or role exists in `admin`, as the 9.0.4 source checks it. 4. `enableLocalhostAuthBypass` is `true`, which is its default. It is set at startup only. ## What the exception allows It is a narrow door, not a bypass of all checks. In the 9.0.4 source the session receives `createUser` and `grantRole` on `admin`, `createUser` on `$external`, and on the cluster `replSetConfigure`, `replSetGetStatus`, `addShard` and `issueDirectShardOperations`. So you can initiate a replica set and create the first user, but you cannot run `find` on a collection or drop a database. Creating a first role is allowed only for a user who already holds it through external authorization, which is why the manual reserves that path for LDAP setups. On a replica set, wait for a primary before creating the user. On a sharded cluster, the exception applies to each shard as well as the cluster, so each shard needs its own user administrator or the parameter turned off. ## When it closes - **Creating the first user in `admin` closes it.** The manual words the rule as no users or roles at all, while the 9.0.4 source asks only about those defined in `admin`. Users created solely in `shop` before access control was enabled would not close it. - **It stays closed for the life of the process**, even if every user is later dropped. A source comment says so directly. A restart evaluates it afresh. - **An arbiter keeps it open.** An arbiter stores no data, so it has no users, and the manual says the exception is the only way to log on to one with authorization active. ## The trap in that first user The server does not check that the first user can administer anything. Create it with `read` and the exception still closes, leaving no account that can create others. Recovery means restarting with access control off for long enough to add a real user administrator, which on production is a maintenance window. So the first user gets `userAdminAnyDatabase`, or `userAdmin` on `admin`, and a stored password: ```javascript use admin db.createUser({ user: "userAdmin1", pwd: passwordPrompt(), roles: [{ role: "userAdminAnyDatabase", db: "admin" }] }) ```

  • What happens if the first user created through the localhost exception holds only read on admin?
    The exception closes anyway, because the check is whether a user exists, not whether that user can administer. That user cannot create others, and nobody else can log in. Recovery is to restart with access control off, create a user administrator, and restart with it on again. That is why the first user should hold `userAdminAnyDatabase`.
  • If every user is dropped from a running mongod, does the localhost exception reopen?
    Not while that process runs. Once the server sees a user or role in `admin`, it caches that answer for the process lifetime, even if all users are later dropped. After a restart it checks again, so a restart with no users in `admin` would open the exception once more.
  • Why does an arbiter keep the localhost exception open on a secured replica set?
    An arbiter holds no data, so it has no users or roles to find. The manual says the only way to log on to an arbiter with authorization active is the exception. In the source, that session also gets `serverStatus`, `getParameter`, `getCmdLineOpts` and `shutdown`, so loopback access to an arbiter host matters.

  • Setting security.authorization on mongos is how a sharded cluster turns on access control.
  • The localhost exception lets a local client read and write any collection.
  • A replica set member can run with authorization enabled and no member authentication.
  • Dropping every user reopens the localhost exception straight away.
  • The server checks that the first user created is an administrator.
  • MongoDB enforces access control by default, so a fresh mongod needs no configuration.

Assumes MongoDB 9.0; security.authorization values are case-sensitive from 9.0.0 (also 8.3.9, 8.2.13, 8.0.30, 7.0.41), and earlier builds silently leave a miscased value disabled.