diff --git a/snooty.toml b/snooty.toml index 82b743182..24777abcc 100644 --- a/snooty.toml +++ b/snooty.toml @@ -12,7 +12,8 @@ toc_landing_pages = [ "/crud", "/crud/builders", "/data-formats", - "/api-documentation" + "/api-documentation", + "/security/auth" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/connection.txt b/source/connection.txt index d34dc63f2..c2b4dd595 100644 --- a/source/connection.txt +++ b/source/connection.txt @@ -28,7 +28,7 @@ Learn how to set up a connection and specify connection behavior from your application to a MongoDB deployment using the driver in the following sections: -- :ref:`Connect to MongoDB ` +- :ref:`Connect to MongoDB ` - :ref:`View a List of Connection Options ` - :ref:`Specify Connection Behavior with the MongoClient Class ` - :ref:`Enable Network Compression ` @@ -38,4 +38,4 @@ sections: - :atlas:`Connect to MongoDB Atlas from AWS Lambda ` For information about authenticating with a MongoDB instance, -see :ref:`` and :ref:``. +see the :ref:`` section. diff --git a/source/connection/connect.txt b/source/connection/connect.txt index c718c28f1..d056f043d 100644 --- a/source/connection/connect.txt +++ b/source/connection/connect.txt @@ -1,4 +1,4 @@ -.. _connect-to-mongodb: +.. _java-connect-to-mongodb: ================== Connect to MongoDB @@ -34,8 +34,8 @@ Use the ``MongoClients.create()`` method to construct a ``MongoClient``. As each ``MongoClient`` represents a thread-safe pool of connections to the database, most applications only require a single instance of a ``MongoClient``, even across multiple threads. -All resource usage limits, such as max connections, apply to individual -``MongoClient`` instances. + All resource usage limits, such as max connections, apply to individual + ``MongoClient`` instances. To learn about the different settings you can use to control the behavior of your ``MongoClient``, see the guide on diff --git a/source/connection/connection-troubleshooting.txt b/source/connection/connection-troubleshooting.txt index a4a79c6bd..79315612f 100644 --- a/source/connection/connection-troubleshooting.txt +++ b/source/connection/connection-troubleshooting.txt @@ -103,8 +103,8 @@ Connection Troubleshooting .. replacement:: authentication-guide-reference - To learn more about specifying authentication mechanisms, see the :ref:`authentication-mechanisms` and - :ref:`enterprise-authentication-mechanisms` guides. + To learn more about specifying authentication mechanisms, see the :ref:`java-authentication-mechanisms` + section. .. replacement:: verify-authentication-mechanism-anchor diff --git a/source/connection/mongoclientsettings.txt b/source/connection/mongoclientsettings.txt index 154cec5c6..6aa860b71 100644 --- a/source/connection/mongoclientsettings.txt +++ b/source/connection/mongoclientsettings.txt @@ -116,7 +116,7 @@ connection behavior: messages to the server. * - ``credential()`` - - Sets the :ref:`credential `. + - Sets the :ref:`credential `. * - ``readConcern()`` - Sets the :manual:`read concern `. diff --git a/source/crud/aggregation.txt b/source/crud/aggregation.txt index 0b6f5d247..defdb8d4e 100644 --- a/source/crud/aggregation.txt +++ b/source/crud/aggregation.txt @@ -114,7 +114,7 @@ Connect to a MongoDB Deployment .. tip:: To learn more about connecting to MongoDB, see the :ref:`Connection - Guide `. + Guide `. Insert Sample Data ++++++++++++++++++ diff --git a/source/faq.txt b/source/faq.txt index 8aa090530..d473191cf 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -185,9 +185,8 @@ check the following items in your code: - The credentials for the authentication mechanism that you specified are correct. To learn how to specify your credentials, see the - :ref:`authentication-mechanisms` and :ref:`enterprise-authentication-mechanisms` - guides. - + :ref:`java-authentication-mechanisms` section. + - The name of the authentication database that you specified is correct. To learn how to set up the users and roles for your MongoDB deployment, see `Manage Users and Roles `__ diff --git a/source/includes/connect-guide-note.rst b/source/includes/connect-guide-note.rst index 5471eac73..49f51a495 100644 --- a/source/includes/connect-guide-note.rst +++ b/source/includes/connect-guide-note.rst @@ -2,4 +2,4 @@ This example connects to an instance of MongoDB using a connection URI. To learn more about connecting to your MongoDB instance, see the - :ref:`connection guide `. + :ref:`connection guide `. diff --git a/source/security.txt b/source/security.txt index 4414a7ffb..96762b1a6 100644 --- a/source/security.txt +++ b/source/security.txt @@ -10,7 +10,6 @@ Security :maxdepth: 1 Authentication - Enterprise Authentication In-Use Encryption TLS/SSL SOCKS5 Proxy diff --git a/source/security/auth.txt b/source/security/auth.txt index 25dd128f0..e98580a9d 100644 --- a/source/security/auth.txt +++ b/source/security/auth.txt @@ -1,577 +1,82 @@ .. _authentication-mechanisms: +.. _java-authentication-mechanisms: ========================= Authentication Mechanisms ========================= - - .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol -.. _authentication-mechanisms-java: - -Overview --------- - -In this guide, you can learn how to authenticate with MongoDB using each -**authentication mechanism** available in the MongoDB Community Edition. -Authentication mechanisms are processes by which the driver and MongoDB deployment -confirm identity and establish trust to ensure security. - -The mechanisms that you can use with the latest version of MongoDB Community -Edition are as follows: - -- :ref:`Default ` -- :ref:`SCRAM-SHA-256 ` -- :ref:`SCRAM-SHA-1 ` -- :ref:`MONGODB-CR ` -- :ref:`MONGODB-AWS ` -- :ref:`X.509 ` - -To authenticate using ``Kerberos`` or ``LDAP``, see the -:doc:`Enterprise Authentication Mechanisms guide `. -For more information about establishing a connection to your MongoDB cluster, -read our :doc:`Connection Guide `. - -Specify an Authentication Mechanism ------------------------------------ - -.. include:: /includes/fundamentals/auth-specify.rst - -Mechanisms ----------- - -.. _default-auth-mechanism: - -Default -~~~~~~~ - -The default authentication mechanism setting uses one of the following -authentication mechanisms depending on what your version of {+mdb-server+} -supports: - -#. ``SCRAM-SHA-256`` -#. ``SCRAM-SHA-1`` -#. ``MONGODB-CR`` - -Server versions 3.6 and earlier use ``MONGODB-CR`` as the default -mechanism. Newer versions of {+mdb-server+} use one of the mechanisms for -which they advertise support. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -- ``username``: your MongoDB username -- ``password``: your MongoDB user's password -- ``hostname``: network address of your MongoDB deployment that your - client can access -- ``port``: port number of your MongoDB deployment -- ``authenticationDb``: MongoDB database that contains your user's - authentication data - -.. note:: - - If you omit the ``authenticationDb`` parameter, the driver uses the - default ``admin`` database. - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. _mongo-client-setting-with-mongo-credential-example: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the default authentication mechanism using a connection - string, omit the mechanism. The code to instantiate a ``MongoClient`` - resembles the following: - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource="); - - .. tab:: - :tabid: MongoCredential - - To specify the default authentication mechanism using the - ``MongoCredential`` class, use the ``createCredential()`` method. The - code to instantiate a ``MongoClient`` resembles the following: - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-default.rst - -For more information about the challenge-response (CR) and salted -challenge-response authentication mechanisms (SCRAM) that MongoDB supports, -see the :manual:`SCRAM ` section of the {+mdb-server+} -manual. - -.. _scram-sha-256-auth-mechanism: - -``SCRAM-SHA-256`` -~~~~~~~~~~~~~~~~~ - -.. note:: - - ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting - in MongoDB 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. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -- ``username``: your MongoDB username -- ``password``: your MongoDB user's password -- ``hostname``: network address of your MongoDB deployment that your - client can access -- ``port``: port number of your MongoDB deployment -- ``authenticationDb``: MongoDB database that contains your user's - authentication data - -.. note:: - - If you omit the ``authenticationDb`` parameter, the driver uses the - default ``admin`` database. - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the ``SCRAM-SHA-256`` authentication mechanism using a - connection string, assign the ``authMechanism`` parameter the value - ``SCRAM-SHA-256`` in your connection string. The code to instantiate - a ``MongoClient`` resembles the following: - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-256"); - - .. tab:: - :tabid: MongoCredential - - To specify the default authentication mechanism using the - ``MongoCredential`` class, use the - `createScramSha256Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__ - method. The code to instantiate a ``MongoClient`` resembles - the following: - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-sha256.rst - -.. _scram-sha-1-auth-mechanism: - -``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. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -- ``username``: your MongoDB username -- ``password``: your MongoDB user's password -- ``hostname``: network address of your MongoDB deployment that your - client can access -- ``port``: port number of your MongoDB deployment -- ``authenticationDb``: MongoDB database that contains your user's - authentication data - -.. note:: - - If you omit the ``authenticationDb`` parameter, the driver uses the - default ``admin`` database. - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the ``SCRAM-SHA-1`` authentication mechanism using a - connection string, assign the ``authMechanism`` parameter the value - ``SCRAM-SHA-1`` in your connection string. The code to instantiate - a ``MongoClient`` resembles the following: - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-1"); - - .. tab:: - :tabid: MongoCredential - - To specify the default authentication mechanism using the - ``MongoCredential`` class, use the - `createScramSha1Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ - method. The code to instantiate a ``MongoClient`` resembles the following: - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-sha1.rst - -.. _mongodb-cr-auth-mechanism: - -``MONGODB-CR`` -~~~~~~~~~~~~~~ - -``MONGODB-CR`` is a challenge-response authentication mechanism that uses your -username and password to authenticate your user. This authentication -mechanism was deprecated starting in MongoDB 3.6 and is no longer -supported as of MongoDB 4.0. - -You cannot specify this method explicitly; refer to the fallback provided -by the :ref:`default authentication mechanism ` to -connect using ``MONGODB-CR``. - -.. _mongodb-aws-auth-mechanism: - -``MONGODB-AWS`` -~~~~~~~~~~~~~~~ - -.. - The MONGODB-AWS section structure was updated for v4.8 of the driver. Avoid - backporting any documentation that might not apply to a prior version. - -.. note:: - - The MONGODB-AWS authentication mechanism is available for MongoDB - deployments on MongoDB Atlas. - -The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services -Identity and Access Management (AWS IAM) credentials to authenticate your -user. To learn more about configuring MongoDB Atlas, see the -:atlas:`Set Up Passwordless Authentication with AWS IAM Roles ` -guide. - -To instruct the driver to use this authentication mechanism, you can specify -``MONGODB-AWS`` either as a parameter in the connection string or by using -the ``MongoCredential.createAwsCredential()`` factory method. - -Learn how to specify this authentication mechanism and the various ways to -provide your AWS IAM credentials in the next sections. - -These sections contain code examples that use the following placeholders: +.. facet:: + :name: genre + :values: reference -- ``awsKeyId``: value of your AWS access key ID -- ``awsSecretKey``: value of your AWS secret access key -- ``atlasUri``: network address of your MongoDB Atlas deployment -- ``hostname``: hostname of your MongoDB Atlas deployment -- ``port``: port of your MongoDB Atlas deployment -- ``awsSessionToken``: value of your AWS session token +.. meta:: + :keywords: enterprise, community, security -.. _java-mongodb-aws-sdk: +.. toctree:: + :caption: Authentication -AWS SDK for Java -++++++++++++++++ + SCRAM + X.509 + AWS IAM + OIDC + LDAP (PLAIN) + Kerberos (GSSAPI) -.. versionadded:: v4.8 - -You can use one of the AWS SDK for Java v1 or v2 to specify your credentials. -This method offers the following features: - -- Multiple options for obtaining credentials -- Credential caching which helps your application avoid rate limiting -- Credential provider management for use with the `Elastic Kubernetes Service `__. - -To use the AWS SDK for Java for ``MONGODB-AWS`` authentication, you must -perform the following: - -1. Specify the authentication mechanism -#. Add the SDK as a dependency to your project -#. Supply your credentials using one of the methods in the credential - provider chain - -.. important:: - - This method of providing ``MONGODB-AWS`` credentials is available - only in the {+driver-long+} v4.8 and later. - -To specify the authentication mechanism by using a ``MongoCredential``, -use the ``MongoCredential.createAwsCredential()`` factory method -and add the ``MongoCredential`` instance to your ``MongoClient`` as shown -in the following example: - -.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java - :language: java - :dedent: - :start-after: start mechOnlyMongoCredential - :end-before: end mechOnlyMongoCredential - :emphasize-lines: 1,7 - -To specify the authentication mechanism in the connection string, add -it as a parameter as shown in the following example: - -.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java - :language: java - :dedent: - :start-after: start mechOnlyConnectionString - :end-before: end mechOnlyConnectionString - -To add the AWS SDK as a dependency to your project, see the following -AWS documentation for the version you need: - -- For the **AWS SDK for Java v2**, see the `Setting Up `__ - guide. -- For the **AWS SDK for Java v1**, see the `Getting Started `__ - guide. - -.. note:: - - For the AWS SDK for Java v2, the Java driver currently tests using the - ``software.amazon.awssdk:auth:2.18.9`` dependency. - - For the AWS SDK for Java v1, the Java driver currently tests using the - ``com.amazonaws:aws-java-sdk-core:1.12.337`` dependency. - -To supply your credentials, see the following AWS documentation for the -version you need: - -- To learn more about the **AWS SDK for Java v2** class the driver uses to - get the credentials, see the `DefaultCredentialsProvider `__ - API documentation. - - Learn how to supply your credentials to this class from the - `Use the default credential provider chain `__ - section. - -- To learn more about the **AWS SDK for Java v1** class the driver uses to - get the credentials, see the `DefaultAWSCredentialsProviderChain `__ - API documentation. - - Learn how to supply your credentials to this class from the - `Using the Default Credential Provider Chain `__ - section. - -.. note:: - - If you include both v1 and v2 of the AWS SDK for Java in your project, - you must use the v2 methods to supply your credentials. - -.. _java-mongodb-aws-env-variables: - -Specify Your Credentials in the Environment -+++++++++++++++++++++++++++++++++++++++++++ - -You can provide your AWS IAM credentials by instructing the driver to -use the ``MONGODB-AWS`` authentication mechanism and by setting the -appropriate environment variables. - -To use the environment variables to supply your credentials, you must perform -the following: - -1. Specify the authentication mechanism -#. Add the appropriate environment variables - -You can specify the authentication mechanism by using a ``MongoCredential`` -or on the connection string. - -To specify the authentication mechanism by using a ``MongoCredential``, -use the ``MongoCredential.createAwsCredential()`` factory method and add the -``MongoCredential`` instance to your ``MongoClient`` as shown in the following -example: - -.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java - :language: java - :dedent: - :start-after: start mechOnlyMongoCredential - :end-before: end mechOnlyMongoCredential - :emphasize-lines: 1,7 - -To specify the authentication mechanism in the connection string, add it as a -parameter as shown in the following example: - -.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java - :language: java - :dedent: - :start-after: start mechOnlyConnectionString - :end-before: end mechOnlyConnectionString - -The next examples show how to provide your credentials by setting environment -variables for the following types of authentication: - -- Programmatic access keys -- Web identity provider -- ECS container credentials -- EC2 container credentials - -The following example shows how you can set your **programmatic access keys** -in environment variables by using ``bash`` or a similar shell: - -.. code-block:: bash - - export AWS_ACCESS_KEY_ID= - export AWS_SECRET_ACCESS_KEY= - export AWS_SESSION_TOKEN= - -Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS -session token for that role. - -You can use an OpenID Connect (OIDC)-compatible **web identity provider** to authenticate -to Amazon Elastic Kubernetes Service (EKS) or other services. - -.. important:: - - Your project must include v1 or v2 of the AWS SDK as a dependency to authenticate - using a web identity provider. - -To use a web identity provider, create a file that contains your -OIDC token. Next, use ``bash`` or a similar shell to set an environment variable -to the absolute path to this file, as shown in the following example: - -.. code-block:: bash - - export AWS_WEB_IDENTITY_TOKEN_FILE= - -To authenticate by using **ECS container credentials**, set the ECS -endpoint relative URI in an environment variable by using ``bash`` or -a similar shell as shown in the following example: - -.. code-block:: bash - - export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= - -To authenticate by using **EC2 container credentials**, make sure none of the -environment variables mentioned in this section are set. The driver obtains the -credentials from the default IPv4 EC2 instance metadata endpoint instead -of from environment variables. - -.. _java-mongodb-aws-mongoclient-configuration: - -Specify Your Credentials in a MongoCredential -+++++++++++++++++++++++++++++++++++++++++++++ - -You can supply your AWS IAM credentials to a ``MongoClient`` by using a -``MongoCredential`` instance. To construct the ``MongoCredential`` instance -for ``MONGODB-AWS`` authentication, use the `createAwsCredential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createAwsCredential(java.lang.String,char%5B%5D)>`__ -factory method. - -You can supply only programmatic access keys to the -``MongoCredential.createAwsCredential()`` method. If you must supply ECS -or EC2 container credentials, use the instructions in -:ref:`` or :ref:``. - -To use the ``MongoCredential`` for ``MONGODB-AWS`` authentication, you -must perform the following: - -1. Specify the authentication mechanism -#. Supply the credentials - -To specify the authentication mechanism by using a ``MongoCredential``, -use the ``MongoCredential.createAwsCredential()`` factory method -and add the ``MongoCredential`` instance to your ``MongoClient`` as shown -in the following example: - -.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java - :language: java - :dedent: - :start-after: start mongoCredential - :end-before: end mongoCredential - :emphasize-lines: 1 - -If you must specify an AWS session token, pass it to the -`withMechanismProperty() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__ -method as shown in the following example: - -.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java - :language: java - :dedent: - :start-after: start mongoCredentialSessionTokenCredential - :end-before: end mongoCredentialSessionTokenCredential - :emphasize-lines: 1,7 - -To refresh your credentials, you can declare a ``Supplier`` lambda expression -that returns new credentials as shown in the following example: - -.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java - :language: java - :dedent: - :start-after: start refreshCredentials - :end-before: end refreshCredentials - :emphasize-lines: 4-5,8-9 - -.. note:: - - If you must provide AWS IAM credentials in a connection string, refer to - a previous release of the `MONGODB-AWS driver documentation `__. - -.. _x509-auth-mechanism: - -``X.509`` -~~~~~~~~~ - -The ``X.509`` authentication mechanism uses -:wikipedia:`TLS ` with X.509 certificates to -authenticate your user, identified by the relative distinguished names -(RDNs) of your client certificate. When you specify the ``X.509`` -authentication mechanism, the server authenticates the connection using -the subject name of the client certificate. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -- ``hostname``: network address of your MongoDB deployment that your - client can access -- ``port``: port number of your MongoDB deployment -- ``authenticationDb``: MongoDB database that contains your user's - authentication data - -.. note:: - - If you omit the ``authenticationDb`` parameter, the driver uses the - default ``admin`` database. - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the ``X.509`` authentication mechanism using a connection - string, assign the ``authMechanism`` parameter the value ``MONGODB-X509`` - and enable TLS by assigning the ``tls`` - parameter a ``true`` value. The code to instantiate a ``MongoClient`` - resembles the following: - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create("mongodb://:/?authSource=&authMechanism=MONGODB-X509&tls=true"); - - .. tab:: - :tabid: MongoCredential - - To specify the ``X.509`` authentication mechanism using the - ``MongoCredential`` class, use the - `createMongoX509Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createMongoX509Credential(java.lang.String)>`__ - method. Also, enable TLS by calling the - `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ - method and setting the ``enabled`` property to ``true`` in the - `SslSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SslSettings.Builder.html>`__ - block. The code to instantiate a ``MongoClient`` resembles - the following: - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-x509.rst +Overview +-------- -For additional information on configuring your application to use -certificates as well as TLS/SSL options, see our -:doc:`TLS/SSL guide `. \ No newline at end of file +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:`java-connect-to-mongodb` 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:`OIDC (Workload Identity Federation) ` + - Yes + - Yes + - No + * - :ref:`` + - Yes + - Yes + - No + * - :ref:`Kerberos (GSSAPI) ` + - No + - Yes + - No \ No newline at end of file diff --git a/source/security/auth/aws-iam.txt b/source/security/auth/aws-iam.txt new file mode 100644 index 000000000..f8c8870ae --- /dev/null +++ b/source/security/auth/aws-iam.txt @@ -0,0 +1,299 @@ +.. _java-authentication-aws: + +================================== +AWS Identity and Access Management +================================== + +.. 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. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: Your AWS access key ID +- ````: The network address of your MongoDB Atlas deployment +- ````: Your AWS secret access key +- ````: Your AWS session token +- ````: The hostname of your MongoDB Atlas deployment +- ````: The port of your MongoDB Atlas deployment + +To use the code examples on this page, replace these placeholders with your own values. + +Specify MONGODB-AWS Authentication +---------------------------------- + +To instruct the driver to use this authentication mechanism, you can specify +``MONGODB-AWS`` either as a parameter in the connection string or by using +the ``MongoCredential.createAwsCredential()`` factory method. + +This section describes how to specify this authentication mechanism and the various ways to +provide your AWS IAM credentials. + +.. _java-mongodb-aws-sdk: + +Use AWS SDK for Java +~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + This method of providing ``MONGODB-AWS`` credentials is available + only in the {+driver-short+} v4.8 and later. + +You can specify your credentials by using v1 or v2 of the AWS SDK for Java, which +offers the following features: + +- Multiple options for obtaining credentials +- Credential caching which helps your application avoid rate limiting +- Credential provider management for use with the `Elastic Kubernetes Service `__. + +To use the AWS SDK for Java for ``MONGODB-AWS`` authentication, you must +perform the following actions: + +1. Specify the authentication mechanism +#. Add the SDK as a dependency to your project +#. Supply your credentials by using one of the methods in the credential + provider chain + +To specify the authentication mechanism by using a ``MongoCredential``, +use the ``MongoCredential.createAwsCredential()`` factory method +and add the ``MongoCredential`` instance to your ``MongoClient`` as shown +in the following example: + +.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java + :language: java + :dedent: + :start-after: start mechOnlyMongoCredential + :end-before: end mechOnlyMongoCredential + :emphasize-lines: 1,8 + +To specify the authentication mechanism in the connection string, add +it as a parameter as shown in the following example: + +.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java + :language: java + :dedent: + :start-after: start mechOnlyConnectionString + :end-before: end mechOnlyConnectionString + +To add the AWS SDK as a dependency to your project, see the following +AWS documentation for the version you need: + +- For the **AWS SDK for Java v2**, see the `Setting Up `__ + guide. +- For the **AWS SDK for Java v1**, see the `Getting Started `__ + guide. + +.. note:: + + For the AWS SDK for Java v2, the Java driver tests using the + ``software.amazon.awssdk:auth:2.18.9`` dependency. + + For the AWS SDK for Java v1, the Java driver tests using the + ``com.amazonaws:aws-java-sdk-core:1.12.337`` dependency. + +To supply your credentials, see the following AWS documentation for the +version you need: + +- To learn more about the **AWS SDK for Java v2** class the driver uses to + get the credentials, see the `DefaultCredentialsProvider `__ + API documentation. + + Learn how to supply your credentials to this class from the + `Use the default credential provider chain `__ + section. + +- To learn more about the **AWS SDK for Java v1** class the driver uses to + get the credentials, see the `DefaultAWSCredentialsProviderChain `__ + API documentation. + + Learn how to supply your credentials to this class from the + `Using the Default Credential Provider Chain `__ + section. + +.. note:: + + If you include both v1 and v2 of the AWS SDK for Java in your project, + you must use the v2 methods to supply your credentials. + +.. _java-mongodb-aws-env-variables: + +Use Environment Variables +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can provide your AWS IAM credentials by instructing the driver to +use the ``MONGODB-AWS`` authentication mechanism and by setting the +appropriate environment variables. + +To use the environment variables to supply your credentials, you must perform +the following actions: + +1. Specify the authentication mechanism +#. Add the appropriate environment variables + +You can specify the authentication mechanism by using a ``MongoCredential`` +or in the connection string. + +To specify the authentication mechanism by using a ``MongoCredential``, +use the ``MongoCredential.createAwsCredential()`` factory method and add the +``MongoCredential`` instance to your ``MongoClient`` as shown in the following +example: + +.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java + :language: java + :dedent: + :start-after: start mechOnlyMongoCredential + :end-before: end mechOnlyMongoCredential + :emphasize-lines: 1,8 + +To specify the authentication mechanism in the connection string, add it as a +parameter as shown in the following example: + +.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java + :language: java + :dedent: + :start-after: start mechOnlyConnectionString + :end-before: end mechOnlyConnectionString + +You can also set environment variables to enable the following types of +authentication: + +- Programmatic access keys +- Web identity provider +- ECS container credentials +- EC2 container credentials + +The following example shows how you can set your **programmatic access keys** +in environment variables by using ``bash`` or a similar shell: + +.. code-block:: bash + + export AWS_ACCESS_KEY_ID= + export AWS_SECRET_ACCESS_KEY= + export AWS_SESSION_TOKEN= + +Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS +session token for that role. + +You can use an OpenID Connect (OIDC)-compatible **web identity provider** to authenticate +to Amazon Elastic Kubernetes Service (EKS) or other services. + +.. important:: + + Your project must include v1 or v2 of the AWS SDK as a dependency to authenticate + using a web identity provider. + +To use a web identity provider, create a file that contains your +OIDC token. Next, use ``bash`` or a similar shell to set an environment variable +to the absolute path to this file, as shown in the following example: + +.. code-block:: bash + + export AWS_WEB_IDENTITY_TOKEN_FILE= + +To authenticate by using **ECS container credentials**, set the ECS +endpoint relative URI in an environment variable by using ``bash`` or +a similar shell as shown in the following example: + +.. code-block:: bash + + export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= + +To authenticate by using **EC2 container credentials**, make sure none of the +environment variables mentioned in this section are set. The driver obtains the +credentials from the default IPv4 EC2 instance metadata endpoint instead +of from environment variables. + +.. _java-mongodb-aws-mongoclient-configuration: + +Use a MongoCredential Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can supply your AWS IAM credentials to a ``MongoClient`` by using a +``MongoCredential`` instance. To construct the ``MongoCredential`` instance +for ``MONGODB-AWS`` authentication, use the ``createAwsCredential()`` +factory method. + +You can supply only programmatic access keys to the +``MongoCredential.createAwsCredential()`` method. If you must supply ECS +or EC2 container credentials, use the instructions in the +:ref:`` or :ref:`` +sections. + +To use the ``MongoCredential`` for ``MONGODB-AWS`` authentication, you +must perform the following actions: + +1. Specify the authentication mechanism +#. Supply the credentials + +To specify the authentication mechanism by using a ``MongoCredential``, +use the ``MongoCredential.createAwsCredential()`` factory method +and add the ``MongoCredential`` instance to your ``MongoClient`` as shown +in the following example: + +.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java + :language: java + :dedent: + :start-after: start mongoCredential + :end-before: end mongoCredential + :emphasize-lines: 1,8 + +If you must specify an AWS session token, pass it to the +`withMechanismProperty() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__ +method as shown in the following example: + +.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java + :language: java + :dedent: + :start-after: start mongoCredentialSessionTokenCredential + :end-before: end mongoCredentialSessionTokenCredential + :emphasize-lines: 1,8 + +To refresh your credentials, you can declare a ``Supplier`` lambda expression +that returns new credentials as shown in the following example: + +.. literalinclude:: /includes/fundamentals/code-snippets/MongoDbAwsAuth.java + :language: java + :dedent: + :start-after: start refreshCredentials + :end-before: end refreshCredentials + :emphasize-lines: 1-5,9 + +.. note:: + + If you must provide AWS IAM credentials in a connection string, see + v4.7 or earlier of the {+driver-short+} documentation. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ +- `MongoCredential.createAwsCredential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createAwsCredential(java.lang.String,char%5B%5D)>`__ diff --git a/source/security/auth/kerberos.txt b/source/security/auth/kerberos.txt new file mode 100644 index 000000000..159d75ae0 --- /dev/null +++ b/source/security/auth/kerberos.txt @@ -0,0 +1,212 @@ +.. _java-authentication-kerberos: + +================= +Kerberos (GSSAPI) +================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: .NET, 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. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: Your :wikipedia:`URL-encoded ` principal name. For + example: ``"username%40REALM.ME"`` +- ````: The network address of your MongoDB deployment. +- ````: The port number of your MongoDB deployment. If you omit this parameter, + the driver uses the default port number (``27017``). + +To use the code examples, replace these placeholders with your own values. + +Specify GSSAPI Authentication +----------------------------- + +Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab below for instructions and sample code for specifying this authentication +mechanism: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the GSSAPI authentication mechanism by using a connection + string, perform the following actions: + + - Assign the ``authMechanism`` URL parameter to the value ``GSSAPI`` + - (*optional*) Assign the ``authSource`` URL parameter to the value ``$external`` + + .. note:: + + If you specify the ``GSSAPI`` mechanism, you cannot assign + ``authSource`` to any value other than ``$external``. + + The code to instantiate a ``MongoClient`` resembles the following: + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI"); + + .. tab:: + :tabid: MongoCredential + + To specify the GSSAPI authentication mechanism by using the + ``MongoCredential`` class, use the ``createGSSAPICredential()`` + method. The code to instantiate a ``MongoClient`` resembles + the following: + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi.rst + + +To acquire a `Kerberos ticket `__, +the GSSAPI Java libraries require you to specify the realm and Key Distribution +Center (KDC) system properties. See the sample settings in the following example: + +.. code-block:: none + + java.security.krb5.realm=MYREALM.ME + java.security.krb5.kdc=mykdc.myrealm.me + +Additional Properties +~~~~~~~~~~~~~~~~~~~~~ + +You might need to specify one or more of the following +``MongoCredential`` mechanism properties depending on your Kerberos setup: + +- ``SERVICE_NAME`` +- ``CANONICALIZE_HOST_NAME`` +- ``JAVA_SUBJECT`` +- ``JAVA_SASL_CLIENT_PROPERTIES`` +- ``JAVA_SUBJECT_PROVIDER`` + +.. tabs:: + :hidden: + + .. tab:: + :tabid: Connection String + + .. important:: + + You can only specify the following GSSAPI properties using the + ``MongoCredential``: + + - ``JAVA_SUBJECT`` + - ``JAVA_SASL_CLIENT_PROPERTIES`` + - ``JAVA_SUBJECT_PROVIDER`` + + Select the :guilabel:`MongoCredential` tab to see how to specify + them. + + To specify one of the GSSAPI additional properties, include it in the + connection string as a URL parameter using the format: + ``:``. + + Your code to instantiate a ``MongoClient`` using GSSAPI and additional + properties might resemble the following: + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService"); + + .. tab:: + :tabid: MongoCredential + + To specify one of the GSSAPI additional properties, call the + ``withMechanismProperty()`` method on your ``MongoCredential`` + instance and pass the property name and value as parameters. Use the + property name constants defined in the ``MongoCredential`` class: + + - `SERVICE_NAME_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#SERVICE_NAME_KEY>`__ + - `CANONICALIZE_HOST_NAME_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#CANONICALIZE_HOST_NAME_KEY>`__ + - `JAVA_SUBJECT_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SUBJECT_KEY>`__ + - `JAVA_SASL_CLIENT_PROPERTIES_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SASL_CLIENT_PROPERTIES_KEY>`__ + - `JAVA_SUBJECT_PROVIDER_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SUBJECT_PROVIDER_KEY>`__ + + Select the **SERVICE_NAME_KEY** or **JAVA_SUBJECT_KEY** tab to + see sample code to instantiate a ``MongoCredential`` that uses GSSAPI and + the selected property: + + .. tabs:: + + .. tab:: + :tabid: SERVICE_NAME_KEY + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst + + .. tab:: + :tabid: JAVA_SUBJECT_KEY + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst + +Configure Caching Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the Java driver caches Kerberos tickets by ``MongoClient`` instance. +If your deployment needs to frequently create and destroy ``MongoClient`` instances, +you can change the default Kerberos ticket caching behavior to cache by process +to improve performance. + +.. tabs:: + :hidden: + + .. tab:: + :tabid: Connection String + + To cache Kerberos tickets by process, you must use the ``MongoCredential`` authentication + mechanism, as the connection string authentication mechanism does not support the ``JAVA_SUBJECT_PROVIDER`` + mechanism property. If you would like to cache Kerberos tickets by process, select the :guilabel:`MongoCredential` + tab to learn how to accomplish this. + + .. tab:: + :tabid: MongoCredential + + To cache Kerberos tickets by process, you must specify the ``JAVA_SUBJECT_PROVIDER`` + mechanism property and provide a + `KerberosSubjectProvider `__ + in your ``MongoCredential`` instance. The code to configure the Java driver to cache Kerberos tickets + by process resembles the following: + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst + + +.. note:: + + On Windows, Oracle's JRE uses `LSA `__ + rather than `SSPI `__ + in its implementation of GSSAPI which limits interoperability with + Windows Active Directory and implementations of single sign-on. For more + information, see the following resources: + + - `JDK-8054026 `__ + - `JDK-6722928 `__ + - `SO 23427343 `__ + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ +- `MongoCredential.createGSSAPICredential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createGSSAPICredential(java.lang.String)>`__ +- `MongoCredential.withMechanismProperty() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__ \ No newline at end of file diff --git a/source/security/auth/ldap.txt b/source/security/auth/ldap.txt new file mode 100644 index 000000000..0231513a3 --- /dev/null +++ b/source/security/auth/ldap.txt @@ -0,0 +1,92 @@ +.. _java-authentication-ldap: + +=========================== +LDAP (PLAIN) Authentication +=========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: .NET, code example + +Overview +-------- + +The PLAIN authentication mechanism allows you to use your Lightweight Directory Access +Protocol (LDAP) username and password to authenticate to MongoDB. +You can use this mechanism only when authenticating to MongoDB Enterprise Advanced. + +.. tip:: PLAIN Authentication + + LDAP authentication uses the PLAIN Simple Authentication and Security Layer + (SASL) defined in `RFC-4616 `__. + +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. +- ````: The port number of your MongoDB deployment. If you omit this parameter, + the driver uses the default port number (``27017``). You don't need to specify a port + when connecting to a MongoDB Atlas cluster. + +To use the code examples, replace these placeholders with your own values. + +Specify PLAIN Authentication +---------------------------- + +Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab for instructions and sample code for specifying this authentication +mechanism: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the LDAP (PLAIN) authentication mechanism by using a connection + string, perform the following actions: + + - Assign the ``authMechanism`` URL parameter to the value ``PLAIN`` + - (*optional*) Assign the ``authSource`` URL parameter to the value ``$external`` + + .. note:: + + If you specify the ``PLAIN`` mechanism, you cannot assign + ``authSource`` to any value other than ``$external``. + + The code to instantiate a ``MongoClient`` resembles the following: + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create(":@:/?authSource=$external&authMechanism=PLAIN"); + + .. tab:: + :tabid: MongoCredential + + To specify the LDAP (PLAIN) authentication mechanism by using the + ``MongoCredential`` class, use the ``createPlainCredential()`` + method. The code to instantiate a ``MongoClient`` resembles the following: + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-ldap.rst + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ +- `MongoCredential.createPlainCredential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createPlainCredential(java.lang.String,java.lang.String,char%5B%5D)>`__ diff --git a/source/security/auth/oidc.txt b/source/security/auth/oidc.txt new file mode 100644 index 000000000..9d7748de1 --- /dev/null +++ b/source/security/auth/oidc.txt @@ -0,0 +1,222 @@ +.. _java-authentication-oidc: + +=================================== +OIDC (Workload Identity Federation) +=================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: .NET, code example + +Overview +-------- + +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). + +You can use this mechanism only when authenticating to MongoDB Atlas or MongoDB +Enterprise Advanced, and only when authenticating to MongoDB v7.0 or later. + +.. tip:: OIDC Authentication + + To learn more about configuring MongoDB Atlas for OIDC authentication, see + :atlas:`Set up Workforce Identity Federation with OIDC ` + in the Atlas documentation. + + For more information about using OIDC authentication with MongoDB, see + :manual:`Authentication and Authorization with OIDC/OAuth 2.0 ` and + :manual:`oidcIdentityProviders ` + 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 network address of your MongoDB deployment. +- ````: The port number of your MongoDB deployment. If you omit this parameter, + the driver uses the default port number (``27017``). You don't need a port number + when connecting to a MongoDB Atlas cluster. + +To use the code examples, replace these placeholders with your own values. + +Specify OIDC Authentication +--------------------------- + +The following sections describe how to use OIDC authentication to +authenticate from various platforms. + +.. _java-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. + +You can specify Azure IMDS OIDC authentication either by +using a ``MongoCredential`` or as part of the connection string. + +Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to +see the corresponding syntax: + +.. tabs:: + + .. tab:: Connection String + :tabid: mongodb-azure-imds-connection-string + + Replace the ```` placeholder in the + following code with the percent-encoded value of the audience server + parameter configured on your MongoDB deployment. + + The comma (``,``) character and its encoding (``%2C``) are + reserved, and using these characters in a value causes the + driver to interpret commas as delimiters of key-value pairs. + You must specify values that contain commas in a ``MongoCredential`` instance, as + demonstrated in the :guilabel:`MongoCredential` tab. + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create( + "mongodb://@:/?" + + "?authMechanism=MONGODB-OIDC" + + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:"); + + .. tab:: MongoCredential + :tabid: mongodb-azure-mongo-credential + + Replace the ```` placeholder with the value of the + ``audience`` server parameter configured on your MongoDB deployment. + + .. code-block:: java + + MongoCredential credential = MongoCredential.createOidcCredential("") + .withMechanismProperty("ENVIRONMENT", "azure") + .withMechanismProperty("TOKEN_RESOURCE", ""); + + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder() + .applyToClusterSettings(builder -> + builder.hosts(Arrays.asList(new ServerAddress("", )))) + .credential(credential) + .build()); + +.. _java-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 {+driver-short+}'s built-in GCP +support. + +You can specify GCP IMDS OIDC authentication either by +using a ``MongoCredential`` or as part of the connection string. + +Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to +see the corresponding syntax: + +.. tabs:: + + .. tab:: Connection String + :tabid: mongodb-gcp-imds-connection-string + + Replace the ```` placeholder in the + following code with the percent-encoded value of the audience server + parameter configured on your MongoDB deployment. + + The comma (``,``) character and its encoding (``%2C``) are + reserved, and using these characters in a value causes the + driver to interpret commas as delimiters of key-value pairs. + You must specify values that contain commas in a ``MongoCredential`` instance, as + demonstrated in the :guilabel:`MongoCredential` tab. + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create( + "mongodb://:/?" + + "authMechanism=MONGODB-OIDC" + + "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:"); + + .. tab:: MongoCredential + :tabid: mongodb-gcp-mongo-credential + + Replace the ```` placeholder with the value of the + ``audience`` server parameter configured on your MongoDB deployment. + + .. code-block:: java + + MongoCredential credential = MongoCredential.createOidcCredential() + .withMechanismProperty("ENVIRONMENT", "gcp") + .withMechanismProperty("TOKEN_RESOURCE", ""); + + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder() + .applyToClusterSettings(builder -> + builder.hosts(Arrays.asList(new ServerAddress("", )))) + .credential(credential) + .build()); + +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. +To do so, use the ``"OIDC_CALLBACK"`` authentication property, as shown in the following +code example: + +.. code-block:: java + + MongoCredential credential = MongoCredential.createOidcCredential(null) + .withMechanismProperty("OIDC_CALLBACK", (context) -> { + String accessToken = ... + return new OidcCallbackResult(accessToken); + }); + +The value of the ``"OIDC_CALLBACK"`` property must be a lambda or other implementation +of the ``OidcCallback`` functional interface that accepts an ``OidcCallbackContext`` +as a parameter and returns an ``OidcCallbackResult``. + +The following example uses an example callback to retrieve an OIDC token from a file +named ``"access-token.dat"`` in the local file system: + +.. code-block:: java + + MongoCredential credential = MongoCredential.createOidcCredential(null) + .withMechanismProperty("OIDC_CALLBACK", (context) -> { + string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat")); + return new OidcCallbackResult(accessToken); + }); + + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder() + .applyToClusterSettings(builder -> + builder.hosts(Arrays.asList(new ServerAddress("", )))) + .credential(credential) + .build()); + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ +- `MongoCredential.createOidcCredential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createOidcCredential(java.lang.String)>`__ +- `MongoCredential.withMechanismProperty() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__ \ No newline at end of file diff --git a/source/security/auth/scram.txt b/source/security/auth/scram.txt new file mode 100644 index 000000000..c36777695 --- /dev/null +++ b/source/security/auth/scram.txt @@ -0,0 +1,169 @@ +.. _java-authentication-scram: + +===== +SCRAM +===== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: .NET, 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. +- ````: The port number of your MongoDB deployment. If you omit this parameter, + the driver uses the default port number (``27017``). You don't need a port number + when connecting to a MongoDB Atlas cluster. +- ````: The MongoDB database that contains the user's authentication + data. If you omit this parameter, the driver uses the default value, ``admin``. + +To use the code examples, replace these placeholders with your own values. + +Specify the Default SCRAM Authentication Mechanism +-------------------------------------------------- + +To use the default SCRAM mechanism to authenticate your MongoDB user, specify your +MongoDB credentials, but don't specify an authentication mechanism. +Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab below for instructions and sample code for the corresponding syntax: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the default authentication mechanism by using a connection + string, omit the mechanism. The code to instantiate a ``MongoClient`` + resembles the following: + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource="); + + .. tab:: + :tabid: MongoCredential + + To specify the default authentication mechanism by using the + ``MongoCredential`` class, use the ``createCredential()`` method. The + code to instantiate a ``MongoClient`` resembles the following: + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-default.rst + +For more information about the challenge-response (CR) and salted +challenge-response authentication mechanisms (SCRAM) that MongoDB supports, +see the :manual:`SCRAM ` section of the {+mdb-server+} +manual. + +Specify SCRAM-SHA-256 Authentication +------------------------------------ + +``SCRAM-SHA-256`` is the default authentication method for MongoDB starting +in MongoDB 4.0, but this code example shows how to explicitly use this +mechanism. Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab for instructions and sample code for specifying this authentication +mechanism: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the ``SCRAM-SHA-256`` authentication mechanism by using a + connection string, assign the ``authMechanism`` parameter the value + ``SCRAM-SHA-256`` in your connection string. The code to instantiate + a ``MongoClient`` resembles the following: + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-256"); + + .. tab:: + :tabid: MongoCredential + + To specify the ``SCRAM-SHA-256`` authentication mechanism by using the + ``MongoCredential`` class, use the ``createScramSha256Credential()`` + method. The code to instantiate a ``MongoClient`` resembles + the following: + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-sha256.rst + +Specify SCRAM-SHA-1 Authentication +---------------------------------- + +``SCRAM-SHA-1`` is the default authentication method for MongoDB versions +earlier than 4.0, but this code example shows how to explicitly use this +mechanism. Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab for instructions and sample code for specifying this authentication +mechanism: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the ``SCRAM-SHA-1`` authentication mechanism by using a + connection string, assign the ``authMechanism`` parameter the value + ``SCRAM-SHA-1`` in your connection string. The code to instantiate + a ``MongoClient`` resembles the following: + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-1"); + + .. tab:: + :tabid: MongoCredential + + To specify the ``SCRAM-SHA-1`` authentication mechanism by using the + ``MongoCredential`` class, use the ``createScramSha1Credential()`` + method. The code to instantiate a ``MongoClient`` resembles the following: + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-sha1.rst + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ +- `MongoCredential.createCredential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createCredential(java.lang.String,java.lang.String,char%5B%5D)>`__ +- `MongoCredential.createScramSha256Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__ +- `MongoCredential.createScramSha1Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ \ No newline at end of file diff --git a/source/security/auth/x509.txt b/source/security/auth/x509.txt new file mode 100644 index 000000000..d82146730 --- /dev/null +++ b/source/security/auth/x509.txt @@ -0,0 +1,96 @@ +.. _java-authentication-x509: + +===== +X.509 +===== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: .NET, 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:`tls-ssl` 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 port number of the MongoDB deployment. If you omit this parameter, + the driver uses the default port number (``27017``). You don't need a port number + when connecting to a MongoDB Atlas cluster. +- ````: The MongoDB database that contains your user's + authentication data. If you omit this placeholder, the driver uses the + default ``admin`` database. + +To use the code examples, replace these placeholders with your own values. + +Specify X.509 Authentication +---------------------------- + +Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab below for instructions and sample code for specifying this authentication +mechanism: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the ``X.509`` authentication mechanism by using a connection + string, assign the ``authMechanism`` parameter to ``MONGODB-X509`` + and enable TLS by assigning the ``tls`` parameter to ``true``. The code + to instantiate a ``MongoClient`` resembles the following: + + .. code-block:: java + + MongoClient mongoClient = MongoClients.create("mongodb://:/?authSource=&authMechanism=MONGODB-X509&tls=true"); + + .. tab:: + :tabid: MongoCredential + + To specify the ``X.509`` authentication mechanism by using the + ``MongoCredential`` class, use the ``createMongoX509Credential()`` + method. Also, enable TLS by calling the + `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ + method and setting the ``enabled`` property to ``true`` in the + `SslSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SslSettings.Builder.html>`__ + block. The code to instantiate a ``MongoClient`` resembles + the following: + + .. include:: /includes/fundamentals/code-snippets/auth-credentials-x509.rst + +API Documentation +----------------- + +To learn more about any of the MongoDB methods and types used on this +page, see the following API documentation: + +- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ +- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ +- `MongoCredential.createMongoX509Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createMongoX509Credential(java.lang.String)>`__ + diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt deleted file mode 100644 index f6c15eda0..000000000 --- a/source/security/enterprise-auth.txt +++ /dev/null @@ -1,462 +0,0 @@ -.. _enterprise-authentication-mechanisms: - -==================================== -Enterprise Authentication Mechanisms -==================================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: ldap, encryption, principal, tls - -Overview --------- - -In this guide, you can learn how to authenticate with MongoDB using each -**authentication mechanism** available exclusively in the MongoDB Enterprise -Edition. - -You can use the following mechanisms with the latest version of MongoDB -Enterprise Edition: - -- :ref:`Kerberos (GSSAPI) ` -- :ref:`LDAP (PLAIN) ` -- :ref:`MONGODB-OIDC ` - -To authenticate using another mechanism, see the -:doc:`Authentication Mechanisms guide `. For more -information on establishing a connection to your MongoDB cluster, read our -:doc:`Connection Guide `. - -Specify an Authentication Mechanism ------------------------------------ - -.. include:: /includes/fundamentals/auth-specify.rst - -Mechanisms ----------- - -.. _gssapi-auth-mechanism: - -Kerberos (GSSAPI) -~~~~~~~~~~~~~~~~~~~~~~ - -The Generic Security Services API (``GSSAPI``) authentication mechanism -allows the user to authenticate to a Kerberos service using the user's -principal name. - -.. note:: - - The method refers to the ``GSSAPI`` authentication mechanism instead - of ``Kerberos`` because the driver authenticates using the - `GSSAPI RFC-4652 `_ SASL - mechanism. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -- ``username``: your URL-encoded principal name, such as ``"username%40REALM.ME"`` -- ``hostname``: network address of your MongoDB deployment that your - client can access -- ``port``: port number of your MongoDB deployment - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the GSSAPI authentication mechanism using a connection - string: - - - Assign the ``authMechanism`` URL parameter to the value ``GSSAPI`` - - (*optional*) Assign the ``authSource`` URL parameter to the value ``$external`` - - .. note:: - - If you specify the ``GSSAPI`` mechanism, you cannot assign - ``authSource`` to any value other than ``$external``. - - The code to instantiate a ``MongoClient`` resembles the following: - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI"); - - .. tab:: - :tabid: MongoCredential - - To specify the GSSAPI authentication mechanism using the - ``MongoCredential`` class, use the ``createGSSAPICredential()`` - method. The code to instantiate a ``MongoClient`` resembles - the following: - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi.rst - - -In order to acquire a -`Kerberos ticket `__, -the GSSAPI Java libraries require you to specify the realm and Key Distribution -Center (KDC) system properties. See the sample settings in the following example: - -.. code-block:: none - - java.security.krb5.realm=MYREALM.ME - java.security.krb5.kdc=mykdc.myrealm.me - -You might need to specify one or more of the following additional -``MongoCredential`` mechanism properties depending on your Kerberos setup: - -- ``SERVICE_NAME`` -- ``CANONICALIZE_HOST_NAME`` -- ``JAVA_SUBJECT`` -- ``JAVA_SASL_CLIENT_PROPERTIES`` -- ``JAVA_SUBJECT_PROVIDER`` - -.. tabs:: - :hidden: - - .. tab:: - :tabid: Connection String - - .. important:: - - You can only specify the following GSSAPI properties using the - ``MongoCredential``: - - - ``JAVA_SUBJECT`` - - ``JAVA_SASL_CLIENT_PROPERTIES`` - - ``JAVA_SUBJECT_PROVIDER`` - - Select the :guilabel:`MongoCredential` tab to see how to specify - them. - - To specify one of the GSSAPI additional properties, include it in the - connection string as a URL parameter using the format: - ``:``. - - Your code to instantiate a ``MongoClient`` using GSSAPI and additional - properties might resemble the following: - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService"); - - .. tab:: - :tabid: MongoCredential - - To specify one of the GSSAPI additional properties, call the - ``withMechanismProperty()`` method on your ``MongoCredential`` - instance and pass the property name and value as parameters. Use the - property name constants defined in the ``MongoCredential`` class: - - - `SERVICE_NAME_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#SERVICE_NAME_KEY>`__ - - `CANONICALIZE_HOST_NAME_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#CANONICALIZE_HOST_NAME_KEY>`__ - - `JAVA_SUBJECT_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SUBJECT_KEY>`__ - - `JAVA_SASL_CLIENT_PROPERTIES_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SASL_CLIENT_PROPERTIES_KEY>`__ - - `JAVA_SUBJECT_PROVIDER_KEY <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#JAVA_SUBJECT_PROVIDER_KEY>`__ - - Select the **SERVICE_NAME_KEY** or **JAVA_SUBJECT_KEY** tab to - see sample code to instantiate a ``MongoCredential`` that uses GSSAPI and - the selected property: - - .. tabs:: - - .. tab:: - :tabid: SERVICE_NAME_KEY - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst - - .. tab:: - :tabid: JAVA_SUBJECT_KEY - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst - -By default, the Java driver caches Kerberos tickets by ``MongoClient`` instance. -If your deployment needs to frequently create and destroy ``MongoClient`` instances, -you can change the default Kerberos ticket caching behavior to cache by process -to improve performance. - -.. tabs:: - :hidden: - - .. tab:: - :tabid: Connection String - - To cache Kerberos tickets by process, you must use the ``MongoCredential`` authentication - mechanism, as the connection string authentication mechanism does not support the ``JAVA_SUBJECT_PROVIDER`` - mechanism property. If you would like to cache Kerberos tickets by process, select the :guilabel:`MongoCredential` - tab to learn how to accomplish this. - - .. tab:: - :tabid: MongoCredential - - To cache Kerberos tickets by process, you must specify the ``JAVA_SUBJECT_PROVIDER`` - mechanism property and provide a - `KerberosSubjectProvider `__ - in your ``MongoCredential`` instance. The code to configure the Java driver to cache Kerberos tickets - by process resembles the following: - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst - - -.. note:: - - On Windows, Oracle’s JRE uses `LSA `__ - rather than `SSPI `__ - in its implementation of GSSAPI which limits interoperability with - Windows Active Directory and implementations of single sign-on. See the - following articles for more information: - - - `JDK-8054026 `__ - - `JDK-6722928 `__ - - `SO 23427343 `__ - - -.. _plain-auth-mechanism: - -LDAP (PLAIN) -~~~~~~~~~~~~ - -*Available in MongoDB Enterprise Edition 3.4 and later.* - -You can authenticate to a Lightweight Directory Access Protocol (LDAP) -server using your directory server username and password. - -.. tip:: - - 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 `_. - -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 `. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -- ``username``: your LDAP username -- ``password``: your LDAP user's password -- ``hostname``: network address of your MongoDB deployment that your - client can access -- ``port``: port number of your MongoDB deployment - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the LDAP (PLAIN) authentication mechanism using a connection - string: - - - Assign the ``authMechanism`` URL parameter to the value ``PLAIN`` - - (*optional*) Assign the ``authSource`` URL parameter to the value ``$external`` - - .. note:: - - If you specify the ``PLAIN`` mechanism, you cannot assign - ``authSource`` to any value other than ``$external``. - - The code to instantiate a ``MongoClient`` resembles the following: - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create(":@:/?authSource=$external&authMechanism=PLAIN"); - - .. tab:: - :tabid: MongoCredential - - To specify the LDAP (PLAIN) authentication mechanism using the - ``MongoCredential`` class, use the ``createPlainCredential()`` - method. The code to instantiate a ``MongoClient`` resembles the following: - - .. include:: /includes/fundamentals/code-snippets/auth-credentials-ldap.rst - -.. _mongodb-oidc: - -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 to various platforms. - -For more information about the MONGODB-OIDC authentication mechanism, see -:manual:`OpenID Connect Authentication ` and -:manual:`MongoDB Server Parameters ` -in the MongoDB Server manual. - -.. _java-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. - -You can specify Azure IMDS OIDC authentication either by -using a ``MongoCredential`` or as part of the connection string. - -Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to -see the corresponding syntax. - -.. tabs:: - - .. tab:: Connection String - :tabid: mongodb-azure-imds-connection-string - - Replace the ```` placeholder in the - following code with the percent-encoded value of the audience server - parameter configured on your MongoDB deployment. - - The comma (``,``) character and its encoding (``%2C``) are - reserved, and using these characters in a value causes the - driver to interpret commas as delimiters of key-value pairs. - You must specify values that contain commas in a ``MongoCredential`` instance, as - demonstrated in the :guilabel:`MongoCredential` tab. - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create( - "mongodb://@:/?" + - "?authMechanism=MONGODB-OIDC" + - "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:"); - - .. tab:: MongoCredential - :tabid: mongodb-azure-mongo-credential - - Replace the ```` placeholder with the client ID or application ID of the - Azure managed identity or enterprise application. Replace the ```` - placeholder with the value of the - ``audience`` server parameter configured on your MongoDB deployment. - - .. code-block:: java - - MongoCredential credential = MongoCredential.createOidcCredential("") - .withMechanismProperty("ENVIRONMENT", "azure") - .withMechanismProperty("TOKEN_RESOURCE", ""); - - MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder() - .applyToClusterSettings(builder -> - builder.hosts(Arrays.asList(new ServerAddress("", )))) - .credential(credential) - .build()); - -.. _java-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 {+driver-short+}'s built-in GCP -support. - -You can specify GCP IMDS OIDC authentication either by -using a ``MongoCredential`` or as part of the connection string. - -Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to -see the corresponding syntax. - -.. tabs:: - - .. tab:: Connection String - :tabid: mongodb-gcp-imds-connection-string - - Replace the ```` placeholder in the - following code with the percent-encoded value of the audience server - parameter configured on your MongoDB deployment. - - The comma (``,``) character and its encoding (``%2C``) are - reserved, and using these characters in a value causes the - driver to interpret commas as delimiters of key-value pairs. - You must specify values that contain commas in a ``MongoCredential`` instance, as - demonstrated in the :guilabel:`MongoCredential` tab. - - .. code-block:: java - - MongoClient mongoClient = MongoClients.create( - "mongodb://:/?" + - "authMechanism=MONGODB-OIDC" + - "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:"); - - .. tab:: MongoCredential - :tabid: mongodb-gcp-mongo-credential - - Replace the ```` placeholder with the value of the - ``audience`` server parameter configured on your MongoDB deployment. - - .. code-block:: java - - MongoCredential credential = MongoCredential.createOidcCredential() - .withMechanismProperty("ENVIRONMENT", "gcp") - .withMechanismProperty("TOKEN_RESOURCE", ""); - - MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder() - .applyToClusterSettings(builder -> - builder.hosts(Arrays.asList(new ServerAddress("", )))) - .credential(credential) - .build()); - -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. -To do so, use the ``"OIDC_CALLBACK"`` authentication property, as shown in the following -code example: - -.. code-block:: java - - MongoCredential credential = MongoCredential.createOidcCredential(null) - .withMechanismProperty("OIDC_CALLBACK", (context) -> { - String accessToken = ... - return new OidcCallbackResult(accessToken); - }); - -The value of the ``"OIDC_CALLBACK"`` property must be a lambda or other implementation -of the ``OidcCallback`` functional interface that accepts an ``OidcCallbackContext`` -as a parameter and returns an ``OidcCallbackResult``. - -The following example uses an example callback to retrieve an OIDC token from a file -named ``"access-token.dat"`` in the local file system: - -.. code-block:: java - - MongoCredential credential = MongoCredential.createOidcCredential(null) - .withMechanismProperty("OIDC_CALLBACK", (context) -> { - string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat")); - return new OidcCallbackResult(accessToken); - }); - - MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder() - .applyToClusterSettings(builder -> - builder.hosts(Arrays.asList(new ServerAddress("", )))) - .credential(credential) - .build()); diff --git a/source/versioning/whats-new.txt b/source/versioning/whats-new.txt index 129e425b2..12e62fe51 100644 --- a/source/versioning/whats-new.txt +++ b/source/versioning/whats-new.txt @@ -144,8 +144,7 @@ The 5.1.1 driver patch release includes the following changes: - When using the ``MONGODB-OIDC`` authentication mechanism, you must not include comma characters in the ``authMechanismProperties`` connection string value. To learn more about this behavior, see the - :ref:`MONGODB-OIDC ` section of the Enterprise - Authentication guide. + :ref:`MONGODB-OIDC ` guide. - Optimizes GridFS throughput by removing redundant byte array cloning. The ``GridFSDownloadStream`` and ``GridFSUploadStream`` types use @@ -185,7 +184,7 @@ Improvements in 5.1 - Internal testing of GraalVM native image technology. These tests involve building native applications by using the GraalVM native-image tool. - Enhanced support for the MONGODB-OIDC authentication mechanism. For more information about - OIDC, see the :ref:`mongodb-oidc` section of the Enterprise Authentication Mechanisms guide. + OIDC, see the :ref:`java-authentication-oidc` guide. .. _java-new-features-5.1: