DOCSP-9407: Add MONGODB-AWS auth mechanism (#82)

* DOCSP-9407: Add MONGODB-AWS auth mechanism

Author: Chris Cho

source/code-snippets/authentication/aws.js

@@ -0,0 +1,32 @@
+// ignored first line
+const { MongoClient } = require("mongodb");
+
+// Replace the following with values for your environment.
+const accessKeyId = encodeURIComponent("<AWS_ACCESS_KEY_ID>");
+const secretAccessKey = encodeURIComponent("<AWS_SECRET_ACCESS_KEY>");
+const clusterUrl = "<MongoDB cluster url>";
+
+const authMechanism = "MONGODB-AWS";
+
+// Replace the following with your MongoDB deployment's connection string.
+const uri =
+  `mongodb+srv://${accessKeyId}:${secretAccessKey}@${clusterUrl}/?authMechanism=${authMechanism}`;
+
+// Create a new MongoClient
+const client = new MongoClient(uri);
+
+// Function to connect to the server
+async function run() {
+  try {
+    // Connect the client to the server
+    await client.connect();
+
+    // Establish and verify connection
+    await client.db("admin").command({ ping: 1 });
+    console.log("Connected successfully to server");
+  } finally {
+    // Ensures that the client will close when you finish/error
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/code-snippets/authentication/cr.js

@@ -1,16 +1,13 @@
 // ignored first line
 const { MongoClient } = require("mongodb");
-const fs = require("fs");
 
-// specify the placeholder values for your environment in the following lines
+// Replace the following with values for your environment.
 const username = encodeURIComponent("<username>");
 const password = encodeURIComponent("<password>");
 const clusterUrl = "<MongoDB cluster url>";
 
-
-// Replace the following with your MongoDB deployment's connection
-// string.
-const uri = 
+// Replace the following with your MongoDB deployment's connection string.
+const uri =
   `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}&tls=true&tlsCertificateKeyFile=${clientPEMFile}`;
 
 // Create a new MongoClient

source/code-snippets/authentication/default.js

@@ -1,16 +1,15 @@
 // ignored first line
 const { MongoClient } = require("mongodb");
 
-// specify the placeholder values for your environment in the following lines
+// Replace the following with values for your environment.
 const username = encodeURIComponent("<username>");
 const password = encodeURIComponent("<password>");
 const clusterUrl = "<MongoDB cluster url>";
 
 const authMechanism = "DEFAULT";
 
-// Replace the following with your MongoDB deployment's connection
-// string.
-const uri = 
+// Replace the following with your MongoDB deployment's connection string.
+const uri =
   `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
 
 // Create a new MongoClient

source/code-snippets/authentication/sha1.js

@@ -1,16 +1,15 @@
 // ignored first line
 const { MongoClient } = require("mongodb");
 
-// specify the placeholder values for your environment in the following lines
+// Replace the following with values for your environment.
 const username = encodeURIComponent("<username>");
 const password = encodeURIComponent("<password>");
 const clusterUrl = "<MongoDB cluster url>";
 
 const authMechanism = "SCRAM-SHA-1";
 
-// Replace the following with your MongoDB deployment's connection
-// string.
-const uri = 
+// Replace the following with your MongoDB deployment's connection string.
+const uri =
   `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
 
 // Create a new MongoClient

source/code-snippets/authentication/sha256.js

@@ -1,16 +1,15 @@
 // ignored first line
 const { MongoClient } = require("mongodb");
 
-// specify the placeholder values for your environment in the following lines
+// Replace the following with values for your environment.
 const username = encodeURIComponent("<username>");
 const password = encodeURIComponent("<password>");
 const clusterUrl = "<MongoDB cluster url>";
 
 const authMechanism = "SCRAM-SHA-256";
 
-// Replace the following with your MongoDB deployment's connection
-// string.
-const uri = 
+// Replace the following with your MongoDB deployment's connection string.
+const uri =
   `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
 
 // Create a new MongoClient

source/code-snippets/authentication/x509.js

@@ -1,17 +1,15 @@
 // ignored first line
 const { MongoClient } = require("mongodb");
-const fs = require("fs");
 
+// Replace the following with values for your environment.
 const username = encodeURIComponent("<client certificate distinguished name>");
 const clusterUrl = "<MongoDB cluster url>";
-const clientPEMFile = encodeURIComponent(
-  "<path to the client pem certificate file>",
-);
+const clientPEMFile = encodeURIComponent("<path to the client pem certificate file>");
+
 const authMechanism = "MONGODB-X509";
 
-// Replace the following with your MongoDB deployment's connection
-// string.
-const uri = 
+// Replace the following with your MongoDB deployment's connection string.
+const uri =
   `mongodb+srv://${username}@${clusterUrl}/?authMechanism=${authMechanism}&tls=true&tlsCertificateKeyFile=${clientPEMFile}`;
 
 // Create a new MongoClient

source/fundamentals/authentication/mechanisms.txt

@@ -125,6 +125,40 @@ in the following sample code.
    SCRAM </release-notes/3.0-scram/>`, any ``MONGODB-CR`` user
    authentication requests fail.
 
+
+``MONGODB-AWS``
+---------------
+
+.. note::
+   The MONGODB-AWS authentication mechanism is only available in MongoDB
+   versions 4.4 and later.
+
+The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
+Identity and Access Management (AWS IAM) credentials to authenticate your
+user.
+
+To connect to a MongoDB instance with ``MONGODB-AWS`` authentication
+enabled, specify the ``MONGODB-AWS`` authentication mechanism and pass
+your ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` credentials to the
+driver when you attempt to connect. If your AWS login requires a session
+token, you must include your ``AWS_SESSION_TOKEN`` as well.
+
+The driver checks the following sources for your credentials in order:
+
+1. Connection string
+2. Environment variables
+3. AWS ECS endpoint specified in ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``
+4. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks
+   <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`_.
+
+The following code shows an example of specifying the ``MONGODB-AWS``
+authentication mechanism and credentials in the connection string.
+
+.. literalinclude:: /code-snippets/authentication/aws.js
+   :language: javascript
+   :dedent: 4
+
+
 ``X.509``
 ---------