diff --git a/source/fundamentals/authentication.txt b/source/fundamentals/authentication.txt index fe07df164..de0fc31b0 100644 --- a/source/fundamentals/authentication.txt +++ b/source/fundamentals/authentication.txt @@ -35,6 +35,7 @@ Enterprise Edition which includes: - ``Kerberos (GSSAPI/SSPI)`` - ``LDAP (PLAIN)`` +- ``MONGODB-OIDC`` .. note:: For instructions on MongoDB driver installation and deployment setup, see diff --git a/source/fundamentals/authentication/enterprise-mechanisms.txt b/source/fundamentals/authentication/enterprise-mechanisms.txt index 91e9faade..ba5aeae84 100644 --- a/source/fundamentals/authentication/enterprise-mechanisms.txt +++ b/source/fundamentals/authentication/enterprise-mechanisms.txt @@ -10,9 +10,16 @@ Enterprise Authentication Mechanisms :depth: 1 :class: singlecol +.. 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)`` and ``LDAP (PLAIN)``. +``Kerberos (GSSAPI/SSPI)``, ``LDAP (PLAIN)``, and ``MONGODB-OIDC``. ``Kerberos (GSSAPI/SSPI)`` -------------------------- @@ -138,3 +145,209 @@ in the following sample code. 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 `_. + +MONGODB-OIDC +------------ + +.. important:: + + 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. + +For more information about the MONGODB-OIDC authentication mechanism, see +:manual:`OpenID Connect Authentication ` and +:manual:`MongoDB Server Parameters ` +in the {+mdb-server+} manual. + +.. _node-mongodb-oidc-azure-imds: + +Azure IMDS +~~~~~~~~~~ + +If your application runs on an Azure VM, or otherwise uses the +`Azure Instance Metadata Service `__ +(IMDS), you can authenticate to MongoDB by using the {+driver-short+}'s built-in Azure +support. + +To specify Azure IMDS OIDC as the authentication mechanism, set the following options +in your connection string: + +- ``username``: If you're using an Azure managed identity, set this to the client ID + of the managed identity. If you're using a service principal to represent an + enterprise application, set this to the application ID of the service principal. + Otherwise, omit this option. +- ``authMechanism``: Set to ``MONGODB-OIDC``. +- ``authMechanismProperties``: Set to + ``ENVIRONMENT:azure,TOKEN_RESOURCE:``. + Replace the ```` placeholder with the + value of the ``audience`` parameter configured on your MongoDB deployment. + +The following code example shows how to set the preceding connection options: + +.. code-block:: js + :emphasize-lines: 3-4 + + const { MongoClient } = require("mongodb"); + + const uri = "mongodb+srv://@:/?authMechanism=MONGODB-OIDC" + + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:"; + const client = new MongoClient(uri); + +.. _node-mongodb-oidc-gcp-imds: + +GCP IMDS +~~~~~~~~ + +If your application runs on a Google Compute Engine VM, or otherwise uses the +`GCP Instance Metadata Service `__, +you can authenticate to MongoDB by using the {+driver-short+}'s built-in GCP +support. + +To specify GCP IMDS OIDC as the authentication mechanism, set the following options +in your connection string: + +- ``authMechanism``: Set to ``MONGODB-OIDC``. +- ``authMechanismProperties``: Set to + ``ENVIRONMENT:gcp,TOKEN_RESOURCE:``. + Replace the ```` placeholder with the + value of the ``audience`` parameter configured on your MongoDB deployment. + +The following code example shows how to set the preceding connection options: + +.. code-block:: js + :emphasize-lines: 3-4 + + const { MongoClient } = require("mongodb"); + + const uri = "mongodb+srv://:/?authMechanism=MONGODB-OIDC" + + "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:"; + const client = new MongoClient(uri); + +Custom Callback +~~~~~~~~~~~~~~~ + +The {+driver-short+} doesn't offer built-in support for all platforms, including +Azure Functions and Azure Kubernetes Service (AKS). Instead, you +must define a custom callback to use OIDC to authenticate from these platforms. + +First, define a function that retrieves the access token to use for OIDC authentication. +This function must have the following signature: + +.. code-block:: js + + const myCallback = (params: OIDCCallbackParams): Promise => { } + +The ``OIDCCallbackParams`` parameter contains the following properties, which you can +access inside the function: + +.. list-table:: + :header-rows: 1 + + * - Property + - Value + * - ``timeoutContext`` + - An ``AbortSignal`` that aborts the authentication workflow after 30 seconds + * - ``version`` + - The current OIDC API version + * - ``idpInfo`` + - The identity-provider information returned from the server + * - ``username`` + - The username included in the connection string, if any + * - ``refreshToken`` + - The refresh token to request a new access token from the issuer, if any + +The callback function must return an ``OIDCResponse`` object. This object contains the +following properties: + +.. list-table:: + :header-rows: 1 + + * - Property + - Value + * - ``accessToken`` + - The access token to use for authentication. + * - ``expiresInSeconds`` + - *Optional.* The number of seconds until the access token expires. + * - ``refreshToken`` + - *Optional.* The refresh token to request a new access token from the issuer. + +The following example shows a callback function that retrieves an OIDC access token +from a file named ``access-token.dat`` in the local file system: + +.. code-block:: js + + const fs = require("node:fs"); + + const myCallback = (params: OIDCCallbackParams): Promise => { + const token = fs.readFileSync("access-token.dat", "utf8"); + + return { + accessToken: token, + expiresInSeconds: 300, + refreshToken: token + }; + } + +After you define your callback function, pass it to the ``MongoClient`` constructor +as part of the ``authMechanismProperties`` parameter. The {+driver-short+} supports +the following authentication patterns: + +- **Machine authentication:** Used by web services and other applications that require + no human interaction. Select the :guilabel:`Machine Callback` tab to see an example of + this syntax. +- **Human authentication:** Used by database tools, command-line utilities, and other + applications that involve direct human interaction. Select the :guilabel:`Human Callback` + tab to see an example of this syntax. + +.. tabs:: + + .. tab:: Machine Callback + :tabid: machine-callback + + For machine authentication, assign the callback function to the + ``authMechanismProperties.OIDC_CALLBACK`` property, as shown in the following + example: + + .. code-block:: js + :emphasize-lines: 4-7 + + const { MongoClient } = require("mongodb"); + + const uri = "mongodb+srv://:/?authMechanism=MONGODB-OIDC"; + const client = new MongoClient(uri, { + authMechanismProperties: { + OIDC_CALLBACK: myCallback + } + }); + + .. tab:: Human Callback + :tabid: human-callback + + For human authentication, assign the callback function to the + ``authMechanismProperties.OIDC_HUMAN_CALLBACK`` property, as shown in the following + example: + + .. code-block:: js + :emphasize-lines: 4-7 + + const { MongoClient } = require("mongodb"); + + const uri = "mongodb+srv://:/?authMechanism=MONGODB-OIDC"; + const client = new MongoClient(uri, { + authMechanismProperties: { + OIDC_HUMAN_CALLBACK: myCallback + } + }); + +API Documentation +----------------- + +To learn more about the methods and types discussed in this +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