- Security >
- Security Tutorials >
- Enable Access Control >
- Enable Internal Authentication
Enable Internal Authentication¶
On this page
Overview¶
When authentication is enabled on a replica set or a sharded cluster, members of the replica set or the sharded clusters must provide credentials to authenticate.
To enable authentication on a replica set or a sharded cluster, you must
enable authentication individually for each member. For a sharded
cluster, this means enabling authentication on each mongos
and
each mongod
, including the config servers and each member of a
shard’s replica set.
The following tutorial uses a keyfile to enable internal authentication. You can also use x.509 certificate for internal authentication. For details on using x.509, see Use x.509 Certificate for Membership Authentication.
Considerations¶
Access Control¶
Enabling internal authentication enables access control. The following tutorial assumes no users have been created in the system before enabling internal authentication, and uses Localhost Exception to add a user administrator after access control has been enabled.
If you prefer, you can create the users before enabling internal authentication.
Sharded Cluster¶
It is not possible to convert an existing sharded cluster that does not enforce access control to require authentication without taking all components of the cluster offline for a short period of time.
For sharded clusters, the Localhost Exception will apply to the individual shards unless you either create an administrative user or disable the localhost exception on each shard.
Procedures¶
Update Existing Deployment¶
Create a keyfile.¶
Create the keyfile your deployment will use to authenticate to members to each other. You can generate a keyfile using any method you choose. Ensure that the password stored in the keyfile is both long and contains a high amount of randomness.
For example, the following operation uses openssl
command to
generate pseudo-random data to use for a keyfile:
Enable authentication for each member of the sharded cluster or replica set.¶
For each mongod
in the replica set or for each
mongos
and mongod
in the sharded cluster,
including all config servers and shards, specify the keyfile using
either a configuration file or a command line option.
In a configuration file, set the security.keyFile
option to the
keyfile’s path and then start the component, as in the following
example:
Include any other settings as appropriate for your deployment.
Or, when starting the component, specify the --keyFile
option. For example, for a mongod
Include any other options as appropriate for your deployment.
Enabling internal authentication enables access control.
Connect to the MongoDB instance via the localhost exception.¶
To add the first user using Localhost Exception:
Add first user.¶
Add a user with the userAdminAnyDatabase
role.
For example, the following creates the user myUserAdmin
on the
admin
database:
After you create the user administrator, for a replica set, the localhost exception is no longer available.
For sharded clusters, you must still prevent unauthorized access to the individual shards. Follow one of the following steps for each shard in your cluster:
- Create an administrative user, or
- Disable the Localhost Exception at startup. To disable the
localhost exception, set the
enableLocalhostAuthBypass
to 0.
Authenticate as the user administrator.¶
Either connect a new mongo
shell to the MongoDB
instance with the -u <username>
, -p <password>
, and
the --authenticationDatabase <database>
:
The mongo
shell executes a number of commands at start
up. As a result, when you log in as the user administrator, you may
see authentication errors from one or more commands. You may ignore
these errors, which are expected, because the
userAdminAnyDatabase
role does not have permissions to
run some of the start up commands.
Or, in the mongo
shell connected without authentication,
switch to the authentication database, and use db.auth()
method to authenticate:
Create additional users as needed for your deployment.¶
Deploy New Replica Set with Access Control¶
Create the key file to be used by each member of the replica set.¶
Create the key file your deployment will use to authenticate servers to each other.
To generate pseudo-random data to use for a
keyfile
, issue the following openssl
command:
You may generate a key file using any method you choose. Always
ensure that the password stored in the key file is both long and
contains a high amount of entropy. Using openssl
in this manner
helps generate such a key.
Copy the key file to each member of the replica set.¶
Copy the mongodb-keyfile
to all hosts where the replica set
members run.
On UNIX systems, the keyfile must not have group or world permissions:
- Ensure that the user running the mongod is the owner of the file.
- Set the permissions of these files to
400
so that only the owner of the file can read this file.
Start each member of the replica set with the appropriate options.¶
For each member, start a mongod
and specify the key file and
the name of the replica set. Also specify other parameters as needed for
your deployment. For replication-specific parameters, see
Replication Options required by your deployment.
If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.
The following example specifies parameters through the --keyFile
and --replSet
command-line options:
If using a configuration file, set the security.keyFile
option
to the keyfile’s path, and the replication.replSetName
option
to the replica set name:
Start the mongod
using the configuration file:
For more information on the configuration file, see configuration options.
Initiate the replica set.¶
Connect a mongo shell to one member of the replica set and run
rs.initiate()
method initiates the replica set.
For example:
The _id
must match the --replSet
parameter or the
replication.replSetName
specified during startup.
Create administrative users.¶
Connected to the primary, create a root user (siteRootAdmin
)
that you will use to complete the remainder of the tutorial:
Authenticate as the newly created user.¶
Create additional users to address operational requirements.¶
You can use built-in roles to create
common types of database users, such as the dbOwner
role to
create a database administrator, the readWrite
role to
create a user who can update data, or the read
role to
create user who can search data but no more. You also can define
custom roles.
For example, the following creates a database administrator for the
products
database:
For an overview of roles and privileges, see Role-Based Access Control. For more information on adding users, see Manage User and Roles.
x.509 Internal Authentication¶
For details on using x.509 for internal authentication, see Use x.509 Certificate for Membership Authentication.
To upgrade from keyfile internal authentication to x.509 internal authentication, see Upgrade from Keyfile Authentication to x.509 Authentication.