Skip to content

Commit b082ff9

Browse files
lindseymoorelindseymoore
committed
DOCSP-48377 Authentication Reorg (mongodb#1040)
* DOCSP-48377 Authentication Reorg * start building TOC * full draft * edits * edits * SA comments * SA update redirect * Edit table
1 parent 3e98a3e commit b082ff9

19 files changed

+750
-561
lines changed

‎config/redirects

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,5 @@ raw: ${prefix}/stable -> ${base}/current/
8383
[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/crud/update/embedded-arrays/
8484
[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/pkFactory/ -> ${base}/crud/pkFactory/
8585

86+
# Comprehensive Coverage Redirects
87+
[*-master]: ${prefix}/${version}/security/authentication/enterprise-mechanisms/ -> ${base}/security/authentication

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
const { MongoClient } = require("mongodb");
22

33
// Remember to specify your AWS credentials in environment variables.
4-
const clusterUrl = "<MongoDB deployment url>";
4+
const clusterUrl = "<cluster_url>";
55
const authMechanism = "MONGODB-AWS";
66

77
let uri =

‎source/code-snippets/authentication/aws.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
33
// Replace the following with values for your environment.
44
const accessKeyId = encodeURIComponent("<AWS_ACCESS_KEY_ID>");
55
const secretAccessKey = encodeURIComponent("<AWS_SECRET_ACCESS_KEY>");
6-
const clusterUrl = "<MongoDB cluster url>";
6+
const clusterUrl = "<cluster_url>";
77

88
const authMechanism = "MONGODB-AWS";
99

‎source/code-snippets/authentication/cr.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
33
// Replace the following with values for your environment.
44
const username = encodeURIComponent("<db_username>");
55
const password = encodeURIComponent("<db_password>");
6-
const clusterUrl = "<MongoDB cluster url>";
6+
const clusterUrl = "<cluster_url>";
77

88
// Replace the following with your MongoDB deployment's connection string.
99
const uri =

‎source/code-snippets/authentication/default.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
33
// Replace the following with values for your environment.
44
const username = encodeURIComponent("<db_username>");
55
const password = encodeURIComponent("<db_password>");
6-
const clusterUrl = "<MongoDB cluster url>";
6+
const clusterUrl = "<cluster_url>";
77

88
const authMechanism = "DEFAULT";
99

‎source/code-snippets/authentication/sha1.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
33
// Replace the following with values for your environment.
44
const username = encodeURIComponent("<db_username>");
55
const password = encodeURIComponent("<db_password>");
6-
const clusterUrl = "<MongoDB cluster url>";
6+
const clusterUrl = "<cluster_url>";
77

88
const authMechanism = "SCRAM-SHA-1";
99

‎source/code-snippets/authentication/sha256.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb");
33
// Replace the following with values for your environment.
44
const username = encodeURIComponent("<db_username>");
55
const password = encodeURIComponent("<db_password>");
6-
const clusterUrl = "<MongoDB cluster url>";
6+
const clusterUrl = "<cluster_url>";
77

88
const authMechanism = "SCRAM-SHA-256";
99

‎source/code-snippets/authentication/x509.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
const { MongoClient } = require("mongodb");
22

33
// Replace the following with values for your environment.
4-
const clusterUrl = "<MongoDB cluster url>";
5-
const clientPEMFile = encodeURIComponent("<path to the client pem certificate file>");
4+
const clusterUrl = "<cluster_url>";
5+
const clientPEMFile = encodeURIComponent("<pem_certificate_file_path>");
66

77
const authMechanism = "MONGODB-X509";
88

‎source/connect.txt

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,5 +57,4 @@ Compatibility
5757
.. include:: /includes/fact-atlas-link.rst
5858

5959
For information about authenticating to MongoDB,
60-
see :ref:`node-authentication-mechanisms` and
61-
:ref:`node-enterprise-authentication-mechanisms`.
60+
see the :ref:`Authentication Mechanisms <node-authentication-mechanisms>` section.

‎source/connect/connection-options.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ string, see :manual:`Connection Strings </reference/connection-string/>` in the
5353
- Specifies the authentication mechanism method to use for connection to the
5454
server. If you do not specify a value, the driver uses the default mechanism,
5555
either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256`` depending on the server version. See
56-
:ref:`authentication mechanism <node-authentication-mechanisms>` for available
56+
the :ref:`Authentication Mechanisms <node-authentication-mechanisms>` section for available
5757
authentication mechanisms.
5858

5959
* - **authMechanismProperties**

‎source/reference/release-notes.txt

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -209,8 +209,7 @@ The {+driver-short+} v6.11 release includes the following features:
209209
releases.
210210

211211
- Adds OIDC authentication support for Kubernetes environments. To learn
212-
more about this feature, see the :ref:`node-enterprise-auth-oidc`
213-
section of the Enterprise Authentication Mechanisms guide.
212+
more about this feature, see the :ref:`node-authentication-oidc` guide.
214213

215214
To use OIDC to authenticate from a Kubernetes environment, set the
216215
``authMechanismProperties`` connection option to ``ENVIRONMENT:k8s``
@@ -683,7 +682,7 @@ The {+driver-short+} v6.1 release includes the following features:
683682

684683
To learn how to set region settings when using the ``MONGODB-AWS``
685684
authentication mechanism, see the :guilabel:`Web Identity Token` tab in the
686-
:ref:`MONGODB-AWS <mongodb-aws>` section of the Authentication Mechanisms guide.
685+
:ref:`AWS IAM Authentication Mechanism <node-authentication-aws>` guide.
687686

688687
- Fixes a memory leak issue caused by recursive calls to the ``next()``
689688
method of the ``ChangeStream`` type.

‎source/security/authentication.txt

Lines changed: 58 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
.. _node-authentication-mechanisms:
22
.. _node-authentication:
33

4-
==============
5-
Authentication
6-
==============
4+
=========================
5+
Authentication Mechanisms
6+
=========================
77

88
.. meta::
99
:description: Authenticate using the MongoDB Node.js Driver with various supported authentication mechanisms.
@@ -12,36 +12,62 @@ Authentication
1212

1313
.. toctree::
1414

15-
Authentication </security/authentication/mechanisms>
16-
Enterprise Authentication </security/authentication/enterprise-mechanisms>
15+
SCRAM </security/authentication/scram>
16+
X.509 </security/authentication/x509>
17+
AWS IAM </security/authentication/aws-iam>
18+
OIDC </security/authentication/oidc>
19+
LDAP (PLAIN) </security/authentication/ldap>
20+
Kerberos (GSSAPI) </security/authentication/kerberos>
1721

1822
Overview
1923
--------
2024

21-
These guides show you how to authenticate to a MongoDB instance using the
22-
Node.js driver.
23-
24-
The :doc:`Authentication Mechanisms </security/authentication/mechanisms>` guide contains
25-
sample connection code using each authentication mechanism supported in the
26-
MongoDB Community Edition which includes:
27-
28-
- ``DEFAULT``
29-
- ``SCRAM-SHA-256``
30-
- ``SCRAM-SHA-1``
31-
- ``MONGODB-CR``
32-
- ``MONGODB-AWS``
33-
- ``X.509``
34-
35-
The :doc:`Enterprise Authentication Mechanisms
36-
</security/authentication/enterprise-mechanisms>` guide contains sample
37-
connection code using authentication mechanisms available only in MongoDB
38-
Enterprise Edition which includes:
39-
40-
- ``Kerberos (GSSAPI/SSPI)``
41-
- ``LDAP (PLAIN)``
42-
- ``MONGODB-OIDC``
43-
44-
.. note::
45-
For instructions on MongoDB driver installation and deployment setup, see
46-
our :guides:`Connect to MongoDB guide </server/drivers/>`. Select your
47-
MongoDB deployment type and the Node.js client.
25+
In this guide, you can learn how to authenticate to MongoDB by using the
26+
**authentication mechanisms** available in {+mdb-server+}.
27+
Authentication mechanisms are processes by which the driver and server confirm
28+
the identity of a client to ensure security before connecting.
29+
30+
.. tip:: Connecting to MongoDB
31+
32+
To learn how to establish a connection to your MongoDB deployment, see the
33+
:ref:`node-connect` guide.
34+
35+
MongoDB Edition Compatibility
36+
-----------------------------
37+
38+
The following table lists the authentication mechanisms supported by MongoDB and
39+
the {+mdb-server+} editions that each mechanism is compatible with. Click the name of
40+
a mechanism to learn more about how to use it with your application.
41+
42+
.. list-table::
43+
:header-rows: 1
44+
:stub-columns: 1
45+
46+
* - Authentication Mechanism
47+
- Atlas
48+
- Enterprise Advanced
49+
- Community
50+
* - :ref:`<node-authentication-scram>`
51+
- Yes
52+
- Yes
53+
- Yes
54+
* - :ref:`<node-authentication-x509>`
55+
- Yes
56+
- Yes
57+
- Yes
58+
* - :ref:`<node-authentication-aws>`
59+
- Yes
60+
- No
61+
- No
62+
* - :ref:`<node-authentication-oidc>`
63+
- Yes
64+
- Yes
65+
- No
66+
* - :ref:`<node-authentication-ldap>`
67+
- Yes
68+
- Yes
69+
- No
70+
* - :ref:`<node-authentication-kerberos>`
71+
- No
72+
- Yes
73+
- No

‎source/security/authentication/aws-iam.txt

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
.. _node-authentication-aws:
2+
3+
================================
4+
AWS IAM Authentication Mechanism
5+
================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 3
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: atlas, amazon web services, code example
19+
20+
Overview
21+
--------
22+
23+
The ``MONGODB-AWS`` authentication mechanism uses Amazon Web Services
24+
Identity and Access Management (AWS IAM) credentials to authenticate a user to MongoDB.
25+
You can use this mechanism only when authenticating to MongoDB Atlas.
26+
27+
.. tip:: Configure Atlas for AWS IAM Authentication
28+
29+
To learn more about configuring MongoDB Atlas for AWS IAM authentication, see
30+
:atlas:`Set Up Authentication with AWS IAM </security/aws-iam-authentication/>` in
31+
the Atlas documentation.
32+
33+
Specify MONGODB-AWS Authentication
34+
----------------------------------
35+
36+
The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
37+
Identity and Access Management (AWS IAM) credentials to authenticate your
38+
user. If you do not already have the `AWS signature library
39+
<https://www.npmjs.com/package/aws4>`__, use the following
40+
``npm`` command to install it:
41+
42+
.. code-block:: bash
43+
44+
npm install aws4
45+
46+
To connect to a MongoDB instance with ``MONGODB-AWS`` authentication
47+
enabled, specify the ``MONGODB-AWS`` authentication mechanism.
48+
49+
The driver checks for your credentials in the following sources in order:
50+
51+
1. Connection string
52+
#. Environment variables
53+
#. Web identity token file
54+
#. AWS ECS endpoint specified in ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``
55+
#. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks
56+
<https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`_.
57+
58+
.. important::
59+
60+
The driver only reads the credentials from the first method that it detects
61+
in the order as given by the preceding list. For example, if you specify
62+
your AWS credentials in the connection string, the driver ignores any
63+
credentials that you specified in environment variables.
64+
65+
.. tabs::
66+
67+
.. tab:: Connection String
68+
:tabid: connection string
69+
70+
To connect to your MongoDB instance with a connection string, pass
71+
your ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY``
72+
credentials to the driver when you attempt to connect. If your AWS
73+
login requires a session token, include your ``AWS_SESSION_TOKEN`` as well.
74+
75+
The following code shows an example of specifying the ``MONGODB-AWS``
76+
authentication mechanism and credentials with a connection string:
77+
78+
.. important::
79+
80+
Always **URI encode** the username and certificate file path using the
81+
``encodeURIComponent`` method to ensure they are correctly parsed.
82+
83+
.. literalinclude:: /code-snippets/authentication/aws.js
84+
:language: javascript
85+
86+
.. tab:: Environment Variables
87+
:tabid: environment variables
88+
89+
To authenticate to your MongoDB instance using AWS credentials stored in
90+
environment variables, set the following variables by using
91+
a shell:
92+
93+
.. code-block:: bash
94+
95+
export AWS_ACCESS_KEY_ID=<awsKeyId>
96+
export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
97+
export AWS_SESSION_TOKEN=<awsSessionToken>
98+
99+
.. note::
100+
101+
Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS
102+
session token for that role.
103+
104+
After you've set the preceding environment variables, specify the ``MONGODB-AWS``
105+
authentication mechanism in your connection string as shown in the following example:
106+
107+
.. literalinclude:: /code-snippets/authentication/aws-env-variable.js
108+
:language: javascript
109+
110+
.. tab:: Web Identity Token File
111+
:tabid: web-identity-token-file
112+
113+
You can use the OpenID Connect (OIDC) token obtained from a web identity
114+
provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or
115+
other services.
116+
117+
To authenticate with your OIDC token you must first install
118+
`@aws-sdk/credential-providers
119+
<https://www.npmjs.com/package/@aws-sdk/credential-providers>`__. You can
120+
install this dependency using the following ``npm`` command:
121+
122+
.. code-block:: bash
123+
124+
npm install @aws-sdk/credential-providers
125+
126+
Next, create a file that contains your OIDC token. Then
127+
set the absolute path to this file in an environment variable by using
128+
a shell as shown in the following example:
129+
130+
.. code-block:: bash
131+
132+
export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>
133+
134+
AWS recommends using regional AWS STS endpoints instead of global
135+
endpoints to reduce latency, build-in redundancy, and increase session token validity.
136+
To set the AWS region, set `AWS_REGION <https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html>`__
137+
and `AWS_STS_REGIONAL_ENDPOINTS <https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html>`__
138+
as environment variables, as shown in the following example:
139+
140+
.. code-block:: bash
141+
142+
export AWS_STS_REGIONAL_ENDPOINTS=regional // Enables regional endpoints
143+
export AWS_REGION=us-east-1 // Sets your AWS region
144+
145+
If both these environment variables aren't set, the default region is
146+
``us-east-1``. For a list of available AWS regions, see the
147+
`Regional Endpoints <https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints>`__
148+
section of the AWS Service Endpoints reference in the AWS documentation.
149+
150+
.. warning:: Consult your SDK's Documentation for Setting an AWS Region
151+
152+
You cannot set your AWS region with environment variables for all SDKs,
153+
as in the above example. See your SDK's specific documentation for
154+
configuring an AWS region.
155+
156+
After you've set the preceding environment variables, specify the ``MONGODB-AWS``
157+
authentication mechanism in your connection string as shown in the following example:
158+
159+
.. literalinclude:: /code-snippets/authentication/aws-env-variable.js
160+
:language: javascript
161+
162+
.. important:: Retrieval of AWS Credentials
163+
164+
Starting in MongoDB version 4.11, when you install the optional
165+
``aws-sdk/credential-providers`` dependency, the driver uses the AWS SDK
166+
to retrieve credentials from the environment. As a result, if you
167+
have a shared AWS credentials file or config file, the driver will
168+
use those credentials by default.
169+
170+
You can override this behavior by performing one of the following
171+
actions:
172+
173+
- Set ``AWS_SHARED_CREDENTIALS_FILE`` variable in your shell to point
174+
to your credentials file.
175+
- Set the equivalent environment variable in your application to point
176+
to your credentials file.
177+
- Create an AWS profile for your MongoDB credentials and set the
178+
``AWS_PROFILE`` environment variable to that profile name.
179+
180+
API Documentation
181+
-----------------
182+
183+
To learn more about any of the methods or types discussed on this
184+
page, see the following API documentation:
185+
186+
- `MongoClient <{+api+}/classes/MongoClient.html>`__

0 commit comments

Comments
 (0)