diff --git a/config/redirects b/config/redirects index a02dfd519..da2a51732 100644 --- a/config/redirects +++ b/config/redirects @@ -83,3 +83,5 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/crud/update/embedded-arrays/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/pkFactory/ -> ${base}/crud/pkFactory/ +# Comprehensive Coverage Redirects +[*-master]: ${prefix}/${version}/security/authentication/enterprise-mechanisms/ -> ${base}/security/authentication diff --git a/source/code-snippets/authentication/aws-env-variable.js b/source/code-snippets/authentication/aws-env-variable.js index 3533a04fc..f8e93fd31 100644 --- a/source/code-snippets/authentication/aws-env-variable.js +++ b/source/code-snippets/authentication/aws-env-variable.js @@ -1,7 +1,7 @@ const { MongoClient } = require("mongodb"); // Remember to specify your AWS credentials in environment variables. -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "MONGODB-AWS"; let uri = diff --git a/source/code-snippets/authentication/aws.js b/source/code-snippets/authentication/aws.js index da158e5b4..2033c009d 100644 --- a/source/code-snippets/authentication/aws.js +++ b/source/code-snippets/authentication/aws.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const accessKeyId = encodeURIComponent(""); const secretAccessKey = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "MONGODB-AWS"; diff --git a/source/code-snippets/authentication/cr.js b/source/code-snippets/authentication/cr.js index 0c8605c13..109a871f6 100644 --- a/source/code-snippets/authentication/cr.js +++ b/source/code-snippets/authentication/cr.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; // Replace the following with your MongoDB deployment's connection string. const uri = diff --git a/source/code-snippets/authentication/default.js b/source/code-snippets/authentication/default.js index b8c60c882..30f18a2f5 100644 --- a/source/code-snippets/authentication/default.js +++ b/source/code-snippets/authentication/default.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "DEFAULT"; diff --git a/source/code-snippets/authentication/sha1.js b/source/code-snippets/authentication/sha1.js index 32dc9fd33..7b932bc79 100644 --- a/source/code-snippets/authentication/sha1.js +++ b/source/code-snippets/authentication/sha1.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "SCRAM-SHA-1"; diff --git a/source/code-snippets/authentication/sha256.js b/source/code-snippets/authentication/sha256.js index 86dfbb499..e44ea9046 100644 --- a/source/code-snippets/authentication/sha256.js +++ b/source/code-snippets/authentication/sha256.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "SCRAM-SHA-256"; diff --git a/source/code-snippets/authentication/x509.js b/source/code-snippets/authentication/x509.js index fffe07529..224a865b5 100644 --- a/source/code-snippets/authentication/x509.js +++ b/source/code-snippets/authentication/x509.js @@ -1,8 +1,8 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. -const clusterUrl = ""; -const clientPEMFile = encodeURIComponent(""); +const clusterUrl = ""; +const clientPEMFile = encodeURIComponent(""); const authMechanism = "MONGODB-X509"; diff --git a/source/connect.txt b/source/connect.txt index 55526a6ec..7ef488cca 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -57,5 +57,4 @@ Compatibility .. include:: /includes/fact-atlas-link.rst For information about authenticating to MongoDB, -see :ref:`node-authentication-mechanisms` and -:ref:`node-enterprise-authentication-mechanisms`. +see the :ref:`Authentication Mechanisms ` section. diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 0f111900e..92b71e2b6 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -52,7 +52,7 @@ string, see :manual:`Connection Strings ` in the - Specifies the authentication mechanism method to use for connection to the server. If you do not specify a value, the driver uses the default mechanism, either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256`` depending on the server version. See - :ref:`authentication mechanism ` for available + the :ref:`Authentication Mechanisms ` section for available authentication mechanisms. * - **authMechanismProperties** diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index 0aec80eea..9d497e2af 100644 --- a/source/reference/release-notes.txt +++ b/source/reference/release-notes.txt @@ -155,8 +155,7 @@ The {+driver-short+} v6.11 release includes the following features: releases. - Adds OIDC authentication support for Kubernetes environments. To learn - more about this feature, see the :ref:`node-enterprise-auth-oidc` - section of the Enterprise Authentication Mechanisms guide. + more about this feature, see the :ref:`node-authentication-oidc` guide. To use OIDC to authenticate from a Kubernetes environment, set the ``authMechanismProperties`` connection option to ``ENVIRONMENT:k8s`` @@ -629,7 +628,7 @@ The {+driver-short+} v6.1 release includes the following features: To learn how to set region settings when using the ``MONGODB-AWS`` authentication mechanism, see the :guilabel:`Web Identity Token` tab in the - :ref:`MONGODB-AWS ` section of the Authentication Mechanisms guide. + :ref:`AWS IAM Authentication Mechanism ` guide. - Fixes a memory leak issue caused by recursive calls to the ``next()`` method of the ``ChangeStream`` type. diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 99fbec390..f1c8e8d5c 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -1,44 +1,70 @@ .. _node-authentication-mechanisms: .. _node-authentication: -============== -Authentication -============== +========================= +Authentication Mechanisms +========================= .. default-domain:: mongodb .. toctree:: - Authentication - Enterprise Authentication + SCRAM + X.509 + AWS IAM + OIDC + LDAP (PLAIN) + Kerberos (GSSAPI) Overview -------- -These guides show you how to authenticate to a MongoDB instance using the -Node.js driver. - -The :doc:`Authentication Mechanisms ` guide contains -sample connection code using each authentication mechanism supported in the -MongoDB Community Edition which includes: - -- ``DEFAULT`` -- ``SCRAM-SHA-256`` -- ``SCRAM-SHA-1`` -- ``MONGODB-CR`` -- ``MONGODB-AWS`` -- ``X.509`` - -The :doc:`Enterprise Authentication Mechanisms -` guide contains sample -connection code using authentication mechanisms available only in MongoDB -Enterprise Edition which includes: - -- ``Kerberos (GSSAPI/SSPI)`` -- ``LDAP (PLAIN)`` -- ``MONGODB-OIDC`` - -.. note:: - For instructions on MongoDB driver installation and deployment setup, see - our :guides:`Connect to MongoDB guide `. Select your - MongoDB deployment type and the Node.js client. +In this guide, you can learn how to authenticate to MongoDB by using the +**authentication mechanisms** available in {+mdb-server+}. +Authentication mechanisms are processes by which the driver and server confirm +the identity of a client to ensure security before connecting. + +.. tip:: Connecting to MongoDB + + To learn how to establish a connection to your MongoDB deployment, see the + :ref:`node-connect` guide. + +MongoDB Edition Compatibility +----------------------------- + +The following table lists the authentication mechanisms supported by MongoDB and +the {+mdb-server+} editions that each mechanism is compatible with. Click the name of +a mechanism to learn more about how to use it with your application. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - Authentication Mechanism + - Atlas + - Enterprise Advanced + - Community + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - No + - No + * - :ref:`` + - Yes + - Yes + - No + * - :ref:`` + - Yes + - Yes + - No + * - :ref:`` + - No + - Yes + - No diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt new file mode 100644 index 000000000..0288200c6 --- /dev/null +++ b/source/security/authentication/aws-iam.txt @@ -0,0 +1,186 @@ +.. _node-authentication-aws: + +================================ +AWS IAM Authentication Mechanism +================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: atlas, amazon web services, code example + +Overview +-------- + +The ``MONGODB-AWS`` authentication mechanism uses Amazon Web Services +Identity and Access Management (AWS IAM) credentials to authenticate a user to MongoDB. +You can use this mechanism only when authenticating to MongoDB Atlas. + +.. tip:: Configure Atlas for AWS IAM Authentication + + To learn more about configuring MongoDB Atlas for AWS IAM authentication, see + :atlas:`Set Up Authentication with AWS IAM ` in + the Atlas documentation. + +Specify MONGODB-AWS Authentication +---------------------------------- + +The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services +Identity and Access Management (AWS IAM) credentials to authenticate your +user. If you do not already have the `AWS signature library +`__, use the following +``npm`` command to install it: + +.. code-block:: bash + + npm install aws4 + +To connect to a MongoDB instance with ``MONGODB-AWS`` authentication +enabled, specify the ``MONGODB-AWS`` authentication mechanism. + +The driver checks for your credentials in the following sources in order: + +1. Connection string +#. Environment variables +#. Web identity token file +#. AWS ECS endpoint specified in ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`` +#. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks + `_. + +.. important:: + + The driver only reads the credentials from the first method that it detects + in the order as given by the preceding list. For example, if you specify + your AWS credentials in the connection string, the driver ignores any + credentials that you specified in environment variables. + +.. tabs:: + + .. tab:: Connection String + :tabid: connection string + + To connect to your MongoDB instance with a connection string, pass + your ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` + credentials to the driver when you attempt to connect. If your AWS + login requires a session token, include your ``AWS_SESSION_TOKEN`` as well. + + The following code shows an example of specifying the ``MONGODB-AWS`` + authentication mechanism and credentials with a connection string: + + .. important:: + + Always **URI encode** the username and certificate file path using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + + .. literalinclude:: /code-snippets/authentication/aws.js + :language: javascript + + .. tab:: Environment Variables + :tabid: environment variables + + To authenticate to your MongoDB instance using AWS credentials stored in + environment variables, set the following variables by using + a shell: + + .. code-block:: bash + + export AWS_ACCESS_KEY_ID= + export AWS_SECRET_ACCESS_KEY= + export AWS_SESSION_TOKEN= + + .. note:: + + Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS + session token for that role. + + After you've set the preceding environment variables, specify the ``MONGODB-AWS`` + authentication mechanism in your connection string as shown in the following example: + + .. literalinclude:: /code-snippets/authentication/aws-env-variable.js + :language: javascript + + .. tab:: Web Identity Token File + :tabid: web-identity-token-file + + You can use the OpenID Connect (OIDC) token obtained from a web identity + provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or + other services. + + To authenticate with your OIDC token you must first install + `@aws-sdk/credential-providers + `__. You can + install this dependency using the following ``npm`` command: + + .. code-block:: bash + + npm install @aws-sdk/credential-providers + + Next, create a file that contains your OIDC token. Then + set the absolute path to this file in an environment variable by using + a shell as shown in the following example: + + .. code-block:: bash + + export AWS_WEB_IDENTITY_TOKEN_FILE= + + AWS recommends using regional AWS STS endpoints instead of global + endpoints to reduce latency, build-in redundancy, and increase session token validity. + To set the AWS region, set `AWS_REGION `__ + and `AWS_STS_REGIONAL_ENDPOINTS `__ + as environment variables, as shown in the following example: + + .. code-block:: bash + + export AWS_STS_REGIONAL_ENDPOINTS=regional // Enables regional endpoints + export AWS_REGION=us-east-1 // Sets your AWS region + + If both these environment variables aren't set, the default region is + ``us-east-1``. For a list of available AWS regions, see the + `Regional Endpoints `__ + section of the AWS Service Endpoints reference in the AWS documentation. + + .. warning:: Consult your SDK's Documentation for Setting an AWS Region + + You cannot set your AWS region with environment variables for all SDKs, + as in the above example. See your SDK's specific documentation for + configuring an AWS region. + + After you've set the preceding environment variables, specify the ``MONGODB-AWS`` + authentication mechanism in your connection string as shown in the following example: + + .. literalinclude:: /code-snippets/authentication/aws-env-variable.js + :language: javascript + +.. important:: Retrieval of AWS Credentials + + Starting in MongoDB version 4.11, when you install the optional + ``aws-sdk/credential-providers`` dependency, the driver uses the AWS SDK + to retrieve credentials from the environment. As a result, if you + have a shared AWS credentials file or config file, the driver will + use those credentials by default. + + You can override this behavior by performing one of the following + actions: + + - Set ``AWS_SHARED_CREDENTIALS_FILE`` variable in your shell to point + to your credentials file. + - Set the equivalent environment variable in your application to point + to your credentials file. + - Create an AWS profile for your MongoDB credentials and set the + ``AWS_PROFILE`` environment variable to that profile name. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/kerberos.txt b/source/security/authentication/kerberos.txt new file mode 100644 index 000000000..3b7c98f27 --- /dev/null +++ b/source/security/authentication/kerberos.txt @@ -0,0 +1,114 @@ +.. _node-authentication-kerberos: + +========================================== +Kerberos (GSSAPI) Authentication Mechanism +========================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example + +Overview +-------- + +The Generic Security Services API (GSSAPI) authentication mechanism allows you to +use your principal name to authenticate to a Kerberos service. +You can use this mechanism only when authenticating to MongoDB Enterprise Advanced. + +Specify Kerberos (GSSAPI) Authentication +---------------------------------------- + +.. note:: + The Node.js driver supports Kerberos on UNIX using the MIT Kerberos library + and on Windows using the SSPI API. + +The ``GSSAPI`` authentication mechanism uses your user principal to +authenticate to a Kerberos service. + +You can specify this authentication mechanism by performing the +following actions while specifying options on your +:manual:`connection string `: + +- Set the ``authMechanism`` parameter to ``GSSAPI``. +- Set the ``SERVICE_NAME`` value in the ``authMechanismProperties`` + parameter if using a value other than ``mongodb``. +- Specify a ``SERVICE_REALM`` value in the ``authMechanismProperties`` + parameter if a custom service realm is required. +- Specify a ``CANONICALIZE_HOST_NAME`` value in the ``authMechanismProperties`` + parameter if canonicalization of the hostname is required. This property accepts + the following values: + + - ``none``: (Default) Does not perform hostname canonicalization + - ``forward``: Performs a forward DNS lookup to canonicalize the hostname + - ``forwardAndReverse``: Performs a forward DNS lookup and then a + reverse lookup on that value to canonicalize the hostname + +.. important:: + + The ``gssapiServiceName`` parameter is deprecated and may be removed + in future versions of the driver. Use + ``authMechanismProperties=SERVICE_NAME:`` in the + connection URI instead. + To learn more about the authentication options for a connection string, see the + :manual:`Authentication Options ` + section of the Connection String Options reference in the Server Manual. + +The following code example authenticates to Kerberos for UNIX using ``GSSAPI``. + +.. important:: + Always **URI encode** the principal using the ``encodeURIComponent`` method + to ensure it is correctly parsed. + +.. code-block:: js + + const { MongoClient } = require("mongodb"); + + // Replace the placeholder values with the values for your environment in the following lines + const clusterUrl = ""; + const principal = encodeURIComponent(""); + const serviceRealm = ""; + const canonicalizationSetting = ""; + const authMechanismProperties = `SERVICE_REALM:${serviceRealm},CANONICALIZE_HOST_NAME:${canonicalizationSetting}`; + + const authMechanism = "GSSAPI"; + + // Connection URI + const uri = `mongodb+srv://${principal}@${clusterUrl}/?authMechanism=${authMechanism}&authMechanismProperties=${authMechanismProperties}`; + + const client = new MongoClient(uri); + + // Function to connect to the server + async function run() { + try { + // Establish and verify connection + await client.db("admin").command({ ping: 1 }); + console.log("Connected successfully to server"); + } finally { + // Ensures that the client will close when you finish/error + await client.close(); + } + } + run().catch(console.dir); + +.. note:: + The method refers to the ``GSSAPI`` authentication mechanism instead + of ``Kerberos`` because the driver authenticates through + `GSSAPI RFC-4652 `_, the SASL + mechanism. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/ldap.txt b/source/security/authentication/ldap.txt new file mode 100644 index 000000000..8d2ec793e --- /dev/null +++ b/source/security/authentication/ldap.txt @@ -0,0 +1,87 @@ +.. _node-authentication-ldap: + +===================================== +LDAP (PLAIN) Authentication Mechanism +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example + +Overview +-------- + +The ``PLAIN`` authentication mechanism allows you to use your Lightweight Directory +Access Protocol (LDAP) username and password to authenticate to MongoDB. LDAP +authentication uses the PLAIN Simple Authentication and Security Layer (SASL) +defined in `RFC-4616 `__. + +You can use this mechanism only when authenticating to MongoDB Atlas or MongoDB +Enterprise Advanced. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: Your LDAP username. +- ````: Your LDAP password. +- ````: The network address of your MongoDB deployment. + +To use the code examples, replace these placeholders with your own values. + +LDAP (PLAIN) +------------ + +The ``PLAIN`` authentication mechanism uses your username and password to +authenticate to an LDAP server. + +You can specify this authentication mechanism by setting the ``authMechanism`` +parameter to ``PLAIN`` and including your LDAP username and password in the +:manual:`connection string ` as shown +in the following sample code. + +.. code-block:: js + + const { MongoClient } = require("mongodb"); + + // specify the placeholder values for your environment in the following lines + const clusterUrl = ""; + const ldapUsername = ""; + const ldapPassword = ""; + const authMechanism = "PLAIN"; + + // Connection URI + const uri = `mongodb+srv://${ldapUsername}:${ldapPassword}@${clusterUrl}/?authMechanism=${authMechanism}`; + + const client = new MongoClient(uri); + + // Function to connect to the server + async function run() { + try { + // Establish and verify connection + await client.db("admin").command({ ping: 1 }); + console.log("Connected successfully to server"); + } finally { + // Ensures that the client will close when you finish/error + await client.close(); + } + } + run().catch(console.dir); + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/mechanisms.txt b/source/security/authentication/mechanisms.txt deleted file mode 100644 index b4b6a681d..000000000 --- a/source/security/authentication/mechanisms.txt +++ /dev/null @@ -1,366 +0,0 @@ -.. _node-community-authentication-mechanisms: - -========================= -Authentication Mechanisms -========================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -In this guide, you can find sample code for connection to MongoDB with each -authentication mechanism available in the MongoDB Community Edition: -``DEFAULT``, ``SCRAM-SHA-256``, ``SCRAM-SHA-1``, ``MONGODB-CR``, -``MONGODB-AWS``, and ``X.509``. - -``DEFAULT`` ------------ - -The ``DEFAULT`` authentication mechanism is a fallback setting that instructs -the driver to negotiate the first authentication mechanism supported by the -server in the following order of preference: - -#. ``SCRAM-SHA-256`` -#. ``SCRAM-SHA-1`` -#. ``MONGODB-CR`` - -If the ``DEFAULT`` option is specified, the driver first attempts to -authenticate using ``SCRAM-SHA-256``. If the version of the MongoDB instance -does not support that mechanism, the driver attempts to authenticate using -``SCRAM-SHA-1``. If the instance does not support that mechanism either, -the driver attempts to authenticate using ``MONGODB-CR``. - -You can specify this authentication mechanism by setting the ``authMechanism`` -parameter to ``DEFAULT`` in the -:manual:`connection string `, or by omitting -the parameter since it is the default value. Also include your username and -password as shown in the code below. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/default.js - :language: javascript - -For more information on the challenge-response (CR) and salted -challenge-response authentication mechanisms (SCRAM) that MongoDB supports, -see the :manual:`SCRAM ` section of the manual. - -``SCRAM-SHA-256`` ------------------ - -.. note:: - - ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting - in version 4.0 - -``SCRAM-SHA-256`` is a salted challenge-response authentication mechanism -(SCRAM) that uses your username and password, encrypted with the ``SHA-256`` -algorithm to authenticate your user. - -You can specify this authentication mechanism by setting the ``authMechanism`` -to the value ``SCRAM-SHA-256`` in the -:manual:`connection string ` as shown in the -following sample code. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/sha256.js - :language: javascript - -``SCRAM-SHA-1`` ---------------- - -.. note:: - ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions - 3.0, 3.2, 3.4, and 3.6. - -``SCRAM-SHA-1`` is a salted challenge-response mechanism (SCRAM) that uses your -username and password, encrypted with the ``SHA-1`` algorithm to authenticate -your user. - -You can specify this authentication mechanism by setting the ``authMechanism`` -parameter to the value ``SCRAM-SHA-1`` in the -:manual:`connection string ` as shown -in the following sample code. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/sha1.js - :language: javascript - -``MONGODB-CR`` --------------- - -.. warning:: - MONGODB-CR was deprecated starting in MongoDB 3.6, and is no longer supported as of MongoDB 4.0 - -``MONGODB-CR`` is a challenge-response authentication mechanism that uses your -username and password to authenticate your user. - -You can specify this option by setting the ``authMechanism`` parameter to value -``MONGODB-CR`` in the -:manual:`connection string ` as shown -in the following sample code. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/cr.js - :language: javascript - -.. important:: - If you have upgraded the authentication schema from MONGODB-CR to SCRAM, - any ``MONGODB-CR`` user authentication requests fail. - -.. _mongodb-aws: - -``MONGODB-AWS`` ---------------- - -.. note:: - The MONGODB-AWS authentication mechanism is available only in MongoDB - versions 4.4 and later. - -The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services -Identity and Access Management (AWS IAM) credentials to authenticate your -user. If you do not already have the `AWS signature library -`__, use the following -``npm`` command to install it: - -.. code-block:: bash - - npm install aws4 - -To connect to a MongoDB instance with ``MONGODB-AWS`` authentication -enabled, specify the ``MONGODB-AWS`` authentication mechanism. - -The driver checks for your credentials in the following sources in order: - -1. Connection string -#. Environment variables -#. Web identity token file -#. AWS ECS endpoint specified in ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`` -#. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks - `_. - -.. important:: - - The driver only reads the credentials from the first method that it detects - in the order as given by the preceding list. For example, if you specify - your AWS credentials in the connection string, the driver ignores any - credentials that you specified in environment variables. - -.. tabs:: - - .. tab:: Connection String - :tabid: connection string - - To connect to your MongoDB instance with a connection string, pass - your ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` - credentials to the driver when you attempt to connect. If your AWS - login requires a session token, include your ``AWS_SESSION_TOKEN`` as well. - - The following code shows an example of specifying the ``MONGODB-AWS`` - authentication mechanism and credentials with a connection string: - - .. important:: - - Always **URI encode** the username and certificate file path using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - - .. literalinclude:: /code-snippets/authentication/aws.js - :language: javascript - - .. tab:: Environment Variables - :tabid: environment variables - - To authenticate to your MongoDB instance using AWS credentials stored in - environment variables, set the following variables by using - a shell: - - .. code-block:: bash - - export AWS_ACCESS_KEY_ID= - export AWS_SECRET_ACCESS_KEY= - export AWS_SESSION_TOKEN= - - .. note:: - - Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS - session token for that role. - - After you've set the preceding environment variables, specify the ``MONGODB-AWS`` - authentication mechanism in your connection string as shown in the following example: - - .. literalinclude:: /code-snippets/authentication/aws-env-variable.js - :language: javascript - - .. tab:: Web Identity Token File - :tabid: web-identity-token-file - - You can use the OpenID Connect (OIDC) token obtained from a web identity - provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or - other services. - - To authenticate with your OIDC token you must first install - `@aws-sdk/credential-providers - `__. You can - install this dependency using the following ``npm`` command: - - .. code-block:: bash - - npm install @aws-sdk/credential-providers - - Next, create a file that contains your OIDC token. Then - set the absolute path to this file in an environment variable by using - a shell as shown in the following example: - - .. code-block:: bash - - export AWS_WEB_IDENTITY_TOKEN_FILE= - - AWS recommends using regional AWS STS endpoints instead of global - endpoints to reduce latency, build-in redundancy, and increase session token validity. - To set the AWS region, set `AWS_REGION `__ - and `AWS_STS_REGIONAL_ENDPOINTS `__ - as environment variables, as shown in the following example: - - .. code-block:: bash - - export AWS_STS_REGIONAL_ENDPOINTS=regional // Enables regional endpoints - export AWS_REGION=us-east-1 // Sets your AWS region - - If both these environment variables aren't set, the default region is - ``us-east-1``. For a list of available AWS regions, see the - `Regional Endpoints `__ - section of the AWS Service Endpoints reference in the AWS documentation. - - .. warning:: Consult your SDK's Documentation for Setting an AWS Region - - You cannot set your AWS region with environment variables for all SDKs, - as in the above example. See your SDK's specific documentation for - configuring an AWS region. - - After you've set the preceding environment variables, specify the ``MONGODB-AWS`` - authentication mechanism in your connection string as shown in the following example: - - .. literalinclude:: /code-snippets/authentication/aws-env-variable.js - :language: javascript - -.. important:: Retrieval of AWS Credentials - - Starting in version 4.11, when you install the optional - ``aws-sdk/credential-providers`` dependency, the driver uses the AWS SDK - to retrieve credentials from the environment. As a result, if you - have a shared AWS credentials file or config file, the driver will - use those credentials by default. - - You can override this behavior by performing one of the following - actions: - - - Set ``AWS_SHARED_CREDENTIALS_FILE`` variable in your shell to point - to your credentials file. - - Set the equivalent environment variable in your application to point - to your credentials file. - - Create an AWS profile for your MongoDB credentials and set the - ``AWS_PROFILE`` environment variable to that profile name. - -``X.509`` ---------- - -.. note:: - The X.509 authentication mechanism is only available in MongoDB versions - 2.6 and later. - -The ``X.509`` authentication mechanism uses -:wikipedia:`TLS ` with X.509 certificates to -authenticate by retrieving the distinguished name (DN) from the -client certificate. - -You can specify this authentication mechanism by setting the following -parameters of your :manual:`connection string `: - -- Set the ``authMechanism`` parameter to ``MONGODB-X509`` -- Set the ``tls`` parameter to ``true`` - -Pass the location of your client certificate file as the value of -``tlsCertificateKeyFile`` as a parameter of the connection URI. - -.. important:: - Always **URI encode** the certificate file path using the - ``encodeURIComponent`` method to ensure it is parsed correctly. - -.. literalinclude:: /code-snippets/authentication/x509.js - :language: javascript - -.. tip:: - - To learn more about enabling TLS on a connection, see - :ref:`node-connect-tls`. - -TLS Options -~~~~~~~~~~~ - -The following table describes the TLS options that you can set in a -connection URI. - -.. list-table:: - :widths: 35 12 10 43 - :header-rows: 1 - - * - Parameter Name - - Type - - Default Value - - Description - - * - ``tls`` - - boolean - - ``false`` - - Specifies whether to enable TLS on the connection. - - * - ``tlsInsecure`` - - boolean - - ``false`` - - Specifies whether to allow invalid certificates and mismatched - hostnames. When set to ``true``, this is equivalent to setting - ``tlsAllowInvalidCertificates`` and ``tlsAllowInvalidHostnames`` to - ``true``. - - * - ``tlsCAFile`` - - string - - - - Path to file that contains a single or bundle of trusted certificate - authorities used in a TLS connection. - - * - ``tlsCertificateKeyFile`` - - string - - - - Path to the client certificate file or the client private key file. If - both are required, the two must be concatenated into a single file. - - * - ``tlsCertificateKeyFilePassword`` - - buffer or string - - - - String or buffer that contains the password to decrypt the client - private key. - - * - ``tlsAllowInvalidCertificates`` - - boolean - - ``false`` - - Specifies whether the driver permits an invalid certificate to be used - to connect. - - * - ``tlsAllowInvalidHostnames`` - - boolean - - ``false`` - - Specifies whether the driver raises an error when there is a mismatch between the - server hostname and TLS certificate hostname. diff --git a/source/security/authentication/enterprise-mechanisms.txt b/source/security/authentication/oidc.txt similarity index 55% rename from source/security/authentication/enterprise-mechanisms.txt rename to source/security/authentication/oidc.txt index 750b79934..e08c666f4 100644 --- a/source/security/authentication/enterprise-mechanisms.txt +++ b/source/security/authentication/oidc.txt @@ -1,8 +1,8 @@ -.. _node-enterprise-authentication-mechanisms: +.. _node-authentication-oidc: -==================================== -Enterprise Authentication Mechanisms -==================================== +============================= +OIDC Authentication Mechanism +============================= .. contents:: On this page :local: @@ -13,156 +13,38 @@ Enterprise Authentication Mechanisms .. facet:: :name: genre :values: reference - -.. meta:: - :keywords: ldap, encryption, principal, tls - -In this guide, you can find sample code for connection to MongoDB with each -authentication mechanism available in the MongoDB Enterprise Edition: -``Kerberos (GSSAPI/SSPI)``, ``LDAP (PLAIN)``, and ``MONGODB-OIDC``. - -Kerberos (GSSAPI/SSPI) ----------------------- -.. note:: - The Node.js driver supports Kerberos on UNIX using the MIT Kerberos library - and on Windows using the SSPI API. +.. meta:: + :keywords: code example -The ``GSSAPI`` authentication mechanism uses your user principal to -authenticate to a Kerberos service. +Overview +-------- -You can specify this authentication mechanism by performing the -following actions while specifying options on your -:manual:`connection string `: +The OpenID Connect (OIDC) authentication mechanism allows you to authenticate to +MongoDB by using a third-party identity provider, such as Azure or Google Cloud +Platform (GCP). -- Set the ``authMechanism`` parameter to ``GSSAPI``. -- Set the ``SERVICE_NAME`` value in the ``authMechanismProperties`` - parameter if using a value other than ``mongodb``. -- Specify a ``SERVICE_REALM`` value in the ``authMechanismProperties`` - parameter if a custom service realm is required. -- Specify a ``CANONICALIZE_HOST_NAME`` value in the ``authMechanismProperties`` - parameter if canonicalization of the hostname is required. This property can take - the following values: +The MONGODB-OIDC authentication mechanism requires {+mdb-server+} v7.0 or later running +on a Linux platform. You can use this mechanism only when authenticating to MongoDB Atlas +or MongoDB Enterprise Advanced. - - ``none``: (Default) Does not perform hostname canonicalization - - ``forward``: Performs a forward DNS lookup to canonicalize the hostname - - ``forwardAndReverse``: Performs a forward DNS lookup and then a - reverse lookup on that value to canonicalize the hostname +.. tip:: Learn More about OIDC Authentication -.. important:: + To learn more about configuring MongoDB Atlas for OIDC authentication, see + :atlas:`Set up Workforce Identity Federation with OIDC ` + in the Atlas documentation. - The ``gssapiServiceName`` parameter is deprecated and may be removed - in future versions of the driver. Use - ``authMechanismProperties=SERVICE_NAME:`` in the - connection URI instead. - See the - :manual:`authMechanismProperties ` - parameter documentation for more information. - -The following code sample authenticates to Kerberos for UNIX using ``GSSAPI``. - -.. important:: - Always **URI encode** the principal using the ``encodeURIComponent`` method - to ensure it is correctly parsed. - -.. code-block:: js - - const { MongoClient } = require("mongodb"); - - // specify the placeholder values for your environment in the following lines - const clusterUrl = ""; - const principal = encodeURIComponent(""); - const serviceRealm = ""; - const canonicalizationSetting = ""; - const authMechanismProperties = `SERVICE_REALM:${serviceRealm},CANONICALIZE_HOST_NAME:${canonicalizationSetting}`; - - const authMechanism = "GSSAPI"; - - // Connection URI - const uri = `mongodb+srv://${principal}@${clusterUrl}/?authMechanism=${authMechanism}&authMechanismProperties=${authMechanismProperties}`; - - const client = new MongoClient(uri); - - // Function to connect to the server - async function run() { - try { - // Establish and verify connection - await client.db("admin").command({ ping: 1 }); - console.log("Connected successfully to server"); - } finally { - // Ensures that the client will close when you finish/error - await client.close(); - } - } - run().catch(console.dir); - -.. note:: - The method refers to the ``GSSAPI`` authentication mechanism instead - of ``Kerberos`` because the driver authenticates through - `GSSAPI RFC-4652 `_, the SASL - mechanism. - -LDAP (PLAIN) ------------- - -The ``PLAIN`` authentication mechanism uses your username and password to -authenticate to a Lightweight Directory Access Protocol (LDAP) server. - -You can specify this authentication mechanism by setting the ``authMechanism`` -parameter to ``PLAIN`` and including your LDAP username and password in the -:manual:`connection string ` as shown -in the following sample code. - -.. code-block:: js - - const { MongoClient } = require("mongodb"); - - // specify the placeholder values for your environment in the following lines - const clusterUrl = ""; - const ldapUsername = ""; - const ldapPassword = ""; - const authMechanism = "PLAIN"; - - // Connection URI - const uri = `mongodb+srv://${ldapUsername}:${ldapPassword}@${clusterUrl}/?authMechanism=${authMechanism}`; - - const client = new MongoClient(uri); - - // Function to connect to the server - async function run() { - try { - // Establish and verify connection - await client.db("admin").command({ ping: 1 }); - console.log("Connected successfully to server"); - } finally { - // Ensures that the client will close when you finish/error - await client.close(); - } - } - run().catch(console.dir); - -.. note:: - The authentication mechanism is named ``PLAIN`` instead of ``LDAP`` since it - authenticates using the `PLAIN Simple Authentication and Security Layer - (SASL) defined in RFC-4616 `_. - -.. _node-enterprise-auth-oidc: - -MONGODB-OIDC ------------- - -.. important:: + To learn more about using OIDC authentication with MongoDB, see + :manual:`Authentication and Authorization with OIDC/OAuth 2.0 ` and + :manual:`oidcIdentityProviders ` + in the {+mdb-server+} manual. - The MONGODB-OIDC authentication mechanism requires {+mdb-server+} v7.0 or later running - on a Linux platform. -The following sections describe how to use the MONGODB-OIDC authentication mechanism to -authenticate from various platforms. +Specify OIDC Authentication +--------------------------- -For more information about the MONGODB-OIDC authentication mechanism, see -:manual:`OpenID Connect Authentication ` and -:manual:`MongoDB Server Parameters ` -in the {+mdb-server+} manual. +The following sections describe how to use the ``MONGODB-OIDC`` authentication +mechanism to authenticate from various platforms. .. _node-mongodb-oidc-azure-imds: @@ -196,9 +78,9 @@ The following code example shows how to set the preceding connection options: const uri = "mongodb+srv://@:/?authMechanism=MONGODB-OIDC" + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:"; - const client = new MongoClient(uri); + const client = new MongoClient(uri); -.. _node-mongodb-oidc-gcp-imds: +.. _node-mongodb-oidc-gcp-imds: GCP IMDS ~~~~~~~~ @@ -375,4 +257,4 @@ guide, see the following API documentation: - `MongoClient <{+api+}/classes/MongoClient.html>`__ - `OIDCCallbackParams <{+api+}/interfaces/OIDCCallbackParams.html>`__ -- `OIDCResponse <{+api+}/interfaces/OIDCResponse.html>`__ \ No newline at end of file +- `OIDCResponse <{+api+}/interfaces/OIDCResponse.html>`__ diff --git a/source/security/authentication/scram.txt b/source/security/authentication/scram.txt new file mode 100644 index 000000000..d11fed75b --- /dev/null +++ b/source/security/authentication/scram.txt @@ -0,0 +1,141 @@ +.. _node-authentication-scram: + +=============================== +SCRAM Authentication Mechanisms +=============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: salt, default, code example + +Overview +-------- + +**Salted Challenge Response Authentication Mechanism (SCRAM)** is a family of +authentication mechanisms that use a challenge-response mechanism to authenticate +the user. SCRAM-SHA-256, which uses the SHA-256 algorithm to hash your password, is the +default authentication mechanism in {+mdb-server+} version 4.0 +and later. SCRAM-SHA-1, which uses the SHA-1 algorithm instead, is the default +authentication mechanism in {+mdb-server+} versions earlier than 4.0. + +You can use SCRAM to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: SCRAM Mechanisms + + To learn more about the SCRAM family of authentication mechanisms, see + `RFC 5802 `__ and + :wikipedia:`Salted Challenge Response Authentication Mechanism ` + on Wikipedia. + + For more information about the MongoDB implementation of SCRAM, see + :manual:`SCRAM ` in the {+mdb-server+} manual. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: The MongoDB username of the user to authenticate. +- ````: The MongoDB password of the user to authenticate. +- ````: The network address of your MongoDB deployment. + +To use the code examples, replace these placeholders with your own values. + +Default Authentication Mechanism +-------------------------------- + +The ``DEFAULT`` authentication mechanism is a fallback setting that instructs +the driver to negotiate the first authentication mechanism supported by the +server in the following order of preference: + +#. ``SCRAM-SHA-256`` +#. ``SCRAM-SHA-1`` +#. ``MONGODB-CR`` + +If the ``DEFAULT`` option is specified, the driver first attempts to +authenticate using ``SCRAM-SHA-256``. If the version of the MongoDB instance +does not support that mechanism, the driver attempts to authenticate using +``SCRAM-SHA-1``. If the instance does not support that mechanism either, +the driver attempts to authenticate using ``MONGODB-CR``. + +You can specify the default authentication mechanism by setting the +``authMechanism`` parameter to ``DEFAULT`` in the connection string, or by +omitting the parameter since it is the default value. + +The following example shows how to set the authentication mechanism to the +default by setting ``authMechanism`` to ``DEFAULT`` in the connection string: + +.. important:: + Always **URI encode** the username and password using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + +.. literalinclude:: /code-snippets/authentication/default.js + :language: javascript + +To learn more about the SCRAM version that MongoDB supports, +see the :manual:`SCRAM ` section of the {+mdb-server+} +manual. + +SCRAM-SHA-256 +------------- + +.. note:: + + ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting + in version 4.0 + +``SCRAM-SHA-256`` is a SCRAM version that uses your username and password, +encrypted with the ``SHA-256`` algorithm to authenticate your user. + +You can specify this authentication mechanism by setting the ``authMechanism`` +to the value ``SCRAM-SHA-256`` in the +:manual:`connection string ` as shown in the +following sample code. + +.. important:: + Always **URI encode** the username and password using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + +.. literalinclude:: /code-snippets/authentication/sha256.js + :language: javascript + +``SCRAM-SHA-1`` +--------------- + +.. note:: + ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions + 3.0, 3.2, 3.4, and 3.6. + +``SCRAM-SHA-1`` is a SCRAM version that uses your +username and password, encrypted with the ``SHA-1`` algorithm to authenticate +your user. + +You can specify this authentication mechanism by setting the ``authMechanism`` +parameter to the value ``SCRAM-SHA-1`` in the +:manual:`connection string ` as shown +in the following sample code. + +.. important:: + Always **URI encode** the username and password using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + +.. literalinclude:: /code-snippets/authentication/sha1.js + :language: javascript + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/x509.txt b/source/security/authentication/x509.txt new file mode 100644 index 000000000..3595f9082 --- /dev/null +++ b/source/security/authentication/x509.txt @@ -0,0 +1,122 @@ +.. _node-authentication-x509: + +============================== +X.509 Authentication Mechanism +============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: certificate, code example + +Overview +-------- + +In the **X.509** authentication mechanism, the server and client use the +:wikipedia:`TLS ` protocol to exchange X.509 public-key +certificates. You can use this mechanism to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: X.509 Mechanism + + To learn how to use TLS/SSL with the {+driver-short+}, + see the :ref:`node-tls` guide. + + For more information about X.509 certificates, see + :manual:`Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments + ` in the {+mdb-server+} manual. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: The network address of your MongoDB deployment. +- ````: The path to your client PEM certificate file. + +To use the code examples, replace these placeholders with your own values. + +Specify X.509 Authentication +---------------------------- + +You can specify this authentication mechanism by setting the following +parameters of your :manual:`connection string `: + +- Set the ``authMechanism`` parameter to ``MONGODB-X509`` +- Set the ``tls`` parameter to ``true`` + +Pass the location of your client certificate file as the value of +``tlsCertificateKeyFile`` as a parameter of the connection URI. + +.. important:: + Always **URI encode** the certificate file path using the + ``encodeURIComponent`` method to ensure it is parsed correctly. + +.. literalinclude:: /code-snippets/authentication/x509.js + :language: javascript + +TLS Options +~~~~~~~~~~~ + +The following table describes the TLS options that you can set in a +connection URI. + +.. list-table:: + :widths: 35 12 10 43 + :header-rows: 1 + + * - Parameter Name + - Type + - Default Value + - Description + + * - ``tls`` + - boolean + - ``false`` + - Specifies whether to enable TLS on the connection. + + * - ``tlsInsecure`` + - boolean + - ``false`` + - Specifies whether to allow invalid certificates and mismatched + hostnames. When set to ``true``, this is equivalent to setting + ``tlsAllowInvalidCertificates`` and ``tlsAllowInvalidHostnames`` to + ``true``. + + * - ``tlsCAFile`` + - string + - + - Path to file that contains a single or bundle of trusted certificate + authorities used in a TLS connection. + + * - ``tlsCertificateKeyFile`` + - string + - + - Path to the client certificate file or the client private key file. If + both are required, the two must be concatenated into a single file. + + * - ``tlsCertificateKeyFilePassword`` + - buffer or string + - + - String or buffer that contains the password to decrypt the client + private key. + + * - ``tlsAllowInvalidCertificates`` + - boolean + - ``false`` + - Specifies whether the driver permits an invalid certificate to be used + to connect. + + * - ``tlsAllowInvalidHostnames`` + - boolean + - ``false`` + - Specifies whether the driver raises an error when there is a mismatch between the + server hostname and TLS certificate hostname.