Skip to content

Commit 487d205

Browse files
rustagirrustagir
authored
DOCSP-30529: auth fundamentals (#26)
1 parent d6f9027 commit 487d205

File tree

4 files changed

+420
-1
lines changed

4 files changed

+420
-1
lines changed

‎source/fundamentals.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Fundamentals
1010

1111
/fundamentals/connections
1212
/fundamentals/stable-api
13+
/fundamentals/authentication
1314
/fundamentals/crud
1415
/fundamentals/database-collection
1516
/fundamentals/aggregation
@@ -19,7 +20,6 @@ Fundamentals
1920
..
2021
Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
2122
/fundamentals/context
22-
/fundamentals/auth
2323
/fundamentals/enterprise-auth
2424
/fundamentals/bson
2525
/fundamentals/indexes

‎source/fundamentals/authentication.txt

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
.. _rust-authentication:
2+
3+
=========================
4+
Authentication Mechanisms
5+
=========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: nones
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to use the **authentication
17+
mechanisms** available in the MongoDB Community Edition. When you connect
18+
to MongoDB, you can use an authentication mechanism to establish trust
19+
between the driver and the server.
20+
21+
.. tip::
22+
23+
.. TODO To learn how to authenticate to MongoDB by using ``GSSAPI/Kerberos`` or
24+
.. ``LDAP``, see the guide on :ref:`rust-enterprise-auth`.
25+
26+
To learn more about connecting to a MongoDB deployment, see the
27+
:ref:`rust-connect-to-mongodb`.
28+
29+
This guide describes the following authentication mechanisms:
30+
31+
- :ref:`SCRAM-Based Mechanisms <rust-auth-scram-mechanisms>`
32+
- :ref:`MONGODB-AWS Mechanism <rust-auth-aws>`
33+
- :ref:`MONGODB-X509 Mechanism <rust-auth-x509>`
34+
35+
To select a specific authentication mechanism, you can specify the
36+
mechanism, your credentials, and other necessary information
37+
in the options of your connection string or in a ``Credential`` struct.
38+
39+
In this guide, the examples demonstrate how to configure
40+
authentication in a ``Credential`` struct. To learn more about the
41+
connection string options for authentication, see the
42+
:manual:`Authentication
43+
Options </reference/connection-string/#authentication-options>` section
44+
of the Connection String URI Format guide in the Server manual.
45+
46+
.. _rust-auth-scram-mechanisms:
47+
48+
SCRAM-Based Mechanisms
49+
----------------------
50+
51+
Salted challenge response authentication mechanism (SCRAM) refers to a
52+
group of authentication mechanisms that use a username and
53+
password to authenticate to a server.
54+
55+
MongoDB supports the following SCRAM-based authentication mechanisms:
56+
57+
- :ref:`SCRAM-SHA-256 <rust-auth-scramsha256>`: an authentication mechanism that
58+
uses your username and password, encrypted with the ``SHA-256``
59+
algorithm
60+
- :ref:`SCRAM-SHA-1 <rust-auth-scramsha1>`: an authentication mechanism that
61+
uses your username and password, encrypted with the ``SHA-1``
62+
algorithm
63+
64+
.. important:: Default Authentication Mechanism
65+
66+
If you do not specify an authentication mechanism, the server
67+
attempts to validate credentials by using the default authentication
68+
mechanism, a SCRAM-based mechanism that varies depending on the
69+
version of the server that you are connecting to.
70+
71+
The ``SCRAM-SHA-256`` mechanism is the default authentication
72+
mechanism for MongoDB Server versions 4.0 and later.
73+
74+
To use the default authentication mechanism, omit only the
75+
``mechanism`` field when you instantiate your ``Credential`` struct.
76+
This example uses the following placeholders:
77+
78+
- ``username``: Your username
79+
- ``password``: Your password
80+
- ``db``: The authentication database associated with the user
81+
82+
.. literalinclude:: /includes/fundamentals/code-snippets/auth.rs
83+
:language: rust
84+
:dedent:
85+
:start-after: start-default
86+
:end-before: end-default
87+
88+
.. _rust-auth-scramsha256:
89+
90+
SCRAM-SHA-256
91+
~~~~~~~~~~~~~
92+
93+
To specify the ``SCRAM-SHA-256`` authentication mechanism, set the
94+
``mechanism`` field of your ``Credential`` struct to
95+
``AuthMechanism::ScramSha256``. This example specifies the
96+
authentication mechanism by using the following placeholders:
97+
98+
- ``username``: Your username
99+
- ``password``: Your password
100+
- ``db``: The authentication database associated with the user
101+
102+
.. literalinclude:: /includes/fundamentals/code-snippets/auth.rs
103+
:language: rust
104+
:dedent:
105+
:start-after: start-scramsha256
106+
:end-before: end-scramsha256
107+
108+
.. _rust-auth-scramsha1:
109+
110+
SCRAM-SHA-1
111+
~~~~~~~~~~~
112+
113+
To specify the ``SCRAM-SHA-1`` authentication mechanism, set the
114+
``mechanism`` field of your ``Credential`` struct to
115+
``AuthMechanism::ScramSha1``. This example specifies the
116+
authentication mechanism by using the following placeholders:
117+
118+
- ``username``: Your username
119+
- ``password``: Your password
120+
- ``db``: The authentication database associated with the user
121+
122+
.. literalinclude:: /includes/fundamentals/code-snippets/auth.rs
123+
:language: rust
124+
:dedent:
125+
:start-after: start-scramsha1
126+
:end-before: end-scramsha1
127+
128+
.. _rust-auth-aws:
129+
130+
MONGODB-AWS Mechanism
131+
---------------------
132+
133+
The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
134+
Identity and Access Management (AWS IAM) credentials to authenticate your
135+
user.
136+
137+
To use this authentication mechanism, you must add the ``aws-auth``
138+
feature flag to your ``mongodb`` dependency in your project's
139+
``Cargo.toml`` file. The following shows an example of what your
140+
``mongodb`` dependency feature list must include to enable the
141+
``MONGODB-AWS`` authentication mechanism:
142+
143+
.. code-block:: none
144+
:emphasize-lines: 3
145+
146+
[dependencies.mongodb]
147+
version = "{+version+}"
148+
features = [ "aws-auth", ... ]
149+
150+
.. important::
151+
152+
To use the ``MONGODB-AWS`` authentication mechanism in the
153+
{+driver-short+}, your application must meet the following
154+
requirements:
155+
156+
- You are connected to MongoDB Server version 4.4 or later.
157+
- You are using the ``tokio`` asynchronous runtime.
158+
159+
The driver obtains the credentials only from the first source in which
160+
they are found. The driver checks for your credentials from the following
161+
sources in the following order:
162+
163+
1. ``Credential`` struct or connection string
164+
#. Environment variables
165+
#. Web identity token file
166+
#. AWS ECS endpoint specified in the ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``
167+
environment variable
168+
#. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks
169+
<https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`__
170+
in the AWS documentation.
171+
172+
For example, if you specify your AWS credentials in your connection string, the
173+
driver uses those credentials and ignores any that you might have
174+
specified in environment variables.
175+
176+
Select from the :guilabel:`Credential Struct`, :guilabel:`Environment
177+
Variables`, and :guilabel:`Web Identity Token File` tabs below for
178+
code samples that demonstrate how to set your AWS IAM credentials in
179+
the corresponding ways.
180+
181+
.. tabs::
182+
183+
.. tab:: Credential Struct
184+
:tabid: credential struct
185+
186+
To specify the ``MONGODB-AWS`` authentication mechanism, set the
187+
``mechanism`` field of your ``Credential`` struct to
188+
``AuthMechanism::MongoDbAws``. This example specifies the
189+
authentication mechanism by using the following placeholders:
190+
191+
- ``access key ID``: Your AWS access key ID
192+
- ``secret access key``: Your AWS secret access key
193+
- ``db``: The authentication database associated with the user
194+
195+
If you are using temporary credentials, create a document that
196+
contains the value of your AWS session token, and then set the
197+
``mechanism_properties`` field of the ``Credential`` struct to
198+
this document. If you are not using temporary credentials, omit
199+
line 9 of the following example:
200+
201+
.. literalinclude:: /includes/fundamentals/code-snippets/auth.rs
202+
:language: rust
203+
:dedent:
204+
:start-after: start-aws
205+
:end-before: end-aws
206+
:linenos:
207+
208+
.. tip::
209+
210+
You can obtain temporary AWS IAM credentials from a Security
211+
Token Service (STS) Assume Role request. Learn more about
212+
this process in the `AssumeRole AWS documentation <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html>`__.
213+
214+
.. tab:: Environment Variables
215+
:tabid: environment variables
216+
217+
To store your AWS credentials in environment variables, run the
218+
following commands in your shell:
219+
220+
.. code-block:: bash
221+
222+
export AWS_ACCESS_KEY_ID=<access key ID>
223+
export AWS_SECRET_ACCESS_KEY=<secret access key>
224+
export AWS_SESSION_TOKEN=<session token>
225+
226+
If you are not using an AWS session token, omit the line
227+
that sets the ``AWS_SESSION_TOKEN`` environment variable.
228+
229+
Set the ``mechanism`` option in your
230+
``Credential`` struct to ``AuthMechanism::MongoDbAws``. The driver
231+
reads your AWS IAM credentials from your environment variables.
232+
The following code shows how to define a ``Credential`` struct
233+
with AWS authentication specified and connect to MongoDB:
234+
235+
.. literalinclude:: /includes/fundamentals/code-snippets/auth.rs
236+
:language: rust
237+
:dedent:
238+
:start-after: start-aws-env-var
239+
:end-before: end-aws-env-var
240+
241+
.. tab:: Web Identity Token File
242+
:tabid: web-identity-token-file
243+
244+
You can use the OpenID Connect (OIDC) token obtained from a web
245+
identity provider to authenticate to Amazon Elastic Kubernetes
246+
Service (EKS) or other services. To use an OIDC token, create a
247+
file that contains your token, then define an environment variable
248+
whose value is the absolute path to the token file as shown in the
249+
following shell command:
250+
251+
.. code-block:: bash
252+
253+
export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to OIDC token file>
254+
255+
Set the ``mechanism`` option in your
256+
``Credential`` struct to ``AuthMechanism::MongoDbAws``. The driver
257+
reads your AWS IAM credentials from the token file.
258+
The following code shows how to define a ``Credential`` struct
259+
with AWS authentication specified and connect to MongoDB:
260+
261+
.. literalinclude:: /includes/fundamentals/code-snippets/auth.rs
262+
:language: rust
263+
:dedent:
264+
:start-after: start-aws-env-var
265+
:end-before: end-aws-env-var
266+
267+
.. _rust-auth-x509:
268+
269+
MONGODB-X509 Mechanism
270+
----------------------
271+
272+
The ``MONGODB-X509`` authentication mechanism uses Transport Level Security (TLS)
273+
with X.509 certificates to authenticate your user, which is identified
274+
by the relative distinguished names (RDNs) of your client certificate.
275+
276+
.. tip::
277+
278+
To learn more about TLS, see the Wikipedia entry on
279+
:wikipedia:`Transport Layer Security <w/index.php?title=Transport_Layer_Security&oldid=1172659512>`.
280+
281+
When you specify this authentication mechanism, the server authenticates
282+
the connection by reading the following files:
283+
284+
- A certificate authority (CA) file, which contains one or more
285+
certificate authorities to trust when making a TLS connection
286+
- A certificate key file, which references the client certificate private key
287+
288+
To specify the ``MONGODB-X509`` authentication mechanism, set the
289+
``mechanism`` field of your ``Credential`` struct to
290+
``AuthMechanism::MongoDbX509``. This example specifies the
291+
authentication mechanism by using the following placeholders:
292+
293+
- ``path to CA certificate``: The filepath for your CA file
294+
- ``path to private client key``: The filepath for your certificate key file
295+
- ``db``: The authentication database associated with the user
296+
297+
The following code shows how to reference your certificates in your
298+
connection string, specify the ``MONGODB-X509`` authentication mechanism, and
299+
connect to MongoDB:
300+
301+
.. literalinclude:: /includes/fundamentals/code-snippets/auth.rs
302+
:language: rust
303+
:dedent:
304+
:start-after: start-x509
305+
:end-before: end-x509
306+
307+
.. TODO To learn more about enabling TLS on a connection, see :ref:`rust-tls`.
308+
309+
Additional Information
310+
----------------------
311+
312+
To learn more about authenticating to MongoDB, see
313+
:manual:`Authentication </core/authentication/>` in the Server manual.
314+
315+
To learn more about managing users of your MongoDB deployment, see
316+
:manual:`Users </core/security-users/>` in the Server manual.
317+
318+
API Documentation
319+
~~~~~~~~~~~~~~~~~
320+
321+
To learn more about the methods and types discussed in this
322+
guide, see the following API Documentation:
323+
324+
- `Credential <{+api+}/options/struct.Credential.html>`__
325+
- `ClientOptions <{+api+}/options/struct.ClientOptions.html>`__
326+
- `Client <{+api+}/options/struct.Client.html>`__
327+
- `Client::with_options() <{+api+}/struct.Client.html#method.with_options>`__
328+
- `ClientOptions::parse() <{+api+}/options/struct.ClientOptions.html#method.parse>`__

‎source/includes/fundamentals-sections.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ Fundamentals section:
33

44
- :ref:`Connect to MongoDB <rust-connection>`
55
- :ref:`Specify the {+stable-api+} Version <rust-stable-api>`
6+
- :ref:`Authenticate to MongoDB <rust-authentication>`
67
- :ref:`Read from and Write to MongoDB <rust-crud>`
78
- :ref:`Manage Databases and Collections <rust-db-coll>`
89
- :ref:`Perform Aggregations <rust-aggregation>`
@@ -11,6 +12,7 @@ Fundamentals section:
1112

1213
..
1314
- :atlas:`Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
15+
- :ref:`Specify the Stable API Version <rust-stable-api>`
1416
- :ref:`Authenticate to MongoDB <rust-authentication-mechanisms>`
1517
- :ref:`Connect with Enterprise Authentication Mechanisms <rust-enterprise-authentication-mechanisms>`
1618
- :ref:`Convert Data to and from BSON <rust-bson>`

0 commit comments

Comments
 (0)