Skip to content

Commit 5dd7d2b

Browse files
kay-kimkay-kim
committed
DOCSP-1834, DOCSP-1714: scram part 1 + mongodbcr data and scram
1 parent 6852a4d commit 5dd7d2b

14 files changed

+218
-200
lines changed

‎config/redirects

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1352,6 +1352,7 @@ raw: /master/release-notes/3.0-general-improvements -> ${base}/release-notes/3.0
13521352
[v3.6-*]: /${version}/reference/method/sh.getBalancerLockDetails -> ${base}/${version}/reference/method/js-sharding
13531353
[*-v3.2]: /${version}/reference/method/sh.disableAutoSplit -> ${base}/${version}/reference/program/mongos
13541354
[*-v3.2]: /${version}/reference/method/sh.enableAutoSplit -> ${base}/${version}/reference/program/mongos
1355+
[*-v3.0]: /${version}/core/security-scram-sha-1 -> ${base}/${version}/core/security-scram
13551356

13561357
[v3.6-*]: /${version}/core/data-modeling-json-schema -> ${base}/${version}/core/schema-validation
13571358
[v3.6-*]: /${version}/core/distributed-write-operations -> ${base}/${version}/core/distributed-queries

‎source/core/authentication-mechanisms.txt

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,11 @@ Authentication Mechanisms
1414

1515
MongoDB supports the following authentication mechanisms:
1616

17-
- :doc:`SCRAM-SHA-1 </core/security-scram-sha-1>`
17+
- :doc:`/core/security-scram` (Default authentication mechanism)
1818

1919
- :doc:`MongoDB Challenge and Response (MONGODB-CR)
2020
</core/security-mongodb-cr>`
2121

22-
.. versionchanged:: 3.0
23-
24-
New challenge-response users created in 3.0 will use
25-
``SCRAM-SHA-1``. If using 2.6 user data, MongoDB 3.0 will continue
26-
to use ``MONGODB-CR``.
27-
2822
- :doc:`x.509 Certificate Authentication </core/security-x.509>`.
2923

3024
In addition, MongoDB Enterprise also provides supports for additional
@@ -38,9 +32,12 @@ Default Authentication Mechanism
3832

3933
.. versionchanged:: 3.0
4034

41-
MongoDB uses the :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>` as the default
42-
challenge and response authentication mechanism. Previous versions used :doc:`MONGODB-CR
43-
</core/security-mongodb-cr>` as the default.
35+
As of MongoDB 3.0, :ref:`Salted Challenge Response Authentication
36+
Mechanism (SCRAM) <authentication-scram-sha-1>` is the default
37+
authentication mechanism for MongoDB.
38+
39+
Previous versions used :doc:`MONGODB-CR </core/security-mongodb-cr>` as
40+
the default.
4441

4542
Specify Authentication Mechanism
4643
--------------------------------
@@ -58,6 +55,6 @@ authentication mechanism from the command line.
5855
.. toctree::
5956
:titlesonly:
6057

61-
/core/security-scram-sha-1
58+
/core/security-scram
6259
/core/security-mongodb-cr
6360
/core/security-x.509

‎source/core/authentication.txt

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,16 +39,11 @@ existing authentication system.
3939

4040
MongoDB supports multiple authentication mechanisms:
4141

42-
- :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>`
42+
- :ref:`authentication-scram` (Default)
4343

4444
- :ref:`MongoDB Challenge and Response (MONGODB-CR)
4545
<authentication-mongodb-cr>`
4646

47-
.. versionchanged:: 3.0
48-
New challenge-response users created in 3.0 will use
49-
``SCRAM-SHA-1``. If using 2.6 user data, MongoDB 3.0 will continue
50-
to use ``MONGODB-CR``.
51-
5247
- :ref:`x.509 Certificate Authentication <security-auth-x509>`.
5348

5449
In addition to supporting the aforementioned mechanisms, MongoDB Enterprise

‎source/core/security-internal-authentication.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ certificates.
2828
Keyfiles
2929
--------
3030

31-
Keyfiles use :doc:`/core/security-scram-sha-1` challenge and response
31+
Keyfiles use :doc:`/core/security-scram` challenge and response
3232
authentication mechanism. The contents of the keyfiles serve as the
3333
shared password for the members. A key's length must be between 6 and
3434
1024 characters and may only contain characters in the base64 set.

‎source/core/security-mongodb-cr.txt

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,13 @@ the user's :data:`name <admin.system.users.user>`, :data:`password
2020
user was created, and the user's database and the user's name together serve to
2121
identify the user.
2222

23-
``MONGODB-CR`` and ``SCRAM-SHA-1``
24-
----------------------------------
23+
``MONGODB-CR`` User Credentials and SCRAM
24+
-----------------------------------------
2525

2626
.. versionchanged:: 3.0
2727

28-
MongoDB no longer defaults to ``MONGODB-CR`` and instead uses ``SCRAM-SHA-1`` as the
29-
default authentication mechanism.
28+
MongoDB no longer defaults to ``MONGODB-CR`` and instead uses
29+
:ref:`Salted Challenge Response Authentication Mechanism (SCRAM)
30+
<authentication-scram-sha-1>` as the default authentication mechanism.
3031

31-
.. include:: /includes/fact-scram-sha-1-protocol.rst
32+
.. include:: /includes/fact-mongodb-cr-users.rst

‎source/core/security-scram-sha-1.txt

Lines changed: 0 additions & 88 deletions
This file was deleted.

‎source/core/security-scram.txt

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
.. _authentication-scram:
2+
3+
.. _authentication-scram-sha-1:
4+
5+
=====
6+
SCRAM
7+
=====
8+
9+
.. default-domain:: mongodb
10+
11+
.. contents:: On this page
12+
:local:
13+
:backlinks: none
14+
:depth: 1
15+
:class: singlecol
16+
17+
.. versionadded:: 3.0
18+
19+
Salted Challenge Response Authentication Mechanism (SCRAM) is the
20+
default authentication mechanism for MongoDB. SCRAM is based on the
21+
IETF `RFC 5802 <https://tools.ietf.org/html/rfc5802>`_ standard that
22+
defines best practices for implementation of challenge-response
23+
mechanisms for authenticating users with passwords.
24+
25+
Using SCRAM, MongoDB verifies the supplied user credentials against the
26+
user's :data:`name <admin.system.users.user>`, :data:`password
27+
<admin.system.users.credentials>` and :data:`authentication database
28+
<admin.system.users.db>`. The authentication database is the database
29+
where the user was created, and together with the user's name, serves
30+
to identify the user.
31+
32+
MongoDB's implementation of SCRAM uses the SHA-1 hashing function.
33+
34+
.. _scram-advantages:
35+
36+
SCRAM Advantages
37+
----------------
38+
39+
MongoDB's implementation of SCRAM represents an improvement in security
40+
over the MongoDB challenge response authentication mechanism, providing:
41+
42+
- A tunable work factor (``iterationCount``),
43+
- Per-user random salts rather than server-wide salts,
44+
- A cryptographically stronger hash function (``SHA-1`` rather than ``MD5``),
45+
and
46+
- Authentication of the server to the client as well as the client to the
47+
server.
48+
49+
MongoDB-CR User Credentials and SCRAM
50+
-------------------------------------
51+
52+
.. include:: /includes/fact-mongodb-cr-users.rst
53+
54+
Driver Support
55+
--------------
56+
57+
To use the SCRAM, you must upgrade your driver if your current driver
58+
version does not support ``SCRAM``.
59+
60+
The minimum driver versions that support ``SCRAM`` are:
61+
62+
.. |driver-compatibility-heading| replace:: Version
63+
64+
.. include:: /includes/list-table-3.0-driver-compatibility.rst
65+
66+
Additional Information
67+
----------------------
68+
69+
- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM
70+
Explained (Part 1)
71+
<https://www.mongodb.com/blog/post/improved-password-based-authentication-mong
72+
odb-30-scram-explained-part-1?jmp=docs>`_
73+
74+
- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM
75+
Explained (Part 2)
76+
<https://www.mongodb.com/blog/post/improved-password-based-authentication-mong
77+
odb-30-scram-explained-part-2?jmp=docs>`_

‎source/includes/fact-mongodb-cr-users-drivers.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
For older versions of drivers that do not support MongoDB 3.0+
2+
features, you will continue to use MONGODB-CR.
3+
4+
For drivers that support MongoDB 3.0+ features (see
5+
:ref:`compatibility-driver-versions`), the default behavior is to
6+
temporarily convert the credentials to SCRAM during authentication;
7+
this temporary conversion does not affect how the credentials are
8+
stored. If you choose to use ``MONGODB-CR``, you must explicitly
9+
specify ``MONGODB-CR`` as the authentication mechanism.

‎source/includes/fact-mongodb-cr-users.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
After you upgrade a deployment that already has MongoDB Challenge
2+
and Response (``MONGODB-CR``) user credentials, if you have not
3+
upgraded the authentication schema, you can continue to use
4+
``MONGODB-CR``:
5+
6+
- For older versions of drivers that do not support MongoDB 3.0+
7+
features, you will continue to use ``MONGODB-CR``.
8+
9+
- For drivers that support MongoDB 3.0+ features (see
10+
:ref:`compatibility-driver-versions`), you must explicitly specify
11+
``MONGODB-CR`` as the authentication mechanism. Otherwise, the
12+
credentials are temporarily converted to use SCRAM during
13+
authentication; this temporary conversion does not affect how the
14+
credentials are stored.
15+
16+
To upgrade the authentication schema model to SCRAM, see
17+
:doc:`/release-notes/3.0-scram`.
18+
19+
.. warning::
20+
21+
.. include:: /includes/fact-upgrade-scram-irreversible.rst

‎source/includes/fact-scram-sha-1-protocol.rst

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎source/includes/fact-upgrade-scram-irreversible.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
The procedure to upgrade to ``SCRAM-SHA-1`` **discards** the
2-
``MONGODB-CR`` credentials used by 2.6. As such, the procedure is
3-
**irreversible**, short of restoring from backups.
1+
The procedure to upgrade to SCRAM **discards** the ``MONGODB-CR``
2+
credentials used by 2.6. As such, the procedure is **irreversible**,
3+
short of restoring from backups.
44

55
The procedure also disables ``MONGODB-CR`` as an authentication
66
mechanism.

‎source/includes/internal-authentication-tutorials-access-control-consideration.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
This tutorial covers creating the minimum number of administrative
22
users on the ``admin`` database *only*. For the user authentication,
3-
the tutorial uses the default :doc:`/core/security-scram-sha-1`
3+
the tutorial uses the default :doc:`/core/security-scram`
44
authentication mechanism. Challenge-response security mechanisms are
55
best suited for testing or development environments. For production
66
environments, we recommend using :doc:`x.509

0 commit comments

Comments
 (0)