Reference > mongo Shell Methods > User Management Methods

On this page

db.updateUser() Definition

Behavior
Definition
Required Access
db.updateUser( username, update, writeConcern )
Example

Updates the user's profile on the database on which you run the
method.
An update to a field completely replaces the previous field's
values.
This includes updates to the user's roles array.

WAR N I NG

When you update the roles array, you completely replace

the
previous array's values. To add or remove roles without
replacing all
the user's existing roles, use the
db.grantRolesToUser() or
db.revokeRolesFromUser() methods.

The db.updateUser() method uses the following syntax:

TI P

Starting in version 4.2 of the mongo shell, you can

use the
passwordPrompt() method in conjunction with
various
user authentication/management methods/commands to
prompt
for the password instead of specifying the
password directly in the
method/command call. However,
you can still specify the password
directly as you would
with earlier versions of the
mongo shell. Give Feedback
 db.updateUser(
"<username>",
{
customData : { <any information> },
On this page
roles : [
{ role: "<role>", db: "<database>" } | "<role>"
Definition
...
], Behavior
pwd: passwordPrompt(), // Or "<cleartext pa
Required Access
authenticationRestrictions: [
{ Example
clientSource: ["<IP>" | "<CIDR range>", ...]
serverAddress: ["<IP>", | "<CIDR range>", ..
},
...
],
mechanisms: [ "<SCRAM-SHA-1|SCRAM-SHA-256>", ...
passwordDigestor: "<server|client>"
},
writeConcern: { <write concern> }
)

The db.updateUser() method has the following arguments.

Parameter Type Description

username string The name of the user to update.

A document containing the

update document
replacement data for the user. This
data completely replaces the
corresponding data for the user.

Give Feedback
 Parameter Type Description

writeConc Optional. The level of write concern for

document
ern the
update operation. The
writeConcern document takes the
same
fields as the getLastError On this page
command.
Definition

The update document specifies the fields to update and their

new Behavior
values. All fields in the update document are optional,
but must
Required Access
include at least one field.
Example
The update document has the following fields:

Field Type Description

customDat
document Optional. Any arbitrary information.
a

Optional. The roles granted to the user.

roles array
An update to the roles array
overrides
the previous array's values.

Give Feedback
Field Type Description

Optional. The user's password. The

pwd string
value can be either:

the user's password in cleartext string,

On this page
or
passwordPrompt() to prompt for the Definition
user's password.
Behavior
TI P
Required Access

Starting in version 4.2 of the Example

mongo shell, you can
use
the passwordPrompt()
method in conjunction with
various user
authentication/management
methods/commands to
prompt
for the password
instead of specifying the
password directly in the
method/command call.
However, you can still
specify the password
directly as you would with
earlier versions of the
mongo
shell.

Give Feedback
Field Type Description

authentic Optional. The authentication

array
ationRest restrictions the server enforces upon
rictions the user.
Specifies a list of IP
addresses and
CIDR ranges from On this page
which the
user is allowed to connect to
the server or from which the server can Definition
accept users.
Behavior
New in version 3.6.
Required Access

Example

Give Feedback
Field Type Description

mechanism Optional. The specific SCRAM

array
s mechanism or mechanisms for the user
credentials.
If
authenticationMechanisms is On this page
specified, you can only
specify a subset
of the authenticationMechanisms. Definition
If updating the mechanisms field
Behavior
without the password, you can only
specify a subset of the user's current Required Access
mechanisms, and only the
existing user
credentials for the specified Example
mechanism or mechanisms
are
retained.

If updating the password along with the

mechanisms, new set of
credentials are
stored for the user.
Valid values are:

"SCRAM-SHA-1"
Uses the SHA-1 hashing function.

"SCRAM-SHA-256"
Uses the SHA-256 hashing function.
Requires featureCompatibilityVersion
set to 4.0.
Requires passwordDigestor to be
server.

New in version 4.0.

Give Feedback
 Field Type Description

passwordD Optional. Indicates whether the server

string
igestor or the client digests the password.
Available values are:
On this page

"server" (Default) Definition

Behavior
The server receives undigested
password from the client and Required Access
digests the password.
Example

"client" (Not compatible with

SCRAM-SHA-256)

The client digests the password

and passes the digested
password
to the server.

Changed in version 4.0: The default

value is "server". In earlier versions,
the
default value is "client".

Roles

In the roles field, you can specify both

built-in roles and user-defined
roles.

To specify a role that exists in the same database where

db.updateUser() runs, you can either specify the role with the name of
the role:

"readWrite"

Or you can specify the role with a document, as in: Give Feedback
 { role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the role

with a
document.

On this page
Authentication Restrictions
Definition
New in version 3.6.
Behavior

The authenticationRestrictions document can contain only the Required Access

following fields. The server throws an error if the
Example
authenticationRestrictions document contains an unrecognized
field:

Field
Value Description
Name

clientSou Array of IP If present, when authenticating a

rce addresses and/or user, the server verifies
that the
CIDR ranges client's IP address is either in the
given list or
belongs to a CIDR
range in the list. If the client's IP
address
is not present, the server
does not authenticate the user.

serverAdd Array of IP A list of IP addresses or CIDR

ress addresses and/or ranges to which the client can
CIDR ranges connect. If present, the server will
verify that the client's
connection
was accepted via an IP address in
the given list. If
the connection
was accepted via an unrecognized
IP address, the
server does not
authenticate the user.

I M PORTANT

If a user inherits multiple roles with incompatible authentication

restrictions, that user becomes unusable. Give Feedback
 For example, if a user inherits one role in which the
clientSource field is ["198.51.100.0"] and another role
in
which the clientSource field is ["203.0.113.0"] the
server is
unable to authenticate the user.

On this page

For more information on authentication in MongoDB, see

Authentication. Definition

The db.updateUser() method wraps the updateUser

command. Behavior

Required Access
Behavior
Example

Replica set

If run on a replica set, db.updateUser() is executed using majority

write concern by default.

Encyption

WAR N I NG

By default, db.updateUser() sends all specified data to the

MongoDB
instance in cleartext, even if using
passwordPrompt(). Use
TLS transport encryption to protect
communications between clients
and the server, including the
password sent by db.updateUser(). 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.

Required Access
Give Feedback
You must have access that includes the revokeRole
action on all
databases in order to update a
user's roles array.

You must have the grantRole action on a role's database to add a role to
a user.
On this page
To change another user's pwd or customData field, you must have
the
changePassword and changeCustomData
actions respectively on that Definition
user's database. Behavior

To modify your own password and custom data, you must have privileges Required Access
that grant changeOwnPassword and
changeOwnCustomData actions Example
respectively on the user's database.

Example
Given a user appClient01 in the products database with the following
user info:

{
_id : "products.appClient01",
userId : UUID("c5d88855-3f1e-46cb-9c8b-269bef957986"),
user : "appClient01",
db : "products",
customData : { empID : "12345", badge : "9156" },
roles : [
{
role : "readWrite",
db : "products"
},
{
role : "read",
db : "inventory"
}
],
mechanisms : [ // Starting in MongoDB 4.0
"SCRAM-SHA-1", Give Feedback
 "SCRAM-SHA-256"
],
authenticationRestrictions : [ {
clientSource: ["69.89.31.226"],
serverAddress: ["172.16.254.1"]
} ] On this page
}
Definition

Behavior
The following db.updateUser() method completely replaces the
user's
Required Access
customData and roles data:
Example
use products
db.updateUser( "appClient01",
{
customData : { employeeId : "0x3039" },
roles : [
{ role : "read", db : "assets" }
]
} )

The user appClient01 in the products database now has the following
user information:

{
_id : "products.appClient01",
userId : UUID("c5d88855-3f1e-46cb-9c8b-269bef957986"),
user : "appClient01",
db : "products",
customData : { employeeId : "0x3039" },
roles : [
{
role : "read",
db : "assets"
}
], Give Feedback
 mechanisms : [ // Starting in MongoDB 4.0
"SCRAM-SHA-1",
"SCRAM-SHA-256"
],
authenticationRestrictions : [ {
clientSource: ["69.89.31.226"], On this page
serverAddress: ["172.16.254.1"]
} ] Definition
}
Behavior

Required Access

Update User to Use SCRAM-SHA-256 Credentials Only Example

NOTE

To use SCRAM-SHA-256, the

featureCompatibilityVersion must be set to 4.0. For
more
information on featureCompatibilityVersion, see View
FeatureCompatibilityVersion and
setFeatureCompatibilityVersion.

The following operation updates a user who currently have both

SCRAM-
SHA-256 and SCRAM-SHA-1 credentials to have only
SCRAM-SHA-256
credentials.

NOTE

If the password is not specified along with the mechanisms,

you can only update the mechanisms to a subset of the
current
SCRAM mechanisms for the user.
If the password is specified along with the mechanisms, you
can specify any supported SCRAM mechanism or
mechanisms.
For SCRAM-SHA-256, the passwordDigestor must be the
default value "server". Give Feedback
use reporting
db.updateUser(
"reportUser256",
{
On this page
mechanisms: [ "SCRAM-SHA-256" ]
} Definition
)
Behavior

Required Access

Example

Give Feedback