updateUser

Definition

  • updateUser
  • Updates the user’s profile on the database on which you run thecommand. An update to a field completely replaces the previousfield’s values, including updates to the user’s roles andauthenticationRestrictions arrays.

Warning

When you update the roles array, you completely replace theprevious array’s values. To add or remove roles without replacing allthe user’s existing roles, use the grantRolesToUser orrevokeRolesFromUser commands.

The updateUser command uses the following syntax. Toupdate a user, you must specify the updateUser field and at leastone other field, other than writeConcern:

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

  1. {
  2.   updateUser: "<username>",
  3.   pwd: passwordPrompt(),      // Or  "<cleartext password>"
  4.   customData: { <any information> },
  5.   roles: [
  6.     { role: "<role>", db: "<database>" } | "<role>",
  7.     ...
  8.   ],
  9.   authenticationRestrictions: [
  10.      {
  11.        clientSource: ["<IP>" | "<CIDR range>", ...],
  12.        serverAddress: ["<IP>", | "<CIDR range>", ...]
  13.      },
  14.      ...
  15.   ],
  16.   mechanisms: [ "<scram-mechanism>", ... ],
  17.   digestPassword: <boolean>,
  18.   writeConcern: { <write concern> }
  19. }

The command has the following fields:

FieldTypeDescriptionupdateUserstringThe name of the user to update.pwdstringOptional. The user’s password. The value can be either:

  • the user’s password in cleartext string, or
  • passwordPrompt() to prompt for the user’s password.

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

customDatadocumentOptional. Any arbitrary information.rolesarrayOptional. The roles granted to the user. An update to the roles arrayoverrides the previous array’s values.writeConcerndocumentOptional. The level of write concern for theupdate operation. The writeConcern document takes the samefields as the getLastError command.authenticationRestrictionsarrayOptional. The authentication restrictions the server enforces upon the user.Specifies a list of IP addresses andCIDR ranges from which theuser is allowed to connect to the server or from which the server canaccept users.

New in version 3.6.

mechanismsarrayOptional. The specific SCRAM mechanism or mechanisms for the user credentials.If authenticationMechanisms is specified, you can onlyspecify a subset of the authenticationMechanisms.

If updating the mechanisms field without the password, you can onlyspecify a subset of the user’s current mechanisms, and only theexisting user credentials for the specified mechanism or mechanismsare retained.

If updating the password along with the mechanisms, new set ofcredentials 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 digestPassword to be true.

New in version 4.0.

digestPasswordbooleanOptional. Indicates whether the server or the client digests the password.

If true, the server receives undigested password from the client anddigests the password.

If false, the client digests the password and passes the digestedpassword to the server. Not compatible with SCRAM-SHA-256

Changed in version 4.0: The default value is true. In earlier versions, the defaultvalue is false.

Roles

In the roles field, you can specify bothbuilt-in roles and user-definedroles.

To specify a role that exists in the same database whereupdateUser runs, you can either specify the role with the name ofthe role:

  1. "readWrite"

Or you can specify the role with a document, as in:

  1. { role: "<role>", db: "<database>" }

To specify a role that exists in a different database, specify the rolewith a document.

Authentication Restrictions

New in version 3.6.

The authenticationRestrictions document can contain only thefollowing fields. The server throws an error if theauthenticationRestrictions document contains an unrecognized field:

Field NameValueDescription
clientSourceArray of IP addresses and/orCIDR rangesIf present, when authenticating a user, the server verifiesthat the client’s IP address is either in the given list orbelongs to a CIDR range in the list. If the client’s IP addressis not present, the server does not authenticate the user.
serverAddressArray of IP addresses and/orCIDR rangesA list of IP addresses or CIDR ranges to which the client canconnect. If present, the server will verify that the client’sconnection was accepted via an IP address in the given list. Ifthe connection was accepted via an unrecognized IP address, theserver does not authenticate the user.

Important

If a user inherits multiple roles with incompatible authenticationrestrictions, that user becomes unusable.

For example, if a user inherits one role in which theclientSource field is ["198.51.100.0"] and another role inwhich the clientSource field is ["203.0.113.0"] the server isunable to authenticate the user.

For more information on authentication in MongoDB, seeAuthentication.

Behavior

Warning

By default, updateUser sends all specified data to the MongoDBinstance in cleartext, even if using passwordPrompt(). UseTLS transport encryption to protect communications between clientsand the server, including the password sent by updateUser. Forinstructions on enabling TLS transport encryption, seeConfigure mongod and mongos for TLS/SSL.

MongoDB does not store the password in cleartext. The passwordis only vulnerable in transit between the client and theserver, and only if TLS transport encryption is not enabled.

Required Access

You must have access that includes the revokeRoleaction on all databases in order to update auser’s roles array.

You must have the grantRoleaction on a role’s database to add a role to a user.

To change another user’s pwd or customData field, you must havethe changeAnyPassword and changeAnyCustomDataactions respectively on that user’s database.

To modify your own password and custom data, you must have privilegesthat grant changeOwnPassword andchangeOwnCustomDataactions respectively on the user’s database.

Example

Given a user appClient01 in the products database with the followinguser info:

  1. {
  2.    "_id" : "products.appClient01",
  3.    "userId" : UUID("c5d88855-3f1e-46cb-9c8b-269bef957986"), // Starting in MongoDB 4.0.9
  4.    "user" : "appClient01",
  5.    "db" : "products",
  6.    "customData" : { "empID" : "12345", "badge" : "9156" },
  7.    "roles" : [
  8.        { "role" : "readWrite",
  9.          "db" : "products"
  10.        },
  11.        { "role" : "read",
  12.          "db" : "inventory"
  13.        }
  14.    ],
  15.    "mechanisms" : [   // Starting in MongoDB 4.0
  16.       "SCRAM-SHA-1",
  17.       "SCRAM-SHA-256"
  18.    ]
  19. }

The following updateUser command completely replaces theuser’s customData and roles data:

  1. use products
  2. db.runCommand( {
  3.    updateUser : "appClient01",
  4.    customData : { employeeId : "0x3039" },
  5.    roles : [ { role : "read", db : "assets" } ]
  6. } )

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

  1. {
  2.    "_id" : "products.appClient01",
  3.    "userId" : UUID("c5d88855-3f1e-46cb-9c8b-269bef957986"), // Starting in MongoDB 4.0.9
  4.    "user" : "appClient01",
  5.    "db" : "products",
  6.    "customData" : { "employeeId" : "0x3039" },
  7.    "roles" : [
  8.        { "role" : "read",
  9.          "db" : "assets"
  10.        }
  11.    ],
  12.    "mechanisms" : [   // Starting in MongoDB 4.0
  13.       "SCRAM-SHA-1",
  14.       "SCRAM-SHA-256"
  15.    ]
  16.  
  17. }