From 64bfd91385f8e51cd1d9945d1a7a6b30d1874668 Mon Sep 17 00:00:00 2001 From: Alex Bevilacqua Date: Mon, 29 May 2023 13:50:55 -0400 Subject: [PATCH 1/4] docs: update ssl tutorial for MongoDB Atlas / x.509 --- docs/tutorials/ssl.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index 3e3d9d2bd47..dc1a9e87921 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -68,9 +68,9 @@ MongooseServerSelectionError: Hostname/IP does not match certificate's altnames: The SSL certificate's [common name](https://knowledge.digicert.com/solution/SO7239.html) **must** line up with the host name in your connection string. If the SSL certificate is for `hostname2.mydomain.com`, your connection string must connect to `hostname2.mydomain.com`, not any other hostname or IP address that may be equivalent to `hostname2.mydomain.com`. For replica sets, this also means that the SSL certificate's common name must line up with the [machine's `hostname`](../connections.html#replicaset-hostnames). -## X509 Auth +## X.509 Authentication -If you're using [X509 authentication](https://www.mongodb.com/docs/drivers/node/current/fundamentals/authentication/mechanisms/#x.509), you should set the user name in the connection string, **not** the `connect()` options. +If you're using [X.509 authentication](https://www.mongodb.com/docs/drivers/node/current/fundamentals/authentication/mechanisms/#x.509), you should set the user name in the connection string, **not** the `connect()` options. ```javascript // Do this: @@ -91,3 +91,24 @@ await mongoose.connect('mongodb://127.0.0.1:27017/test', { auth: { username } }); ``` +## X.509 Authentication with MongoDB Atlas + +With MongoDB Atlas, X.509 certificates are not Root CA certificates and will not work with the `sslCA` parameter as self-signed certificates would. If the `sslCA` parameter is used an error similar to the following would be raised: + +```no-highlight +MongoServerSelectionError: unable to get local issuer certificate +``` + +To connect to a MongoDB Atlas cluster using X.509 authentication the correct option to set is `tlsCertificateKeyFile`, as well as the necessary options to . In addition to enabling SSL Validation and authenticatio mechanism, we get a full example: + +```javascript +const url = "mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509" +await mongoose.connect(url, { + sslValidate: true, + tlsCertificateKeyFile: /path/to/certificate.pem, + authMechanism: 'MONGODB-X509', + authSource: '$external' +}); +``` + +**Note** The connection string options must be URL escaped correctly. From 67ce62e71162ed4a642568e2f8496c55f5dc4b36 Mon Sep 17 00:00:00 2001 From: Alex Bevilacqua Date: Mon, 29 May 2023 13:54:24 -0400 Subject: [PATCH 2/4] Update ssl.md --- docs/tutorials/ssl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index dc1a9e87921..cfd2836accc 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -99,7 +99,7 @@ With MongoDB Atlas, X.509 certificates are not Root CA certificates and will not MongoServerSelectionError: unable to get local issuer certificate ``` -To connect to a MongoDB Atlas cluster using X.509 authentication the correct option to set is `tlsCertificateKeyFile`, as well as the necessary options to . In addition to enabling SSL Validation and authenticatio mechanism, we get a full example: +To connect to a MongoDB Atlas cluster using X.509 authentication the correct option to set is `tlsCertificateKeyFile`. The connection string already specifies the `authSource` and `authMechanism`, and the DNS `TXT` record would supply the parameter and value for `sslValidate`, however they're included below as `connect()` options for completeness: ```javascript const url = "mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509" From 3a2d8020bb0f4866808f6f3d4c889cbc66ff007b Mon Sep 17 00:00:00 2001 From: Alex Bevilacqua Date: Tue, 30 May 2023 10:41:37 -0400 Subject: [PATCH 3/4] Update ssl.md --- docs/tutorials/ssl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index cfd2836accc..17ac6b7cf29 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -105,7 +105,7 @@ To connect to a MongoDB Atlas cluster using X.509 authentication the correct opt const url = "mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509" await mongoose.connect(url, { sslValidate: true, - tlsCertificateKeyFile: /path/to/certificate.pem, + tlsCertificateKeyFile: "/path/to/certificate.pem", authMechanism: 'MONGODB-X509', authSource: '$external' }); From e280b5587c812880d2b216415babee2cc6e42442 Mon Sep 17 00:00:00 2001 From: Valeri Karpov Date: Thu, 1 Jun 2023 20:02:36 -0400 Subject: [PATCH 4/4] docs: couple style fixes --- docs/tutorials/ssl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index 17ac6b7cf29..95bee181911 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -102,10 +102,10 @@ MongoServerSelectionError: unable to get local issuer certificate To connect to a MongoDB Atlas cluster using X.509 authentication the correct option to set is `tlsCertificateKeyFile`. The connection string already specifies the `authSource` and `authMechanism`, and the DNS `TXT` record would supply the parameter and value for `sslValidate`, however they're included below as `connect()` options for completeness: ```javascript -const url = "mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509" +const url = 'mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509'; await mongoose.connect(url, { sslValidate: true, - tlsCertificateKeyFile: "/path/to/certificate.pem", + tlsCertificateKeyFile: '/path/to/certificate.pem', authMechanism: 'MONGODB-X509', authSource: '$external' });