Skip to content

Commit 81c8c2e

Browse files
rustagirrustagir
committed
DOCSP-25770: TLS setup (#666)
* DOCSP-25770: TLS connection * first draft * TOC * first pass fixes * small fixes * change header levels * orient page around production * fixes * MW PR fixes 1 * wiki link fixes * MW PR fixes 2 * fixes * MW suggestions * NB PR fixes 1 * small fixes (cherry picked from commit cafe9c5) (cherry picked from commit 05b5167)
1 parent 8b87a2e commit 81c8c2e

File tree

2 files changed

+289
-0
lines changed

2 files changed

+289
-0
lines changed

‎source/fundamentals/connection.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Connection
1111
/fundamentals/connection/connect
1212
/fundamentals/connection/connection-options
1313
/fundamentals/connection/network-compression
14+
/fundamentals/connection/tls
1415

1516
.. contents:: On this page
1617
:local:
@@ -28,6 +29,7 @@ learn:
2829
- :ref:`How to Connect to MongoDB <node-connect-to-mongodb>`
2930
- :ref:`The Available Connection Options <node-connection-options>`
3031
- :ref:`How to Enable Network Compression <node-network-compression>`
32+
- :ref:`How to Enable TLS on a Connection <node-connect-tls>`
3133

3234
For information about authenticating to MongoDB,
3335
see :ref:`node-authentication-mechanisms` and

‎source/fundamentals/connection/tls.txt

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
.. _node-connect-tls:
2+
3+
==========================
4+
Enable TLS on a Connection
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to connect to MongoDB instances with
17+
the TLS security protocol.
18+
19+
To configure your connection to use TLS, enable
20+
the TLS option and provide your certificates for validation.
21+
22+
.. tip::
23+
24+
To learn more about TLS, see the Wikipedia entry on
25+
:wikipedia:`Transport Layer Security <Transport_Layer_Security>`.
26+
27+
.. _node-enable-tls:
28+
29+
Enable TLS
30+
----------
31+
32+
You can enable TLS on a connection to your MongoDB instance
33+
in the following ways:
34+
35+
- Setting the ``tls`` option to ``true`` in your ``MongoClientOptions`` object
36+
- Setting the ``tls`` option to ``true`` in your connection string
37+
38+
.. tabs::
39+
40+
.. tab:: MongoClientOptions
41+
:tabid: mongoclientoptions
42+
43+
A ``MongoClient`` instance can connect with TLS if you set ``tls``
44+
to ``true`` in your ``MongoClientOptions`` object:
45+
46+
.. code-block:: js
47+
48+
const client = new MongoClient(uri, { tls: true });
49+
50+
.. tab:: Connection String
51+
:tabid: connection string
52+
53+
A ``MongoClient`` instance can connect with TLS if you set the
54+
``tls`` option to ``true`` in your connection string:
55+
56+
.. code-block:: js
57+
:emphasize-lines: 1
58+
59+
const uri = "mongodb://<hostname>:<port>?tls=true";
60+
const client = new MongoClient(uri, myClientSettings);
61+
62+
.. note::
63+
64+
If you use a DNS SRV record when connecting to MongoDB by specifying
65+
the ``+srv`` modification in your connection string, you enable
66+
TLS on your connection by default.
67+
68+
In addition to the ``tls`` client option, the driver provides additional
69+
options to configure TLS on your connection. For **testing purposes**,
70+
you can set the ``tlsAllowInvalidHostnames``,
71+
``tlsAllowInvalidCertificates``, and ``tlsInsecure`` client options.
72+
73+
Setting the ``tlsAllowInvalidHostnames`` option to ``true`` disables
74+
hostname verification, and setting the
75+
``tlsAllowInvalidCertificates`` to ``true`` disables certificate
76+
validation. Setting the ``tlsInsecure`` option to ``true`` disables
77+
both certificate and hostname validation.
78+
79+
.. warning::
80+
81+
Specifying any of these options in a production environment makes
82+
your application insecure and potentially
83+
vulnerable to expired certificates and to foreign processes posing
84+
as valid client instances.
85+
86+
For a full list of client options, see :ref:`node-connection-options`.
87+
88+
.. _node-configure-tls-certificates:
89+
90+
Configure Certificates
91+
----------------------
92+
93+
To successfully initiate a TLS request, an application must prove its
94+
identity by referencing cryptographic certificates. To connect to
95+
MongoDB with TLS, your certificates must be stored as PEM
96+
files.
97+
98+
.. important::
99+
100+
For production use, your MongoDB deployment should use valid
101+
certificates generated and signed by the same certificate authority.
102+
For testing, you can use self-signed certificates.
103+
104+
The following list describes the components that you need to establish
105+
a connection with TLS:
106+
107+
.. list-table::
108+
:header-rows: 1
109+
:widths: 30 70
110+
111+
* - TLS Component
112+
- Description
113+
114+
* - Certificate Authority (CA)
115+
- One or more certificate authorities to
116+
trust when making a TLS connection.
117+
118+
* - Client Certificate
119+
- A digital certificate and key that allow the server to verify the identity
120+
of your application to establish an encrypted network connection.
121+
122+
* - Certificate Key
123+
- The client certificate private key file. This key is often
124+
included within the certificate file itself.
125+
126+
* - Passphrase
127+
- The password to decrypt the private client key if it is encrypted.
128+
129+
.. tip::
130+
131+
To learn more about the PEM format, see the Wikipedia entry on
132+
:wikipedia:`Privacy-Enhanced Mail <Privacy-Enhanced_Mail>`.
133+
134+
.. _node-client-tls-connect:
135+
136+
Reference Certificates in a Client
137+
----------------------------------
138+
139+
You must reference your certificates in your ``MongoClientOptions``
140+
object so that the server can validate them before the client connects.
141+
You can reference your certificates in the following ways:
142+
143+
- Create a ``SecureContext`` object to store certificates *(Recommended)*
144+
- Provide filepath strings that point to your certificates
145+
- Create ``Buffer`` objects to store certificates
146+
147+
.. _node-tls-securecontext:
148+
149+
Create a ``SecureContext`` Object to Store Certificates
150+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151+
152+
We recommend that you use the ``secureContext`` option to configure
153+
your TLS connection. ``SecureContext`` objects are native to Node.js
154+
and allow you to keep all your TLS options in a single reusable object.
155+
156+
To create a ``SecureContext`` object, import the ``createSecureContext()``
157+
method from the ``tls`` module. Next, call the ``createSecureContext()``
158+
method and pass the contents of your certificates in the options parameter.
159+
This method returns a ``SecureContext`` object that you can use in your
160+
``MongoClientOptions`` object.
161+
162+
The following code shows how to create a ``SecureContext`` object and
163+
pass it to your client:
164+
165+
.. code-block:: js
166+
:emphasize-lines: 2-6, 9
167+
168+
// Create a SecureContext object
169+
const secureContext = tls.createSecureContext({
170+
ca: fs.readFileSync(`<path to CA certificate>`),
171+
cert: fs.readFileSync(`<path to public client certificate>`),
172+
key: fs.readFileSync(`<path to private client key>`),
173+
});
174+
175+
// Pass the SecureContext as a client option
176+
const client = new MongoClient(uri, { tls: true, secureContext });
177+
178+
To learn more about the ``createSecureContext()`` method and the
179+
``tls`` package, see the `Node.js TLS API documentation
180+
<https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions>`__.
181+
182+
For a runnable example that uses a ``SecureContext`` object, see
183+
the :ref:`SecureContext Example <node-securecontext-full-example>`.
184+
185+
Provide Certificate Filepaths
186+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187+
188+
You can include the filepaths for your certificates as client options to
189+
retrieve your certificates while connecting with TLS.
190+
191+
The following code shows how to provide certificate filepaths as options
192+
in your ``MongoClient``:
193+
194+
.. code-block:: js
195+
:emphasize-lines: 4-6
196+
197+
// Pass filepaths as client options
198+
const client = new MongoClient(uri, {
199+
tls: true,
200+
tlsCAFile: `<path to CA certificate>`,
201+
tlsCertificateFile: `<path to public client certificate>`,
202+
tlsCertificateKeyFile: `<path to private client key>`,
203+
});
204+
205+
Create ``Buffer`` Objects to Store Certificates
206+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
207+
208+
You can pass the contents of your certificate files as ``Buffer``
209+
objects in your client options to connect with TLS.
210+
211+
The following code shows how to read the contents of your certificate
212+
files and pass the resulting ``Buffer`` objects as options in your
213+
``MongoClient``:
214+
215+
.. code-block:: js
216+
:emphasize-lines: 2-4, 7
217+
218+
// Read file contents
219+
const ca = fs.readFileSync(`<path to CA certificate>`);
220+
const cert = fs.readFileSync(`<path to public client certificate>`);
221+
const key = fs.readFileSync(`<path to private client key>`);
222+
223+
// Pass Buffers as client options
224+
const client = new MongoClient(uri, { tls: true, ca, cert, key });
225+
226+
.. _node-securecontext-full-example:
227+
228+
``SecureContext`` Example
229+
-------------------------
230+
231+
This example shows how to create a ``SecureContext`` object and
232+
a ``MongoClient`` instance that includes TLS options. The example
233+
connects to MongoDB and executes a find query:
234+
235+
.. code-block:: js
236+
237+
import { MongoClient } from "mongodb";
238+
import * as fs from "fs";
239+
import * as tls from "tls";
240+
241+
// Replace the uri string with your connection string.
242+
const uri = "<connection uri>";
243+
244+
// Replace the filepaths with your certificate filepaths.
245+
const secureContext = tls.createSecureContext({
246+
ca: fs.readFileSync(`<path to CA certificate>`),
247+
cert: fs.readFileSync(`<path to public client certificate>`),
248+
key: fs.readFileSync(`<path to private client key>`),
249+
});
250+
251+
// Create a client with the secureContext option
252+
const client = new MongoClient(uri, { tls: true, secureContext });
253+
254+
async function run() {
255+
try {
256+
const db = client.db("myDB");
257+
const myColl = db.collection("myColl");
258+
const doc = await myColl.findOne({});
259+
console.log(doc);
260+
} finally {
261+
await client.close();
262+
}
263+
}
264+
run().catch(console.dir);
265+
266+
Additional Information
267+
----------------------
268+
269+
For more information about enabling TLS on a connection, see the
270+
following Server manual documentation:
271+
272+
- :manual:`TLS/SSL (Transport Encryption) </core/security-transport-encryption/>`
273+
- :manual:`TLS/SSL Configuration for Clients </tutorial/configure-ssl-clients/>`
274+
275+
API Documentation
276+
~~~~~~~~~~~~~~~~~
277+
278+
- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__
279+
- `MongoClient <{+api+}/classes/MongoClient.html>`__
280+
- `tlsAllowInvalidHostnames client option <{+api+}/interfaces/MongoClientOptions.html#tlsAllowInvalidHostnames>`__
281+
- `tlsAllowInvalidCertificates client option <{+api+}/interfaces/MongoClientOptions.html#tlsAllowInvalidCertificates>`__
282+
- `secureContext client option <{+api+}/interfaces/MongoClientOptions.html#secureContext>`__
283+
- `tlsCAFile client option <{+api+}/interfaces/MongoClientOptions.html#tlsCAFile>`__
284+
- `tlsCertificateKeyFile client option <{+api+}/interfaces/MongoClientOptions.html#tlsCertificateKeyFile>`__
285+
- `ca client option <{+api+}/interfaces/MongoClientOptions.html#ca>`__
286+
- `cert client option <{+api+}/interfaces/MongoClientOptions.html#cert>`__
287+
- `key client option <{+api+}/interfaces/MongoClientOptions.html#key>`__

0 commit comments

Comments
 (0)