Skip to content

Commit a595baa

Browse files
kyuan-mongodbkyuan-mongodb
authored
DOCSP-13829 authentication mechanism (#18)
* added authentication mechanism page
1 parent 91c1c33 commit a595baa

File tree

2 files changed

+252
-20
lines changed

2 files changed

+252
-20
lines changed

‎source/fundamentals.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ Fundamentals
88
:titlesonly:
99
:maxdepth: 1
1010

11+
/fundamentals/auth
1112

1213

1314
..
1415
/fundamentals/connection
15-
/fundamentals/auth
1616
/fundamentals/enterprise-auth
1717
/fundamentals/databases-collections
1818
/fundamentals/data-formats

‎source/fundamentals/auth.txt‎

Lines changed: 251 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,254 @@ Authentication Mechanisms
1010
:depth: 2
1111
:class: singlecol
1212

13-
In this guide, we show you how to authenticate with MongoDB using each
14-
**authentication mechanism** available in the MongoDB Community Edition.
15-
Authentication mechanisms are processes by which the driver and server
16-
confirm identity and establish trust to ensure security.
17-
18-
The mechanisms that you can use with the latest version of MongoDB Community
19-
Edition are as follows:
20-
21-
* Default
22-
* SCRAM-SHA-256
23-
* SCRAM-SHA-1
24-
* MONGODB-CR
25-
* MONGODB-AWS
26-
* X.509
27-
28-
To authenticate using ``Kerberos`` or ``LDAP``, see the
29-
:doc:`Enterprise Authentication Mechanisms guide </fundamentals/enterprise-auth>`.
30-
For more information on establishing a connection to your MongoDB cluster,
31-
read our :doc:`Connection Guide </fundamentals/connection>`.
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to use each **authentication
17+
mechanism** available in the MongoDB Community Edition. MongoDB uses
18+
authentication mechanisms to confirm an identity and establish trust to
19+
ensure security in the driver and server before connecting.
20+
21+
If you want to establish a connection to your MongoDB cluster without an
22+
authentication mechanism, see our :doc:`Connection Guide </fundamentals/connection>`.
23+
24+
Supported Mechanisms
25+
--------------------
26+
27+
The Go Driver establishes a connection with an authentication mechanism
28+
through a `Client <https://pkg.go.dev/go.mongodb.org/mongo-driver@v1.7.1/mongo#Client>`__
29+
type. The ``Client`` type specifies the mechanism and credentials to use
30+
as connection options in a `Credential <https://pkg.go.dev/go.mongodb.org/mongo-driver@v1.7.1/mongo/options#Credential>`__
31+
type . To configure these options, pass a ``Credential`` type to the
32+
`SetAuth() <https://pkg.go.dev/go.mongodb.org/mongo-driver@v1.7.1/mongo/options#ClientOptions.SetAuth>`__
33+
function of the `ClientOptions <https://pkg.go.dev/go.mongodb.org/mongo-driver@v1.7.1/mongo/options#ClientOptions>`__
34+
type.
35+
36+
The following sections demonstrate this process with the five
37+
mechanisms the MongoDB Community Edition supports.
38+
39+
Example Conventions
40+
~~~~~~~~~~~~~~~~~~~
41+
42+
Each authentication mechanism contains the following placeholders:
43+
44+
* ``username`` - Your MongoDB username
45+
* ``password`` - Your MongoDB user's password
46+
* ``hostname`` - Your MongoDB servers network address, accessible by
47+
your client
48+
* ``port`` - Your MongoDB servers port number
49+
* ``authenticationDb`` - Your MongoDB database that contains the user's
50+
authentication data. If you omit this option, the driver uses the
51+
default value ``admin``.
52+
53+
.. _default-auth-mechanism:
54+
55+
Default
56+
~~~~~~~
57+
58+
The default mechanism uses one of the following authentication
59+
mechanisms depending on what MongoDB versions your server supports:
60+
61+
.. list-table::
62+
:header-rows: 1
63+
:stub-columns: 1
64+
:class: compatibility-large
65+
66+
* - Mechanism
67+
- Versions
68+
69+
* - ``SCRAM-SHA-256``
70+
- MongoDB 4.0 and later
71+
72+
* - ``SCRAM-SHA-1``
73+
- MongoDB 3.0, 3.2, 3.4, and 3.6
74+
75+
* - ``MONGODB-CR``
76+
- MongoDB 2.6 and earlier
77+
78+
To specify the default authentication mechanism, omit the
79+
``AuthMechanism`` option:
80+
81+
.. code-block:: go
82+
83+
credential := options.Credential{
84+
AuthSource: "<authenticationDb>",
85+
Username: "<username>",
86+
Password: "<password>",
87+
}
88+
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
89+
SetAuth(credential)
90+
91+
client, err := mongo.Connect(context.TODO(), clientOpts)
92+
93+
For more information on the challenge-response (CR) and salted
94+
challenge-response authentication mechanisms (SCRAM) that MongoDB supports,
95+
see the :manual:`SCRAM </core/security-scram/>` section of the server manual.
96+
97+
``SCRAM-SHA-256``
98+
~~~~~~~~~~~~~~~~~
99+
100+
.. important::
101+
102+
``SCRAM-SHA-256`` is the default authentication method for MongoDB starting
103+
in MongoDB 4.0.
104+
105+
``SCRAM-SHA-256`` is a salted challenge-response authentication mechanism
106+
(SCRAM) that uses your username and password, encrypted with the ``SHA-256``
107+
algorithm, to authenticate your user.
108+
109+
To specify the ``SCRAM-SHA-256`` authentication mechanism, assign the
110+
``AuthMechanism`` option the value ``"SCRAM-SHA-256"``:
111+
112+
.. code-block:: go
113+
:emphasize-lines: 2
114+
115+
credential := options.Credential{
116+
AuthMechanism: "SCRAM-SHA-256",
117+
AuthSource: "<authenticationDb>",
118+
Username: "<username>",
119+
Password: "<password>",
120+
}
121+
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
122+
SetAuth(credential)
123+
124+
client, err := mongo.Connect(context.TODO(), clientOpts)
125+
126+
.. _scram-sha-1-auth-mechanism:
127+
128+
``SCRAM-SHA-1``
129+
~~~~~~~~~~~~~~~
130+
131+
.. important::
132+
133+
``SCRAM-SHA-1`` is the default authentication method for MongoDB versions
134+
3.0, 3.2, 3.4, and 3.6.
135+
136+
``SCRAM-SHA-1`` is a salted challenge-response mechanism (SCRAM) that uses your
137+
username and password, encrypted with the ``SHA-1`` algorithm, to authenticate
138+
your user.
139+
140+
To specify the ``SCRAM-SHA-1`` authentication mechanism, assign the
141+
``AuthMechanism`` option the value ``"SCRAM-SHA-1"``:
142+
143+
.. code-block:: go
144+
:emphasize-lines: 2
145+
146+
credential := options.Credential{
147+
AuthMechanism: "SCRAM-SHA-1",
148+
AuthSource: "<authenticationDb>",
149+
Username: "<username>",
150+
Password: "<password>",
151+
}
152+
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
153+
SetAuth(credential)
154+
155+
client, err := mongo.Connect(context.TODO(), clientOpts)
156+
157+
``MONGODB-CR``
158+
~~~~~~~~~~~~~~
159+
160+
``MONGODB-CR`` is a challenge-response authentication mechanism that uses your
161+
username and password to authenticate your user.
162+
163+
.. important::
164+
165+
This authentication mechanism was deprecated starting in MongoDB 3.6
166+
and is no longer supported as of MongoDB 4.0.
167+
168+
``MONGODB-AWS``
169+
~~~~~~~~~~~~~~~
170+
171+
.. important::
172+
173+
The MONGODB-AWS authentication mechanism is only available in MongoDB
174+
versions 4.4 and later.
175+
176+
The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
177+
Identity and Access Management (AWS IAM) credentials to authenticate your
178+
user.
179+
180+
To specify the ``MONGODB-AWS`` authentication mechanism, perform the
181+
following:
182+
183+
- Assign the ``AuthMechanism`` option the value ``MONGODB-AWS``
184+
- Assign the ``Username`` option the value of your ``accessKeyID``
185+
- Assign the ``Password`` option the value of your ``secretAccessKey``
186+
187+
.. code-block:: go
188+
:emphasize-lines: 3, 5-6
189+
190+
var accessKeyID, secretAccessKey string
191+
awsCredential := options.Credential{
192+
AuthMechanism: "MONGODB-AWS",
193+
AuthSource: "<authenticationDb>",
194+
Username: "<accessKeyID>",
195+
Password: "<secretAccessKey>",
196+
}
197+
awsIAMClient, err := mongo.Connect(
198+
context.TODO(),
199+
options.Client().SetAuth(awsCredential))
200+
if err != nil {
201+
panic(err)
202+
}
203+
_ = awsIAMClient
204+
205+
If you need to specify an AWS session token, use the temporary
206+
credentials returned from an assume role request.
207+
208+
To use temporary credentials, assign the ``AuthMechanismProperties``
209+
option the value of your ``sessionToken``:
210+
211+
.. code-block:: go
212+
:emphasize-lines: 7-9
213+
214+
var sessionToken string
215+
assumeRoleCredential := options.Credential{
216+
AuthMechanism: "MONGODB-AWS",
217+
AuthSource: "<authenticationDb>",
218+
Username: "<accessKeyID>",
219+
Password: "<secretAccessKey>",
220+
AuthMechanismProperties: map[string]string{
221+
"AWS_SESSION_TOKEN": "<sessionToken>",
222+
},
223+
}
224+
assumeRoleClient, err := mongo.Connect(context.TODO(),
225+
options.Client().SetAuth(assumeRoleCredential))
226+
227+
``X.509``
228+
~~~~~~~~~
229+
230+
The ``X.509`` authentication mechanism uses
231+
:wikipedia:`TLS <Transport_Layer_Security>` with X.509 certificates to
232+
authenticate your user, identified by the relative distinguished names
233+
(RDNs) of your client certificate. When you specify the ``X.509``
234+
authentication mechanism, the server authenticates the connection using
235+
the paths of the following files:
236+
237+
- ``tlsCAFile`` which contains either a single or a bundle of certificate authorities to trust when making a TLS connection
238+
- ``tlsCertificateKeyFile`` which references the path to the client certificate file or the client private key file
239+
240+
To specify the ``X.509`` authentication mechanism, perform the
241+
following:
242+
243+
- Assign the ``tlsCAFile`` the path to its file in the connection string
244+
- Assign the ``tlsCertificateKeyFile`` the path to its file in the connection string
245+
- Assign the ``AuthMechanism`` option the value ``"MONGODB-X509"``
246+
247+
.. code-block:: go
248+
:emphasize-lines: 4-5, 7
249+
250+
caFilePath := "<cafile_path>"
251+
certificateKeyFilePath := "<client_certificate_path>"
252+
253+
uri := "mongodb://<hostname>:<port>/?tlsCAFile=%s&tlsCertificateKeyFile=%s"
254+
uri = fmt.Sprintf(uri, caFilePath, certificateKeyFilePath)
255+
credential := options.Credential{
256+
AuthMechanism: "MONGODB-X509",
257+
}
258+
259+
clientOpts := options.Client().ApplyURI(uri).SetAuth(credential)
260+
261+
For more information on configuring your application to use
262+
certificates as well as TLS/SSL options, see our
263+
:doc:`TLS/SSL guide </fundamentals/connection/tls>`.

0 commit comments

Comments
 (0)