- Security >
- Security Tutorials >
- Enable Access Control >
- Enable Client Access Control
Enable Client Access Control¶
On this page
Overview¶
Enabling access control requires authentication of every user. Once authenticated, users only have the privileges as defined in the roles granted to the users.
To enable access control, use either the command line option --auth
or
security.authorization
configuration file setting.
Note
The tutorial enables access control and uses the default authentication mechanism. To specify a different authentication mechanism, see Authentication Mechanisms.
You can also enable client access control by enabling internal authentication of replica sets or sharded clusters. For instructions on enabling internal authentication, see Enable Internal Authentication.
This tutorial assumes a standalone environment. For a tutorial on enabling access control on a replica set, see Enable Internal Authentication.
Considerations¶
With access control enabled, ensure you have a user with userAdmin
or userAdminAnyDatabase
role in the admin
database.
You can create users before enabling access control or you can create
users after enabling access control. If you enable access control before
creating any user, MongoDB provides a localhost exception which allows you to create a user administrator in
the admin
database. Once created, authenticate as the user
administrator to create additional users as needed.
Procedures¶
Add Users Before Enabling Access Control¶
The following procedure first adds a user administrator to a MongoDB instance running without access control and then enables access control.
Start MongoDB without access control.¶
For example, the following starts a standalone mongod
instance
without access control.
For details on starting a mongod
or mongos
, see
Manage mongod Processes or
Deploy a Sharded Cluster.
Create the user administrator.¶
Add a user with the userAdminAnyDatabase
role.
For example, the following creates the user myUserAdmin
on the
admin
database:
Re-start the MongoDB instance with access control.¶
Re-start the mongod
instance with the --auth
command
line option or, if using a configuration file, the
security.authorization
setting.
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.¶
If you need to disable access control for any reason, restart the MongoDB
instance without the --auth
command line option, or if using a
configuration file, the security.authorization
setting.
Add Users After Enabling Access Control¶
The following procedure first enables access control, and then uses localhost exception to add a user administrator.
Start the MongoDB instance with access control.¶
Start the mongod
instance with the --auth
command line
option or, if using a configuration file, the
security.authorization
setting.
Create the system user administrator.¶
Add the user with the userAdminAnyDatabase
role, and
only that role.
The following example creates the user myUserAdmin
user on the
admin
database:
After you create the user administrator, the localhost exception is no longer available.
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.¶
Additional Information¶
See also Manage User and Roles.