- Reference >
mongo
Shell Methods >- User Management Methods >
- db.createUser()
db.createUser()¶
On this page
Definition¶
-
db.
createUser
(user, writeConcern)¶ Creates a new user for the database where the method runs.
db.createUser()
returns a duplicate user error if the user already exists on the database.The
db.createUser()
method has the following syntax:Field Type Description user
document The document with authentication and access information about the user to create. writeConcern
document Optional. The level of write concern for the creation operation. The writeConcern
document takes the same fields as thegetLastError
command.The
user
document defines the user and has the following form:The
user
document has the following fields:Field Type Description user
string The name of the new user. pwd
string The user’s password. The pwd
field is not required if you rundb.createUser()
on the$external
database to create users who have credentials stored externally to MongoDB.customData
document Optional. Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user’s full name or employee id. roles
array The roles granted to the user. Can specify an empty array []
to create users without roles.In the
roles
field, you can specify both built-in roles and user-defined role.To specify a role that exists in the same database where
db.createUser()
runs, you can either specify the role with the name of the role:Or you can specify the role with a document, as in:
To specify a role that exists in a different database, specify the role with a document.
The
db.createUser()
method wraps thecreateUser
command.
Behavior¶
Encryption¶
Warning
By default, db.createUser()
sends all specified data to the MongoDB
instance in cleartext. Use TLS transport encryption to protect
communications between clients and the server,
including the password sent by db.createUser()
. For
instructions on enabling TLS transport encryption, see
Configure mongod and mongos for TLS/SSL.
MongoDB does not store the password in cleartext. The password is only vulnerable in transit between the client and the server, and only if TLS transport encryption is not enabled.
External Credentials¶
Users created on the $external
database should have credentials
stored externally to MongoDB, as, for example, with MongoDB
Enterprise installations that use Kerberos.
local
Database¶
You cannot create users on the local database.
Required Access¶
- To create a new user in a database, you must have the
createUser
action on that database resource. - To grant roles to a user, you must have the
grantRole
action on the role’s database.
The userAdmin
and
userAdminAnyDatabase
built-in roles
provide createUser
and
grantRole
actions on their respective resources.
Examples¶
The following db.createUser()
operation creates the
accountAdmin01
user on the products
database.
The operation gives accountAdmin01
the following roles:
- the
clusterAdmin
andreadAnyDatabase
roles on theadmin
database - the
readWrite
role on theproducts
database
Create User with Roles¶
The following operation creates accountUser
in the products
database
and gives the user the readWrite
and dbAdmin
roles.
Create User Without Roles¶
The following operation creates a user named reportsUser
in the admin
database but does not yet assign roles:
Create Administrative User with Roles¶
The following operation creates a user named appAdmin
in the
admin
database and gives the user readWrite
access to the
config
database, which lets the user change certain settings for
sharded clusters, such as to the balancer setting.