1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
=======
TLS/SSL
=======
The Node.js driver supports TLS/SSL connections to MongoDB that support TLS/SSL support.
No Certificate Validation
-------------------------
If the MongoDB instance does not perform any validation of the certificate chain, include the ``tls=true`` in the :manual:`URI ConnectionString </reference/connection-string/>` .
.. code-block:: js
const { MongoClient } = require('mongodb');
// Connection URL
const url = 'mongodb://localhost:27017?tls=true';
// Create a new MongoClient
const client = new MongoClient(url);
// Function to connect to the server and run your code
async function run() {
try {
// Connect the client to the server
await client.connect();
console.log('Connected successfully to server');
} finally {
// Ensures that the client will close when you finish/error
await client.close();
}
}
// Runs your code
run();
Validate Server Certificate
---------------------------
If the MongoDB instance presents a certificate, to validate the server's certificate, pass the following when creating a ``MongoClient``\ :
* A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``tls=true`` setting,
* A connections options with the certificate for the Certificate Authority (\ ``tlsCAFile``\ )
.. code-block:: js
const { MongoClient } = require('mongodb');
const client = new MongoClient('mongodb://localhost:27017?tls=true', {
tlsCAFile: `${__dirname}/certs/ca.pem`)
});
Disable Hostname Verification
-----------------------------
By default, the driver ensures that the hostname included in the
server's TLS certificate(s) matches the hostname(s) provided in the URI connection string. If you need to disable the hostname verification, but otherwise validate the server's certificate, pass to the new ``MongoClient``\ :
*
A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``tls=true`` setting,
*
A connections options with the certificate for the Certificate Authority (\ ``tlsCAFile``\ ) but ``tlsAllowInvalidHostnames`` set to ``true``.
.. code-block:: js
const { MongoClient } = require('mongodb');
const client = new MongoClient('mongodb://localhost:27017?tls=true', {
tlsCAFile: `${__dirname}/certs/ca.pem`),
tlsAllowInvalidHostnames: true
});
Validate Server Certificate and Present Valid Certificate
---------------------------------------------------------
If the MongoDB server performs certificate validation, the client must pass its
certificate to the server. To pass the client's certificate as well as to validate the server's certificate, pass to the new ``MongoClient``\ :
*
A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``tls=true`` setting,
*
A connections options with the certificate for the Certificate Authority (\ ``tlsCAFile``\ ), the client's certificate (\ ``tlsCertificateKeyFile``\ ). If the client's key file is encrypted, include the password (\ ``tlsCertificateKeyFilePassword``\ ).
.. code-block:: js
const { MongoClient } = require('mongodb');
const fs = require('fs');
const client = new MongoClient('mongodb://localhost:27017?tls=true', {
tlsCAFile: `${__dirname}/certs/ca.pem`),
tlsCertificateKeyFile: `${__dirname}/certs/client.pem`,
tlsCertificateKeyFilePassword: '10gen'
});
Connect with X.509
------------------
:manual:`X.509 </core/security-x.509>` authentication requires the use of TLS/SSL connections with certificate validation. MongoDB uses the X.509 certificate presented during TLS negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.
To connect using the X.509 authentication mechanism, specify ``MONGODB-X509`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` , ``tls=true``\ , and the username. Use ``enodeURIComponent`` to encode the username string.
In addition to the connection string, pass to the new ``MongoClient``
a connections options with the X.509 certificate and other :doc:`TLS/SSL connections </tutorials/connect/tls>` options.
.. code-block:: js
const { MongoClient } = require('mongodb');
const userName = 'CN=client,OU=kerneluser,O=10Gen,L=New York City,ST=New York,C=US';
const url = `mongodb://${encodeURIComponent(userName)}@server:27017?authMechanism=MONGODB-X509&tls=true`;
const client = new MongoClient(url, {
tlsCertificateKeyFile: `${__dirname}/certs/x509/client.pem`
});
TLS/SSL Options
---------------
The following TLS/SSL options are available.
.. list-table::
:header-rows: 1
* - Parameter
- Type
- Default
- Description
* - ``tls``
- boolean
- ``false``
- Use TLS connections.
* - ``tlsInsecure``
- boolean
- ``false``
- Relax TLS constraints as much as possible (e.g. allowing invalid certificates or hostname mismatches); drivers must document the exact constraints which are relaxed by this option being true
* - ``tlsCAFile``
- string[]
-
- Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection
* - ``tlsCertificateKeyFile``
- string
-
- Path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated
* - ``tlsCertificateKeyFilePassword``
- Buffer|string
-
- String or buffer containing the client certificate password.
* - ``tlsAllowInvalidCertificates``
- boolean
- false
- Specifies whether or not the driver should error when the server’s TLS certificate is invalid
* - ``tlsAllowInvalidHostnames``
- boolean
- false
- Specifies whether or not the driver should error when there is a mismatch between the server’s hostname and the hostname specified by the TLS certificate
|
