docs(guide): convert /tutorials/connect/authenticating.md to rst

Fixes NODE-2199

Author: daprahamian

docs/guide/tutorials/connect/authentication.txt

@@ -1,3 +1,292 @@
 ==============
 Authentication
 ==============
+
+The Node.js driver supports all MongoDB :manual:`authentication mechanisms </core/authentication/>` , including those only available in the MongoDB :manual:`Enterprise Edition </administration/install-enterprise/>` .
+
+DEFAULT
+-------
+
+To use the default mechanism, either omit the authentication mechanism specification or specify ``DEFAULT`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` . The driver will attempt to authenticate using the :manual:`SCRAM-SHA-256 authentication </core/security-scram/>` method if it is available on the MongoDB server. If the server does not support ``SCRAM-SHA-256``, but does support `SCRAM-SHA-1``, the driver will authenticate with ``SCRAM-SHA-1``. If neither ``SCRAM-SHA-256`` or ``SCRAM-SHA-1`` are supported on the server, the driver will authenticate using ``MONGODB-CR`` .
+
+Include the name and password and the :manual:`authentication database </core/security-users/#user-authentication-database>` (\ ``authSource``\ ) in the connection string.
+
+In the following example, the connection string specifies the user ``dave``\ , password ``abc123``\ , and authentication mechanism ``DEFAULT``.
+
+.. important::
+ The user and password should always be **URI** encoded using ``encodeURIComponent`` to ensure any non URI compliant user or password characters are correctly parsed.
+
+.. code-block:: js
+
+ const { MongoClient } = require('mongodb');
+
+ const user = encodeURIComponent('dave');
+ const password = encodeURIComponent('abc123');
+ const authMechanism = 'DEFAULT';
+
+ // Connection URL
+ const url = `mongodb://${user}:${password}@localhost:27017/?authMechanism=${authMechanism}`;
+ 
+ // Create a new MongoClient
+ const client = new MongoClient(url);
+ 
+ // Function to connect to the server
+ 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();
+
+SCRAM-SHA-256
+-------------
+
+.. note::
+ ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting in version 4.0
+
+To explicitly connect to MongoDB using :manual:`SCRAM-SHA-256 </core/security-scram/>` , specify ``SCRAM-SHA-256`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` .
+
+Include the name and password and the :manual:`authentication database </core/security-users/#user-authentication-database>` (\ ``authSource``\ ) in the connection string.
+
+In the following example, the connection string specifies the user ``dave``\ , password ``abc123``\ , authentication mechanism ``SCRAM-SHA-256``\ , and authentication database ``myprojectdb``
+
+.. code-block:: js
+
+ const { MongoClient } = require('mongodb');
+
+ // Connection URL
+ const url = 'mongodb://dave:abc123@localhost:27017/?authMechanism=SCRAM-SHA-256&authSource=myprojectdb';
+
+ // Create a new MongoClient
+ const client = new MongoClient(url);
+
+ // Function to connect to the server
+ 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();
+
+SCRAM-SHA-1
+-----------
+
+.. note::
+ ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions 3.0, 3.2, 3.4, and 3.6.
+
+To explicitly connect to MongoDB using :manual:`SCRAM-SHA-1 </core/security-scram/>` , specify ``SCRAM-SHA-1`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` .
+
+Include the name and password and the :manual:`authentication database </core/security-users/#user-authentication-database>` (\ ``authSource``\ ) in the connection string.
+
+In the following example, the connection string specifies the user ``dave``\ , password ``abc123``\ , authentication mechanism ``SCRAM-SHA-1``\ , and authentication database ``myprojectdb``
+
+.. code-block:: js
+
+ const { MongoClient } = require('mongodb');
+
+ // Connection URL
+ const url = 'mongodb://dave:abc123@localhost:27017/?authMechanism=SCRAM-SHA-1&authSource=myprojectdb';
+
+ // Create a new MongoClient
+ const client = new MongoClient(url);
+
+ // Function to connect to the server
+ 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();
+
+MONGODB-CR
+----------
+
+.. warning::
+ MONGODB-CR was deprecated starting in MongoDB 3.6, and is no longer supported as of MongoDB 4.0
+
+
+To explicitly connect to MongoDB using ``MONGODB-CR`` , specify ``MONGODB-CR`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` .
+
+Include the name and password and the :manual:`authentication database </core/security-users/#user-authentication-database>` (\ ``authSource``\ ) in the connection string.
+
+In the following example, the connection string specifies the user ``dave``\ , password ``abc123``\ , authentication mechanism ``MONGODB-CR``\ , and authentication database ``myprojectdb``.
+
+.. code-block:: js
+
+ const { MongoClient } = require('mongodb');
+
+ // Connection URL
+ const url = 'mongodb://dave:abc123@localhost:27017/?authMechanism=MONGODB-CR&authSource=myprojectdb';
+
+ // Create a new MongoClient
+ const client = new MongoClient(url);
+
+ // Function to connect to the server
+ 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();
+
+.. important::
+ If you have :manual:`upgraded the authentication schema </release-notes/3.0-scram/>` from ``MONGODB-CR`` to ``SCRAM-SHA-1``\ , ``MONGODB-CR`` credentials will fail to authenticate.
+
+X509
+----
+
+With :manual:`X.509 </core/security-x.509>` mechanism, MongoDB uses the X.509 certificate presented during SSL negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.
+
+X.509 authentication requires the use of SSL connections with certificate validation and is available in MongoDB 2.6 and newer.
+
+To connect using the X.509 authentication mechanism, specify ``MONGODB-X509`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` , ``ssl=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 for the ``server`` with the X.509 certificate and other :doc:`TLS/SSL connections </tutorials/connect/tls>` options.
+
+.. code-block:: js
+
+ const { MongoClient } = require('mongodb');
+ const fs = require('fs');
+
+ // Read the cert and key
+ const cert = fs.readFileSync(`${__dirname}/ssl/x509/client.pem`);
+ const key = fs.readFileSync(`${__dirname}/ssl/x509/client.pem`);
+
+ // User name
+ const userName = encodeURIComponent('CN=client,OU=kerneluser,O=10Gen,L=New York City,ST=New York,C=US');
+ const url = `mongodb://${userName}:${password}@server:27017?authMechanism=MONGODB-X509&ssl=true`;
+
+ // Create a new MongoClient
+ const client = new MongoClient(url, {
+ sslKey: key,
+ sslCert: cert,
+ sslValidate: false
+ });
+
+ // Function to connect to the server
+ 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();
+
+For more information on connecting to MongoDB instance, replica set, and sharded cluster with TLS/SSL options, see :doc:`TLS/SSL connections </tutorials/connect/tls>` .
+
+For more information, refer to the MongoDB manual
+:manual:`X.509 tutorial </tutorial/configure-x509-client-authentication/#add-x-509-certificate-subject-as-a-user>` for more information about determining the subject name from the certificate.
+
+Kerberos (GSSAPI/SSPI)
+----------------------
+
+`MongoDB Enterprise <http://www.mongodb.com/products/mongodb-enterprise>`_ supports proxy authentication through a Kerberos service. The Node.js driver supports Kerberos on UNIX via the MIT Kerberos library and on Windows via the SSPI API.
+
+To connect using the GSSAPI authentication mechanism, specify ``authMechanism=GSSAPI`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` . Specify the user principal and the service name in the connection string. Use ``enodeURIComponent`` to encode the user principal string.
+
+The following example connects to MongoDB using Kerberos for UNIX.
+
+.. code-block:: js
+
+ const { MongoClient } = require('mongodb');
+
+ // KDC Server
+ const server = 'mongo-server.example.com';
+ const principal = 'drivers@KERBEROS.EXAMPLE.COM';
+ const urlEncodedPrincipal = encodeURIComponent(principal);
+
+ const url = `mongodb://${urlEncodedPrincipal}@${server}/?authMechanism=GSSAPI&gssapiServiceName=mongodb`;
+
+ const client = new MongoClient(url);
+
+ // Function to connect to the server
+ 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();
+
+.. note::
+ The method refers to the ``GSSAPI`` authentication mechanism instead of ``Kerberos`` because technically the driver authenticates via the :rfc:`GSSAPI <4752>` SASL mechanism.
+
+LDAP (PLAIN)
+------------
+
+`MongoDB Enterprise <http://www.mongodb.com/products/mongodb-enterprise>`_ supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service.
+
+To connect using the LDAP authentication mechanism, specify ``authMechanism=PLAIN`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` .
+
+.. code-block:: js
+
+ const { MongoClient } = require('mongodb');
+
+ // LDAP Server
+ const server = 'ldap.example.com';
+ const user = 'ldap-user';
+ const pass = 'ldap-password';
+
+ // Url
+ const url = `mongodb://${user}:${pass}@${server}?authMechanism=PLAIN&maxPoolSize=1`;
+
+ // Client
+ const client = new MongoClient(url);
+
+ // Function to connect to the server
+ 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();
+
+.. note::
+ The method refers to the ``PLAIN`` authentication mechanism instead of ``LDAP`` because technically the driver authenticates via the :rfc:`PLAIN <4616>` SASL mechanism.