db.updateUser.txt

===============
db.updateUser()
===============

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. method:: db.updateUser( username, update, writeConcern )

   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.

   .. warning::

      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 :method:`db.grantRolesToUser()` or
      :method:`db.revokeRolesFromUser()` methods.

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

   .. tip::

      .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst

   .. code-block:: javascript

      db.updateUser(
         "<username>",
         {
           customData : { <any information> },
           roles : [
             { role: "<role>", db: "<database>" } | "<role>",
             ...
           ],
           pwd: passwordPrompt(),      // Or  "<cleartext password>"
           authenticationRestrictions: [
              {
                clientSource: ["<IP>" | "<CIDR range>", ...],
                serverAddress: ["<IP>", | "<CIDR range>", ...]
              },
              ...
           ],
           mechanisms: [ "<SCRAM-SHA-1|SCRAM-SHA-256>", ... ],
           passwordDigestor: "<server|client>"
         },
         writeConcern: { <write concern> }
      )

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


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Parameter
        - Type
        - Description
      * - ``username``
        - string
        - The name of the user to update.
      * - ``update``
        - document
        - A document containing the replacement data for the user. This
          data completely replaces the corresponding data for the user.
      * - ``writeConcern``
        - document
        - .. include:: /includes/fact-write-concern-spec-link.rst

   The ``update`` document specifies the fields to update and their
   new values. All  fields in the ``update`` document are optional,
   but *must* include at least one field.

   The ``update`` document has the following fields:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Field
   
        - Type
   
        - Description
   
      * - ``customData``
   
        - document
   
        - Optional. Any arbitrary information.
          
          
   
      * - ``roles``
   
        - array
   
        - Optional. The roles granted to the user. An update to the ``roles`` array
          overrides the previous array's values.
          
          
   
      * - ``pwd``
   
        - string
   
        - Optional. The user's password. The value can be either:
          
          - the user's password in cleartext string, or
          
          - :method:`passwordPrompt()` to prompt for the user's password. 
         
          .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst
          
          
   
      * - ``authenticationRestrictions``
   
        - array
   
        - Optional. The authentication restrictions the server enforces upon the user.
          Specifies a list of IP addresses and
          :abbr:`CIDR (Classless Inter-Domain Routing)` ranges from which the
          user is allowed to connect to the server or from which the server can
          accept users.
          
          
   
      * - ``mechanisms``
   
        - array
   
        - Optional. The specific SCRAM mechanism or mechanisms for the user credentials.
          If :parameter:`authenticationMechanisms` is specified, you can only
          specify a subset of the :parameter:`authenticationMechanisms`.
          
          If updating the mechanisms field without the password, you can only
          specify a subset of the user's current mechanisms, and only the
          existing user credentials for the specified 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``.
          
   
      * - ``passwordDigestor``
   
        - string
   
        - Optional. Indicates whether the server or the client digests the password.
          
          Available values are:
          
          - ``"server"`` (Default)
                The server receives undigested password from the client and
                digests the password.
          
          - ``"client"`` (Not compatible with ``SCRAM-SHA-256``)
                The client digests the password and passes the digested
                password to the server.
          
Roles
~~~~~

.. |local-cmd-name| replace:: :method:`db.updateUser()`
.. include:: /includes/fact-roles-array-contents.rst

Authentication Restrictions
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-auth-restrictions-array-contents.rst

The :method:`db.updateUser()` method wraps the :dbcommand:`updateUser`
command.

Compatibility
-------------

This method is available in deployments hosted in the following
environments:

.. include:: /includes/fact-environments-no-atlas-support.rst

.. include:: /includes/fact-environments-onprem-only.rst

Behavior
--------

Replica set
~~~~~~~~~~~

.. |command| replace:: :method:`db.updateUser()`

.. include:: /includes/fact-management-methods-write-concern.rst

Encryption
~~~~~~~~~~

.. include:: /includes/fact-cleartext-passwords-tls.rst

Required Access
---------------

.. include:: /includes/access-update-user.rst

.. include:: /includes/access-change-own-password-and-custom-data.rst

Example
-------

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

.. code-block:: javascript

   {
      _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 : [ 
         "SCRAM-SHA-1",
         "SCRAM-SHA-256"
      ],
      authenticationRestrictions : [ {
         clientSource: ["69.89.31.226"],
         serverAddress: ["172.16.254.1"]
      } ]
   }

The following :method:`db.updateUser()` method **completely** replaces the
user's ``customData`` and ``roles`` data:

.. code-block:: javascript

   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:

.. code-block:: javascript

   {
      _id : "products.appClient01",
      userId : UUID("c5d88855-3f1e-46cb-9c8b-269bef957986"),
      user : "appClient01",
      db : "products",
      customData : { employeeId : "0x3039" },
      roles : [
          {
            role : "read",
            db : "assets"
          }
      ],
      mechanisms : [
         "SCRAM-SHA-1",
         "SCRAM-SHA-256"
      ],
      authenticationRestrictions : [ {
         clientSource: ["69.89.31.226"],
         serverAddress: ["172.16.254.1"]
      } ]
   }
   
Update User to Use ``SCRAM-SHA-256`` Credentials Only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::

   To use :ref:`SCRAM-SHA-256 <authentication-scram-sha-256>`, the
   ``featureCompatibilityVersion`` must be set to ``4.0``. For more
   information on featureCompatibilityVersion, see :ref:`view-fcv` and
   :dbcommand:`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"``.

.. code-block:: javascript

   use reporting
   db.updateUser(
      "reportUser256",
      {
        mechanisms: [ "SCRAM-SHA-256" ]
      }
   )