docsp-27247 - aws auth (#83)

* first draft

* cc feedback

* dl feedback

Author: mongoKart

source/fundamentals/authentication.txt

@@ -23,6 +23,7 @@ of {+mongo-community+}:
 
 - :ref:`csharp-scram-sha-256`
 - :ref:`csharp-scram-sha-1`
+- :ref:`csharp-mongodb-aws`
 - :ref:`csharp-x509`
 
 To authenticate using ``GSSAPI/Kerberos`` or ``LDAP``, see the
@@ -46,14 +47,14 @@ MongoDB using either of the following methods:
 Mechanisms
 ----------
 
-The following examples specify authentication mechanisms using the following
+The following examples contain code examples that use the following
 placeholders:
 
-- ``<username>``: Your MongoDB username.
-- ``<password>``: Your MongoDB user's password.
-- ``<hostname>``: The network address of your MongoDB server, accessible by your client.
-- ``<port>``: The port number of your MongoDB server.
-- ``<authenticationDb>``: The MongoDB database that contains your user's authentication
+- ``<username>`` - MongoDB username.
+- ``<password>`` - MongoDB user's password.
+- ``<hostname>`` - network address of the MongoDB server, accessible by your client.
+- ``<port>`` - port number of the MongoDB server.
+- ``<authenticationDb>`` - MongoDB database that contains the user's authentication
   data. If you omit this parameter, the driver uses the default value ``admin``.
 
 .. _csharp-authentication-default:
@@ -142,6 +143,175 @@ string as follow:
 
    To learn more on specifying the default mechanism, see :ref:`csharp-authentication-default`.
 
+.. _csharp-mongodb-aws:
+
+MONGODB-AWS
+~~~~~~~~~~~
+
+.. note::
+
+   The ``MONGODB-AWS`` authentication mechanism is available only for
+   MongoDB deployments on MongoDB Atlas.
+
+The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
+Identity and Access Management (AWS IAM) credentials to authenticate your
+user. You can either specify your credentials explicitly
+or instruct the driver to retrieve them automatically from an external source.
+
+The following sections contain code examples that use the following placeholders:
+
+- ``<awsKeyId>`` - value of the AWS access key ID
+- ``<awsSecretKey>`` - value of the AWS secret access key
+- ``<awsSessionToken>`` - value of the AWS session token
+
+.. tip::
+
+   To learn more about configuring MongoDB Atlas with AWS IAM, see the
+   :atlas:`Set Up Passwordless Authentication with AWS IAM Roles </security/passwordless-authentication/#set-up-passwordless-authentication-with-aws-iam-roles>` guide.
+
+Specify Your AWS IAM Credentials
+++++++++++++++++++++++++++++++++
+
+You can supply your AWS IAM credentials on a ``MongoClientSettings`` object either by 
+using a ``MongoCredential`` object or as part of the connection string. Select the 
+:guilabel:`Connection String` or :guilabel:`MongoCredential` tab to
+see the corresponding syntax for specifying your credentials: 
+
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: mongodb-aws-mongoclientsettings-connection-string
+      
+      .. code-block:: csharp
+
+         var connectionString = "mongodb+srv://<awsKeyId>:<awsSecretKey>@<hostname>[:<port>]?authSource=$external&authMechanism=MONGODB-AWS";
+         var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
+         var client = new MongoClient(mongoClientSettings);
+
+      If you're using an AWS session token, include the ``authMechanismProperties``
+      parameter in the connection string as shown below:
+
+      .. code-block:: csharp
+
+         var connectionString = "mongodb+srv://<awsKeyId>:<awsSecretKey>@<hostname>[:<port>]?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>";
+
+   .. tab:: MongoCredential
+      :tabid: mongodb-aws-mongoclientsettings-mongo-credential
+
+      .. code-block:: csharp
+
+         var mongoClientSettings = MongoClientSettings.FromConnectionString("mongodb+srv://<hostname>[:<port>]");
+         mongoClientSettings.Credential = new MongoCredential("MONGODB-AWS", new MongoExternalIdentity("<awsKeyId>"), new PasswordEvidence("<awsSecretKey>"));
+         var client = new MongoClient(mongoClientSettings);
+
+      If you're using an AWS session token, call the ``WithMechanismProperty()`` 
+      method on your ``MongoCredential`` object as shown below:
+
+      .. code-block:: csharp
+
+         mongoClientSettings.Credential = new MongoCredential("MONGODB-AWS", new MongoExternalIdentity("<awsKeyId>"), new PasswordEvidence("<awsSecretKey>"))
+             .WithMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>");
+
+Retrieve Credentials Automatically
+++++++++++++++++++++++++++++++++++
+
+Instead of specifying your AWS IAM credentials in ``MongoClientSettings``, you can 
+instruct the {+driver-short+} to use the AWS SDK to automatically retrieve your 
+credentials from an external source. To instruct the driver to
+retrieve your credentials, perform the following actions:
+
+- Specify ``MONGODB-AWS`` as the authentication mechanism
+- Specify that the authentication source is external to MongoDB
+- Set your credentials in the appropriate location 
+
+You can specify the authentication mechanism and source either
+by using a ``MongoCredential`` object or as part of the connection string. Select the 
+:guilabel:`Connection String` or :guilabel:`MongoCredential` tab to
+see the corresponding syntax for specifying the ``MONGODB-AWS`` authentication mechanism
+and external authentication source:
+
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: mongodb-aws-automatic-connection-string
+      
+      .. code-block:: csharp
+
+         var connectionString = "mongodb+srv://<hostname>[:<port>]?authMechanism=MONGODB-AWS&authSource=$external";
+         var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
+         var client = new MongoClient(mongoClientSettings);
+
+   .. tab:: MongoCredential
+      :tabid: mongodb-aws-automatic-mongo-credential
+
+      .. code-block:: csharp
+
+         var mongoClientSettings = MongoClientSettings.FromConnectionString("mongodb+srv://<hostname>[:<port>]");
+         mongoClientSettings.Credential = new MongoCredential("MONGODB-AWS", new MongoExternalAwsIdentity(), new ExternalEvidence());
+         var client = new MongoClient(mongoClientSettings);
+   
+After you specify the authentication mechanism and source, you must set
+your credentials in the location appropriate to the credential type. The {+driver-short+} 
+checks for credentials in the following locations in the order listed here:
+
+- Web identity provider
+- Shared AWS credentials file
+- Environment variables
+- ECS container credentials
+- EC2 container credentials
+
+You can use an OpenID Connect (OIDC)-compatible **web identity provider** to authenticate
+to Amazon Elastic Kubernetes Service (EKS) or other services.
+To use a web identity provider, create a file that contains your
+OIDC token, then set the absolute path to this file in an environment variable by using 
+``bash`` or a similar shell as shown in the following example:
+
+.. code-block:: bash
+
+   export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>
+
+To authenticate by using a profile in a **shared AWS credentials file**, you can use a text
+editor, the AWS SDK for .NET, or the AWS CLI to create the appropriate credential file.
+
+To retrieve credentials directly from **environment variables**, set the following 
+environment variables by using ``bash`` or a similar 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.
+
+To authenticate by using **ECS container credentials**, set the URI of your ECS 
+endpoint in an environment variable by using ``bash`` or a similar shell.
+Select the :guilabel:`Full ECS URI` or :guilabel:`Relative ECS URI` tab to
+see the syntax for specifying the corresponding environment variable:
+
+.. tabs::
+
+   .. tab:: Full ECS URI
+      :tabid: mongodb-aws-full-ecs-uri
+      
+      .. code-block:: bash
+
+         export AWS_CONTAINER_CREDENTIALS_FULL_URI=<full ECS endpoint>
+
+   .. tab:: Relative ECS URI
+      :tabid: mongodb-aws-relative-ecs-uri
+
+      .. code-block:: bash
+
+         export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<relative ECS endpoint>
+
+To authenticate by using **EC2 container credentials**, make sure none of the
+environment variables mentioned earlier are set. The driver obtains the
+credentials from the default IPv4 EC2 instance metadata endpoint.   
+
 .. _csharp-x509:
 
 X.509