DOCS-1515 add documentation of changeUserPassword in 2.4

bin/htaccess.yaml

@@ -1783,4 +1783,11 @@ code: 301
 outputs:
   - 'after-v2.2'
   - 'manual'
+---
+redirect-path: '/tutorial/change-user-password'
+url-base: 'tutorial/control-access-to-mongodb-with-authentication'
+type: 'redirect'
+code: 303
+outputs:
+  - 'v2.2'
 ...

source/includes/fact-change-password.rst

@@ -0,0 +1,6 @@
+In previous versions of MongoDB, you could change an existing user's
+password by calling :method:`db.addUser()` again with the user's
+username and their updated password. Anything specified in the
+:method:`~addUser()` method would override the existing information for
+that user. In newer versions of MongoDB, this will result in a duplicate
+key error.

source/includes/ref-toc-method-database.yaml

@@ -6,6 +6,10 @@ name: ":method:`db.auth()`"
 file: /reference/method/db.auth
 description: "Authenticates a user to a database."
 ---
+name: ":method:`db.changeUserPassword()`"
+file: /reference/method/db.changeUserPassword
+description: "Changes an existing user's password."
+---
 name: ":method:`db.cloneCollection()`"
 file: /reference/method/db.cloneCollection
 description: "Copies data directly between MongoDB instances. Wraps :dbcommand:`cloneCollection`."

source/reference/method/db.changeUserPassword.txt

@@ -0,0 +1,27 @@
+=======================
+db.changeUserPassword()
+=======================
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.changeUserPassword(username, password)
+
+   Allows an administrator to update a user's password from within
+   the shell.
+
+   .. include:: /reference/method/db.auth-param.rst
+
+   :throws exception: 
+         If an error occurs, the
+         :method:`~db.changeUserPassword()` helper throws an exception with the
+         error message and code.
+
+Example
+-------
+
+.. include:: /tutorial/change-user-password.txt
+   :start-after: begin-reference-example-content
+   :end-before: end-reference-example-content

source/security.txt

@@ -41,6 +41,7 @@ Access Control
    /tutorial/enable-authentication
    /tutorial/add-user-administrator
    /tutorial/add-user-to-database
+   /tutorial/change-user-password
    /tutorial/generate-key-file
    /tutorial/control-access-to-mongodb-with-kerberos-authentication
 

source/tutorial/add-user-to-database.txt

@@ -19,6 +19,13 @@ user's credentials and privileges. The :method:`db.addUser()` method
 adds the document to the database's :data:`system.users
 <<database>.system.users>` collection.
 
+.. versionchanged:: 2.4 
+   .. include:: /includes/fact-change-password.rst
+
+   To change a user's password in version
+   2.4 or newer, see :doc:`Change a User's Password
+   </tutorial/change-user-password>`.
+
 For the structure of a privilege document, see :data:`system.users
 <<database>.system.users>`. For descriptions of user roles, see
 :doc:`/reference/user-privileges`.

source/tutorial/change-user-password.txt

@@ -0,0 +1,36 @@
+========================
+Change a User's Password
+========================
+
+.. versionadded:: 2.4
+
+.. default-domain:: mongodb
+
+To change a user's password, you must have the :authrole:`userAdmin`
+role on the database that contains the definition of the user whose
+password you wish to change.
+
+To update the password, pass the user's username
+and the new desired password to the :method:`db.changeUserPassword()` 
+method.
+
+.. begin-reference-example-content
+
+.. example:: The following operation changes the ``reporting`` user's
+   password to ``SOhSS3TbYhxusooLiW8ypJPxmt1oOfL``:
+
+ .. code-block:: javascript
+
+      db = db.getSiblingDB('records')
+      db.changeUserPassword("reporting", "SOhSS3TbYhxusooLiW8ypJPxmt1oOfL")
+
+.. end-reference-example-content
+
+
+.. note::
+
+   .. include:: /includes/fact-change-password.rst
+
+   For more about changing a user's password prior to version 2.4,
+   see: :doc:`Add a User to a Database
+   </tutorial/add-user-to-database>`.