mongodb · mpaik · Feb 6, 2015
diff --git a/source/core/authentication.txt b/source/core/authentication.txt
@@ -61,9 +61,11 @@ database.
 Authentication Mechanisms
 -------------------------
 
+.. versionchanged:: 3.0
+
 MongoDB supports multiple authentication mechanisms. MongoDB's default
 authentication method is a :ref:`challenge and response mechanism
-(MONGODB-CR) <authentication-mongodb-cr>`. MongoDB also supports
+(SCRAM-SHA-1) <authentication-scram-sha-1>`. MongoDB also supports
 :ref:`x509 certificate authentication <security-auth-x509>`, :ref:`LDAP
 proxy authentication <security-auth-ldap>`, and :ref:`Kerberos
 authentication <security-auth-kerberos>`.
@@ -73,20 +75,66 @@ This section introduces the mechanisms available in MongoDB.
 To specify the authentication mechanism to use, see
 :parameter:`authenticationMechanisms`.
 
+.. _authentication-scram-sha-1:
+
+``SCRAM-SHA-1`` Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.0
+
+``SCRAM-SHA-1`` is an IETF standard,
+`RFC 5802 <https://tools.ietf.org/html/rfc5802>`_, that defines best practice
+methods for implementation of challenge-response mechanisms for authenticating
+users with passwords.
+
+``SCRAM-SHA-1`` verifies supplied user credentials against the user's
+:data:`name <admin.system.users.user>`, :data:`password
+<admin.system.users.credentials>` and :data:`database
+<admin.system.users.db>`. The user's database is the database where
+the user was created, and the user's database and the user's name
+together serves to identify the user.
+
+MongoDB's implementation of ``SCRAM-SHA-1`` represents an improvement
+in security over the previously-used ``MONGODB-CR``, providing:
+
+- A tunable work factor (``iterationCount``),
+- Per-user random salts rather than server-wide salts,
+- A cryptographically stronger hash function (``SHA-1`` rather than ``MD5``),
+  and
+- Authentication of the server to the client as well as the client to the
+  server.
+
+.. versionchanged:: 3.0
+
+   ``SCRAM-SHA-1`` is the default mechanism for MongoDB versions
+   beginning with the 3.0 series. Legacy ``MONGODB-CR`` credentials
+   from databases created with older server versions will still work
+   under 3.0 but must be upgraded with :dbcommand:`authSchemaUpgrade`
+   in order to take advantage of many of the improvements. The server
+   will continue to use the legacy credentials until it undergoes this
+   upgrade. Clients and drivers compatible with 3.0 will use the
+   ``SCRAM`` communication protocol even while using the legacy
+   credentials.
+
 .. _authentication-mongodb-cr:
 
 ``MONGODB-CR`` Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``MONGODB-CR`` is a challenge-response mechanism that authenticates
-users through passwords. ``MONGODB-CR`` is the default mechanism.
+users through passwords.
+
+.. versionchanged:: 3.0
+   Versions of MongoDB prior to 3.0 use ``MONGODB-CR`` as the default
+   mechanism. As of version 3.0, MongoDB uses ``SCRAM-SHA-1`` by
+   default.
 
-When you use ``MONGODB-CR`` authentication, ``MONGODB-CR`` verifies the
-user against the user's :data:`name <admin.system.users.user>`,
-:data:`password <admin.system.users.credentials>` and :data:`database
-<admin.system.users.db>`. The user's database is the database where the
-user was created, and the user's database and the user's name together
-serves to identify the user.
+``MONGODB-CR`` verifies supplied user credentials against the user's
+:data:`name <admin.system.users.user>`, :data:`password
+<admin.system.users.credentials>` and :data:`database
+<admin.system.users.db>`. The user's database is the database where
+the user was created, and the user's database and the user's name
+together serve to identify the user.
 
 Using :setting:`key files <security.keyFile>`, you can also use
 ``MONGODB-CR`` authentication for the :ref:`internal member
@@ -266,7 +314,7 @@ exception allows connections from the localhost interface to create
 the first user on the ``admin`` database. The exception applies only
 when there are no users created in the MongoDB instance.
 
-.. versionchanged:: 3.0.0
+.. versionchanged:: 2.8.0
    The localhost exception changed so that these connections *only*
    have access to create the first user on the ``admin``
    database. In previous versions, connections that gained access

diff --git a/source/includes/apiargs-method-db.auth-param.yaml b/source/includes/apiargs-method-db.auth-param.yaml
@@ -20,7 +20,18 @@ type: string
 ---
 arg_name: param
 description: |-
-  Specifies the authentication mechanism used. Defaults to ``MONGODB-CR``. ``PLAIN`` is used for :doc:`SASL/LDAP authentication </tutorial/configure-ldap-sasl-openldap>`, available only in MongoDB Enterprise.
+  Specifies the authentication mechanism used. 
+
+  .. versionchanged:: 3.0
+
+  Defaults to ``SCRAM-SHA-1`` on new 3.0 installations and on 2.6
+  databases that have been upgraded to 3.0 and have undergone
+  :dbcommand:`authSchemaUpgrade`.  Defaults to ``MONGODB-CR``
+  otherwise.
+
+  ``PLAIN`` is used for :doc:`SASL/LDAP authentication
+  </tutorial/configure-ldap-sasl-openldap>`, available only in MongoDB
+  Enterprise.
 interface: method
 name: mechanism
 operation: db.auth

diff --git a/source/includes/options-conf.yaml b/source/includes/options-conf.yaml
@@ -732,13 +732,19 @@ post: |
 program: conf
 name: security.authenticationMechanisms
 # the equivalent command-line option is set via setParameter.
-type: strings
+# disabled pending server-12892, see /reference/configuration-options.txt
+type: string
+default: SCRAM-SHA-1
 directive: setting
 description: |
   .. versionchanged:: 2.6
      Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication
      mechanisms.
 
+  .. versionchanged:: 3.0
+     Added support for the ``SCRAM-SHA-1`` authentication mechanism. Changed
+     default mechanism to ``SCRAM-SHA-1``.
+
   Specifies the list of authentication mechanisms the server accepts. Set
   this to one or more of the following values. If you specify multiple
   values, use a comma-separated list and no spaces. For descriptions
@@ -752,27 +758,34 @@ description: |
 
        - Description
 
-     * - MONGODB-CR
+     * - :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>`
+
+       - `RFC 5802 <https://tools.ietf.org/html/rfc5802>`_ standard
+         Salted Challenge Response Authentication Mechanism using the SHA1
+         hash function.
+
+     * - :ref:`MONGODB-CR <authentication-mongodb-cr>`
 
        - MongoDB challenge/response authentication.
 
-     * - MONGODB-X509
+     * - :ref:`MONGODB-X509 <security-auth-x509>`
 
        - MongoDB SSL certificate authentication.
 
-     * - PLAIN
+     * - :ref:`GSSAPI <security-auth-kerberos>` (Kerberos)
+
+       - External authentication using Kerberos. This mechanism is
+         available only in `MongoDB Enterprise
+         <http://www.mongodb.com/products/mongodb-enterprise>`_.
+
+     * - :ref:`PLAIN <security-auth-ldap>` (LDAP SASL)
 
        - External authentication using LDAP. You can also use ``PLAIN``
          for authenticating in-database users. ``PLAIN`` transmits
          passwords in plain text. This mechanism is available only in
          `MongoDB Enterprise
          <http://www.mongodb.com/products/mongodb-enterprise>`_.
 
-     * - GSSAPI
-
-       - External authentication using Kerberos. This mechanism is
-         available only in `MongoDB Enterprise
-         <http://www.mongodb.com/products/mongodb-enterprise>`_.
 # Per DOCS-2940, combine this with similar info in
 #   /includes/options-shared
 #   /reference/connection-string

diff --git a/source/includes/options-shared.yaml b/source/includes/options-shared.yaml
@@ -282,7 +282,7 @@ name: authenticationMechanism
 # This describes the authenticationMechanism option that is used by the
 # various client tools.
 args: <name>
-default: MONGODB-CR
+default: SCRAM-SHA-1
 directive: option
 description: |
   .. versionadded:: 2.4
@@ -291,6 +291,10 @@ description: |
      Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication
      mechanisms.
 
+  .. versionchanged:: 3.0
+     Added support for the ``SCRAM-SHA-1`` authentication mechanism. Changed
+     default mechanism to ``SCRAM-SHA-1``.
+
   Specifies the authentication mechanism the {{program}} instance uses to
   authenticate to the :program:`mongod` or :program:`mongos`.
 
@@ -302,27 +306,34 @@ description: |
 
        - Description
 
-     * - MONGODB-CR
+     * - :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>`
+
+       - `RFC 5802 <https://tools.ietf.org/html/rfc5802>`_ standard
+         Salted Challenge Response Authentication Mechanism using the SHA1
+         hash function.
+
+     * - :ref:`MONGODB-CR <authentication-mongodb-cr>`
 
        - MongoDB challenge/response authentication.
 
-     * - MONGODB-X509
+     * - :ref:`MONGODB-X509 <security-auth-x509>`
 
        - MongoDB SSL certificate authentication.
 
-     * - PLAIN
+     * - :ref:`GSSAPI <security-auth-kerberos>` (Kerberos)
+
+       - External authentication using Kerberos. This mechanism is
+         available only in `MongoDB Enterprise
+         <http://www.mongodb.com/products/mongodb-enterprise>`_.
+
+     * - :ref:`PLAIN <security-auth-ldap>` (LDAP SASL)
 
        - External authentication using LDAP. You can also use ``PLAIN``
          for authenticating in-database users. ``PLAIN`` transmits
          passwords in plain text. This mechanism is available only in
          `MongoDB Enterprise
          <http://www.mongodb.com/products/mongodb-enterprise>`_.
 
-     * - GSSAPI
-
-       - External authentication using Kerberos. This mechanism is
-         available only in `MongoDB Enterprise
-         <http://www.mongodb.com/products/mongodb-enterprise>`_.
 # Per DOCS-2940, combine this with similar info in
 #   /includes/options-conf
 #   /reference/connection-string

diff --git a/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml b/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml
@@ -0,0 +1,53 @@
+title:
+  text: Connect to the MongoDB instance.
+  character: '`'
+stepnum: 1
+ref: connect
+content: |
+  Connect and authenticate to the :program:`mongod` instance for a
+  single deployment, the primary ``mongod`` for a replica set, or a
+  :program:`mongos` for a sharded cluster as an ``admin`` database
+  user with the role :authrole:`userAdminAnyDatabase`.
+---
+title:
+  text: Upgrade authentication schema.
+  character: '`'
+ref: upgrade-auth-schema
+stepnum: 2
+pre: |
+  Use the :dbcommand:`authSchemaUpgrade` command in the ``admin``
+  database to update the user data using the :program:`mongo` shell.
+action:
+  - heading:
+      text: Run ``authSchemaUpgrade`` command.
+      character: "'"
+    language: javascript
+    code: |
+      db.adminCommand({authSchemaUpgrade: 1});
+    post: |
+      In case of error, you may safely rerun the
+      :dbcommand:`authSchemaUpgrade` command.
+  - heading:
+      text: Sharded cluster ``authSchemaUpgrade`` consideration.
+      character: "'"
+    pre: |
+      For a sharded cluster *without* :ref:`shard local users
+      <_sharding-security>`, :dbcommand:`authSchemaUpgrade` will, by
+      default, upgrade the authorization data of the shards as well,
+      completing the upgrade.
+
+      You can, however, override this behavior by including
+      ``upgradeShards: false`` in the command, as in the following
+      example:
+    language: javascript
+    code: |
+      db.adminCommand(
+         {authSchemaUpgrade: 1, upgradeShards: false }
+      );
+    post: |
+      If you override the default behavior or your cluster has shard
+      local users, after running :dbcommand:`authSchemaUpgrade` on a
+      :program:`mongos` instance, you will need to connect to the
+      primary for each shard and repeat the upgrade process after
+      upgrading on the :program:`mongos`.
+...
diff --git a/source/reference/command/authSchemaUpgrade.txt b/source/reference/command/authSchemaUpgrade.txt
@@ -8,11 +8,11 @@ authSchemaUpgrade
 
 .. dbcommand:: authSchemaUpgrade
 
-   :dbcommand:`authSchemaUpgrade` supports the upgrade from 2.4 to 2.6
-   process for existing systems that use :term:`authentication` and
-   :term:`authorization`. Between 2.4 and 2.6 the schema for user
-   credential documents changed requiring the
-   :dbcommand:`authSchemaUpgrade` process.
+   .. versionchanged:: 3.0
 
-   See :doc:`/release-notes/2.6-upgrade-authorization` for more
-   information.
+   :dbcommand:`authSchemaUpgrade` supports the upgrade process for
+   existing systems that use :term:`authentication` and
+   :term:`authorization` between:
+
+   - 2.4 and 2.6 (See :doc:`/release-notes/2.6-upgrade-authorization`)
+   - 2.6 and 3.0 (See :doc:`/release-notes/2.8-scram`)
diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt
@@ -322,18 +322,23 @@ Authentication Options
    .. versionadded:: 2.4
 
    .. versionchanged:: 2.6
-      Support for the ``PLAIN`` and ``MONGODB-X509`` authentication mechanisms.
+      Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication
+      mechanisms.
+
+   .. versionchanged:: 3.0
+      Added support for the ``SCRAM-SHA-1`` authentication mechanism.
 
    Specify the authentication mechanism that MongoDB will use to
    authenticate the connection. Possible values include:
 
    .. these options should link to a reference page for authentication
       mechanisms. DOCS-2940
 
-   - MONGODB-CR
-   - MONGODB-X509
-   - GSSAPI
-   - PLAIN
+   - :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>`
+   - :ref:`MONGODB-CR <authentication-mongodb-cr>`
+   - :ref:`MONGODB-X509 <security-auth-x509>`
+   - :ref:`GSSAPI <security-auth-kerberos>` (Kerberos)
+   - :ref:`PLAIN <security-auth-ldap>` (LDAP SASL)
 
    Only MongoDB Enterprise :program:`mongod` and :program:`mongos`
    instances provide ``GSSAPI`` (Kerberos) and ``PLAIN`` (LDAP)

diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt
@@ -467,6 +467,10 @@ Parameters
       Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication
       mechanisms.
 
+   .. versionchanged:: 3.0
+      Added support for the ``SCRAM-SHA-1`` authentication mechanism.
+
+
    Specifies the list of authentication mechanisms the server accepts. Set
    this to one or more of the following values. If you specify multiple
    values, use a comma-separated list and no spaces. For descriptions
@@ -480,28 +484,34 @@ Parameters
 
         - Description
 
-      * - MONGODB-CR
+      * - :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>`
+
+        - `RFC 5802 <https://tools.ietf.org/html/rfc5802>`_ standard
+          Salted Challenge Response Authentication Mechanism using the SHA-1
+          hash function.
+
+      * - :ref:`MONGODB-CR <authentication-mongodb-cr>`
 
         - MongoDB challenge/response authentication.
 
-      * - MONGODB-X509
+      * - :ref:`MONGODB-X509 <security-auth-x509>`
 
         - MongoDB SSL certificate authentication.
 
-      * - PLAIN
+      * - :ref:`GSSAPI <security-auth-kerberos>` (Kerberos)
+
+        - External authentication using Kerberos. This mechanism is
+          available only in `MongoDB Enterprise
+          <http://www.mongodb.com/products/mongodb-enterprise>`_.
+
+      * - :ref:`PLAIN <security-auth-ldap>` (LDAP SASL)
 
         - External authentication using LDAP. You can also use ``PLAIN``
           for authenticating in-database users. ``PLAIN`` transmits
           passwords in plain text. This mechanism is available only in
           `MongoDB Enterprise
           <http://www.mongodb.com/products/mongodb-enterprise>`_.
 
-      * - GSSAPI
-
-        - External authentication using Kerberos. This mechanism is
-          available only in `MongoDB Enterprise
-          <http://www.mongodb.com/products/mongodb-enterprise>`_.
-
    .. todo:: Per DOCS-2940, combine this with similar info in
              /includes/options-conf
              /includes/options-shared