- Security >
- Control Access to MongoDB Instances with Authentication
Control Access to MongoDB Instances with Authentication¶
On this page
MongoDB provides a basic authentication system, that you can enable
with the auth
and keyFile
configuration
settings. [1] See the authentication section of the Security Practices and Management document.
This document contains an overview of all operations related to authentication and managing a MongoDB deployment with authentication.
See
The Security Considerations section of the Run-time Database Configuration document for more information on configuring authentication.
[1] | Use the --auth
--keyFile options on the command
line. |
Add Users¶
When setting up authentication for the first time you must either:
- add at least one user to the
admin
database before starting themongod
instance withauth
. - add the first user to the
admin
database when connected to themongod
instance from alocalhost
connection. [2]
Begin by setting up the first administrative user for the
mongod
instance.
[2] | Because of SERVER-6591, you cannot
add the first user to a sharded cluster using the localhost
connection in 2.2. If you are running a 2.2 sharded cluster, and
want to enable authentication, you must deploy the cluster and add
the first user to the admin database before restarting the
cluster to run with keyFile . |
Add an Administrative User¶
About administrative users
Administrative users are those users that have “normal” or read and
write access to the admin
database.
If this is the first administrative user,
[3] connect to the mongod
on the
localhost
interface using the mongo
shell. Then, issue
the following command sequence to switch to the admin
database
context and add the administrative user:
Replace <username>
and <password>
with the credentials for
this administrative user.
[3] | You can also use this procedure if
authentication is not enabled so that your databases has an
administrative user when you enable auth . |
Add a Normal User to a Database¶
To add a user with read and write access to a specific database, in
this example the records
database, connect to the
mongod
instance using the mongo
shell, and issue
the following sequence of operations:
Replace <username>
and <password>
with the credentials for
this user.
Add a Read Only User to a Database¶
To add a user with read only access to a specific database, in
this example the records
database, connect to the
mongod
instance using the mongo
shell, and issue
the following sequence of operations:
Replace <username>
and <password>
with the credentials for
this user.
Administrative Access in MongoDB¶
Although administrative accounts have access to all databases, these
users must authenticate against the admin
database before changing
contexts to a second database, as in the following example:
Example
Given the superAdmin
user with the password Password123
,
and access to the admin
database.
The following operation in the mongo
shell will succeed:
However, the following operation will fail:
Note
If you have authenticated to the admin
database as normal, read
and write, user; logging into a different database as a read only
user will not invalidate the authentication to the admin
database. In this situation, this client will be able to read and
write data to this second database.
Authentication on Localhost¶
The behavior of mongod
running with auth
, when
connecting from a client over the localhost interface (i.e. a client
running on the same system as the mongod
,) varies slightly
between before and after version 2.2.
In general if there are no users for the admin
database, you may
connect via the localhost interface. For sharded clusters running
version 2.2, if mongod
is running with auth
then
all users connecting over the localhost interface must authenticate,
even if there aren’t any users in the admin
database.
Password Hashing Insecurity¶
In version 2.2 and earlier:
- the normal users of a database all have access to the
system.users
collection, which contains the user names and a hash of all user’s passwords. [4] - if a user has the same password in multiple databases, the hash will be the same on all database. A malicious user could exploit this to gain access on a second database use a different users’ credentials.
As a result, always use unique username and password combinations on for each database.
[4] | Read only users do not have access
to the system.users database. |
Thanks to Will Urbanski, from Dell SecureWorks, for identifying this issue.
Configuration Considerations for Authentication¶
The following sections, outline practices for enabling and managing authentication with specific MongoDB deployments:
Generate a Key File¶
The key file must be less than one kilobyte in size and may only contain characters in the base64 set. The key file must not have group or “world” permissions on UNIX systems. Key file permissions are not checked on Windows systems.
Windows Systems¶
Use the following openssl
command at the system shell to generate
pseudo-random content for a key file for deployments with Windows
components:
Linux and Unix Systems¶
Use the following openssl
command at the system shell to generate
pseudo-random content for a key file for systems that do not have
Windows components (i.e. OS X, Unix, or Linux systems):
Key File Properties¶
Be aware that MongoDB strips whitespace characters (e.g. x0d
,
x09
, and x20
,) for cross-platform convenience. As a result,
the following operations produce identical keys: