DOCSP-48377 Authentication Reorg

source/code-snippets/authentication/cr.js

@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
 // Replace the following with values for your environment.
 const username = encodeURIComponent("<db_username>");
 const password = encodeURIComponent("<db_password>");
-const clusterUrl = "<MongoDB cluster url>";
+const clusterUrl = "<cluster_url>";
 
 // Replace the following with your MongoDB deployment's connection string.
 const uri =

source/code-snippets/authentication/default.js

@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
 // Replace the following with values for your environment.
 const username = encodeURIComponent("<db_username>");
 const password = encodeURIComponent("<db_password>");
-const clusterUrl = "<MongoDB cluster url>";
+const clusterUrl = "<cluster_url>";
 
 const authMechanism = "DEFAULT";
 

source/code-snippets/authentication/sha1.js

@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
 // Replace the following with values for your environment.
 const username = encodeURIComponent("<db_username>");
 const password = encodeURIComponent("<db_password>");
-const clusterUrl = "<MongoDB cluster url>";
+const clusterUrl = "<cluster_url>";
 
 const authMechanism = "SCRAM-SHA-1";
 

source/code-snippets/authentication/sha256.js

@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
 // Replace the following with values for your environment.
 const username = encodeURIComponent("<db_username>");
 const password = encodeURIComponent("<db_password>");
-const clusterUrl = "<MongoDB cluster url>";
+const clusterUrl = "<cluster_url>";
 
 const authMechanism = "SCRAM-SHA-256";
 

source/connect.txt

@@ -57,5 +57,4 @@ Compatibility
 .. include:: /includes/fact-atlas-link.rst
 
 For information about authenticating to MongoDB,
-see :ref:`node-authentication-mechanisms` and
-:ref:`node-enterprise-authentication-mechanisms`.
+see the :ref:`Authentication Mechanisms <node-authentication-mechanisms>` section.

source/connect/connection-options.txt

@@ -52,7 +52,7 @@ string, see :manual:`Connection Strings </reference/connection-string/>` in the
      - Specifies the authentication mechanism method to use for connection to the
        server. If you do not specify a value, the driver uses the default mechanism,
        either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256`` depending on the server version. See
-       :ref:`authentication mechanism <node-authentication-mechanisms>` for available
+       the :ref:`Authentication <node-authentication-mechanisms>` section for available
        authentication mechanisms.
 
    * - **authMechanismProperties**

source/reference/release-notes.txt

@@ -155,7 +155,7 @@ The {+driver-short+} v6.11 release includes the following features:
      releases.
 
 - Adds OIDC authentication support for Kubernetes environments. To learn
-  more about this feature, see the :ref:`node-enterprise-auth-oidc`
+  more about this feature, see the :ref:`node-authentication-oidc`
   section of the Enterprise Authentication Mechanisms guide.
 
   To use OIDC to authenticate from a Kubernetes environment, set the
@@ -629,7 +629,7 @@ The {+driver-short+} v6.1 release includes the following features:
 
   To learn how to set region settings when using the ``MONGODB-AWS`` 
   authentication mechanism, see the :guilabel:`Web Identity Token` tab in the 
-  :ref:`MONGODB-AWS <mongodb-aws>` section of the Authentication Mechanisms guide. 
+  :ref:`MONGODB-AWS <node-authentication-aws>` Authentication Mechanism guide. 
 
 - Fixes a memory leak issue caused by recursive calls to the ``next()``
   method of the ``ChangeStream`` type.

source/security/authentication.txt

@@ -9,36 +9,62 @@ Authentication
 
 .. toctree::
 
-   Authentication </security/authentication/mechanisms>
-   Enterprise Authentication </security/authentication/enterprise-mechanisms>
+   SCRAM </security/authentication/scram>
+   X.509 </security/authentication/x509>
+   AWS IAM </security/authentication/aws-iam>
+   OIDC </security/authentication/oidc>
+   LDAP (PLAIN) </security/authentication/ldap>
+   Kerberos (GSSAPI) </security/authentication/kerberos>
 
 Overview
 --------
 
-These guides show you how to authenticate to a MongoDB instance using the
-Node.js driver.
-
-The :doc:`Authentication Mechanisms </security/authentication/mechanisms>` guide contains
-sample connection code using each authentication mechanism supported in the
-MongoDB Community Edition which includes:
-
-- ``DEFAULT``
-- ``SCRAM-SHA-256``
-- ``SCRAM-SHA-1``
-- ``MONGODB-CR``
-- ``MONGODB-AWS``
-- ``X.509``
-
-The :doc:`Enterprise Authentication Mechanisms
-</security/authentication/enterprise-mechanisms>` guide contains sample
-connection code using authentication mechanisms available only in MongoDB
-Enterprise Edition which includes:
-
-- ``Kerberos (GSSAPI/SSPI)``
-- ``LDAP (PLAIN)``
-- ``MONGODB-OIDC``
-
-.. note::
-   For instructions on MongoDB driver installation and deployment setup, see
-   our :guides:`Connect to MongoDB guide </server/drivers/>`. Select your
-   MongoDB deployment type and the Node.js client.
+In this guide, you can learn how to authenticate to MongoDB by using the
+**authentication mechanisms** available in {+mdb-server+}.
+Authentication mechanisms are processes by which the driver and server confirm
+the identity of a client to ensure security before connecting.
+
+.. tip:: Connecting to MongoDB
+
+   To learn how to establish a connection to your MongoDB deployment, see the
+   :ref:`node-connect` guide.
+
+MongoDB Edition Compatibility
+-----------------------------
+
+The following table lists the authentication mechanisms supported by MongoDB and
+the {+mdb-server+} editions that each mechanism is compatible with. Click the name of
+a mechanism to learn more about how to use it with your application.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Authentication Mechanism
+     - Atlas
+     - Enterprise Advanced
+     - Community
+   * - :ref:`<node-authentication-scram>`
+     - Yes
+     - Yes
+     - Yes
+   * - :ref:`<node-authentication-x509>`
+     - Yes
+     - Yes
+     - Yes
+   * - :ref:`<node-authentication-aws>`
+     - Yes
+     - No
+     - No
+   * - :ref:`OIDC (Workload Identity Federation) <node-authentication-oidc>`
+     - Yes
+     - Yes
+     - No
+   * - :ref:`<node-authentication-ldap>`
+     - Yes
+     - Yes
+     - No
+   * - :ref:`Kerberos (GSSAPI) <node-authentication-kerberos>`
+     - No
+     - Yes
+     - No

source/security/authentication/aws-iam.txt

@@ -0,0 +1,186 @@
+.. _node-authentication-aws:
+
+==================================
+AWS Identity and Access Management
+==================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 3
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: atlas, amazon web services, code example
+
+Overview
+--------
+
+The ``MONGODB-AWS`` authentication mechanism uses Amazon Web Services
+Identity and Access Management (AWS IAM) credentials to authenticate a user to MongoDB.
+You can use this mechanism only when authenticating to MongoDB Atlas.
+
+.. tip:: Configure Atlas for AWS IAM Authentication
+
+   To learn more about configuring MongoDB Atlas for AWS IAM authentication, see
+   :atlas:`Set Up Authentication with AWS IAM </security/aws-iam-authentication/>` in
+   the Atlas documentation.
+
+Specify MONGODB-AWS Authentication
+----------------------------------
+
+The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
+Identity and Access Management (AWS IAM) credentials to authenticate your
+user. If you do not already have the `AWS signature library
+<https://www.npmjs.com/package/aws4>`__, use the following
+``npm`` command to install it:
+
+.. code-block:: bash
+
+   npm install aws4
+
+To connect to a MongoDB instance with ``MONGODB-AWS`` authentication
+enabled, specify the ``MONGODB-AWS`` authentication mechanism.
+
+The driver checks for your credentials in the following sources in order:
+
+1. Connection string
+#. Environment variables
+#. Web identity token file
+#. AWS ECS endpoint specified in ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``
+#. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks
+   <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`_.
+
+.. important::
+
+   The driver only reads the credentials from the first method that it detects
+   in the order as given by the preceding list. For example, if you specify 
+   your AWS credentials in the connection string, the driver ignores any 
+   credentials that you specified in environment variables.
+
+.. tabs::
+
+   .. 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
+
+   .. tab:: Environment Variables
+      :tabid: environment variables
+
+      To authenticate to your MongoDB instance using AWS credentials stored in
+      environment variables, set the following variables by using
+      a shell:
+
+      .. code-block:: bash
+
+         export AWS_ACCESS_KEY_ID=<awsKeyId>
+         export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
+         export AWS_SESSION_TOKEN=<awsSessionToken>
+
+      .. note::
+
+         Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS
+         session token for that role.
+
+      After you've set the preceding environment variables, specify the ``MONGODB-AWS``
+      authentication mechanism in your connection string as shown in the following example:
+
+      .. literalinclude:: /code-snippets/authentication/aws-env-variable.js
+         :language: javascript
+
+   .. tab:: Web Identity Token File
+      :tabid: web-identity-token-file
+
+      You can use the OpenID Connect (OIDC) token obtained from a web identity
+      provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or
+      other services.
+
+      To authenticate with your OIDC token you must first install
+      `@aws-sdk/credential-providers
+      <https://www.npmjs.com/package/@aws-sdk/credential-providers>`__. You can
+      install this dependency using the following ``npm`` command:
+
+      .. code-block:: bash
+
+         npm install @aws-sdk/credential-providers
+
+      Next, create a file that contains your OIDC token. Then 
+      set the absolute path to this file in an environment variable by using
+      a shell as shown in the following example:
+
+      .. code-block:: bash
+
+         export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>
+
+      AWS recommends using regional AWS STS endpoints instead of global 
+      endpoints to reduce latency, build-in redundancy, and increase session token validity.
+      To set the AWS region, set `AWS_REGION <https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html>`__ 
+      and `AWS_STS_REGIONAL_ENDPOINTS <https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html>`__
+      as environment variables, as shown in the following example: 
+
+      .. code-block:: bash
+
+         export AWS_STS_REGIONAL_ENDPOINTS=regional // Enables regional endpoints
+         export AWS_REGION=us-east-1 // Sets your AWS region
+
+      If both these environment variables aren't set, the default region is 
+      ``us-east-1``. For a list of available AWS regions, see the
+      `Regional Endpoints <https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints>`__ 
+      section of the AWS Service Endpoints reference in the AWS documentation. 
+
+      .. warning:: Consult your SDK's Documentation for Setting an AWS Region
+
+         You cannot set your AWS region with environment variables for all SDKs,
+         as in the above example. See your SDK's specific documentation for 
+         configuring an AWS region. 
+
+      After you've set the preceding environment variables, specify the ``MONGODB-AWS``
+      authentication mechanism in your connection string as shown in the following example:
+
+      .. literalinclude:: /code-snippets/authentication/aws-env-variable.js
+         :language: javascript
+
+.. important:: Retrieval of AWS Credentials
+
+   Starting in MongoDB version 4.11, when you install the optional
+   ``aws-sdk/credential-providers`` dependency, the driver uses the AWS SDK
+   to retrieve credentials from the environment. As a result, if you
+   have a shared AWS credentials file or config file, the driver will
+   use those credentials by default.
+
+   You can override this behavior by performing one of the following
+   actions:
+
+   - Set ``AWS_SHARED_CREDENTIALS_FILE`` variable in your shell to point
+     to your credentials file.
+   - Set the equivalent environment variable in your application to point
+     to your credentials file.
+   - Create an AWS profile for your MongoDB credentials and set the
+     ``AWS_PROFILE`` environment variable to that profile name.
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed on this
+page, see the following API documentation:
+
+- `MongoClient <{+api+}/classes/MongoClient.html>`__