DOCSP-18964 AWS session token (#263)

* added info about AWS session token

Author: kyuan-mongodb

source/code-snippets/authentication/aws-env-variable.js

@@ -0,0 +1,27 @@
+const { MongoClient } = require("mongodb");
+
+// Remember to add your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY 
+// credentials to your environment variables.
+const clusterUrl = "<MongoDB cluster url>";
+const authMechanism = "MONGODB-AWS";
+
+let uri =
+  `mongodb+srv://${clusterUrl}/?authSource=%24external&authMechanism=${authMechanism}`;
+
+// Create a new MongoClient.
+const client = new MongoClient(uri);
+
+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 {
+    // Ensure that the client closes when it finishes/errors.
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/code-snippets/authentication/aws.js

@@ -8,11 +8,11 @@ const clusterUrl = "<MongoDB cluster url>";
 const authMechanism = "MONGODB-AWS";
 
 let uri =
-  `mongodb+srv://${accessKeyId}:${secretAccessKey}@${clusterUrl}/?authMechanism=${authMechanism}`;
-
+  `mongodb+srv://${accessKeyId}:${secretAccessKey}@${clusterUrl}/?authSource=%24external&authMechanism=${authMechanism}`;
+  
 // Uncomment the following lines if your AWS authentication setup requires a session token.
 // const sessionToken = encodeURIComponent("<AWS_SESSION_TOKEN>");
-// uri = uri.concat(`&authMechanismProperties=${sessionToken}`);
+// uri = uri.concat(`&authMechanismProperties=AWS_SESSION_TOKEN:${sessionToken}`);
 
 // Create a new MongoClient.
 const client = new MongoClient(uri);

source/fundamentals/authentication/mechanisms.txt

@@ -133,35 +133,67 @@ in the following sample code.
 
 The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
 Identity and Access Management (AWS IAM) credentials to authenticate your
-user.
+user. If you do not already have the `AWS signature library
+<https://www.npmjs.com/package/aws4>`__, install it using the following
+``npm`` command:
+
+.. code-block:: bash
+
+   npm install aws4
 
 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.
+enabled, specify the ``MONGODB-AWS`` authentication mechanism. 
 
-The driver checks the following sources for your credentials in order:
+The driver checks for your credentials in the following sources 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>`_.
 
-If you do not already have the `AWS signature library <https://www.npmjs.com/package/aws4>`__,
-install it using the following ``npm`` command:
+.. tabs::
 
-.. code-block:: console
+   .. tab:: Environment Variables
+      :tabid: environment variables
 
-   npm install aws4
+      To connect to your MongoDB instance with environment variables,
+      add your ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY``
+      credentials to your environment variables. If your AWS
+      login requires an ``AWS_SESSION_TOKEN``, add it to your
+      environment variables as well. 
 
-The following code shows an example of specifying the ``MONGODB-AWS``
-authentication mechanism and credentials in the connection string:
+      The following code shows an example of specifying the ``MONGODB-AWS``
+      authentication mechanism with environment variables:
 
-.. literalinclude:: /code-snippets/authentication/aws.js
-   :language: javascript
+      .. note::
+      
+         You don't need to specify these credentials in your connection URI
+         because the driver automatically retrieves them when you attempt
+         to connect.
+
+      .. literalinclude:: /code-snippets/authentication/aws-env-variable.js
+         :language: javascript 
+
+   .. tab:: Connection String
+      :tabid: connection string
+
+      To connect to your MongoDB instance with a connection string, 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, include your ``AWS_SESSION_TOKEN`` as well.
+
+      The following code shows an example of specifying the ``MONGODB-AWS``
+      authentication mechanism and credentials with a connection string:
+
+      .. important::
+         
+         Always **URI encode** the username and certificate file path using the
+         ``encodeURIComponent`` method to ensure they are correctly parsed.
 
+      .. literalinclude:: /code-snippets/authentication/aws.js
+         :language: javascript  
+   
 ``X.509``
 ---------