From 30fb3cf5a089484fa6d9590f3de3696da55460e9 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 2 Oct 2024 16:57:27 -0400 Subject: [PATCH 01/29] authentication v1 --- source/includes/security/authentication.kt | 206 ++++++++ source/security/authentication.txt | 567 +++++++++++++++++++++ source/security/enterprise-auth.txt | 22 + 3 files changed, 795 insertions(+) create mode 100644 source/includes/security/authentication.kt create mode 100644 source/security/authentication.txt create mode 100644 source/security/enterprise-auth.txt diff --git a/source/includes/security/authentication.kt b/source/includes/security/authentication.kt new file mode 100644 index 0000000..382234f --- /dev/null +++ b/source/includes/security/authentication.kt @@ -0,0 +1,206 @@ +import com.mongodb.* +import com.mongodb.kotlin.client.MongoClient +import org.bson.BsonInt64 +import org.bson.Document + +// SCRAM Authentication +// start-default-cred-string +val mongoClient = + MongoClient.create("mongodb+srv://:@:/?authSource=") +// end-default-cred-string + +// start-default-mongo-cred +val credential = MongoCredential.createCredential( + "", "", "".toCharArray() +) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.srvHost("") + } + .credential(credential) + .applyToSslSettings { builder -> + builder.enabled(true) + } + .build() + +val mongoClient = MongoClient.create(settings) +// end-default-mongo-cred + +// start-scramsha256-cred-string +val mongoClient = + MongoClient.create("mongodb+srv://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256") +// end-scramsha256-cred-string + +// start-scramsha256-mongo-cred +val credential = MongoCredential.createScramSha256Credential( + "", "", "".toCharArray() + ) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.srvHost("") + } + .applyToSslSettings { builder -> + builder.enabled(true) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-scramsha256-mongo-cred + +// start-scramsha1-cred-string +val mongoClient = + MongoClient.create("mongodb+srv://:@:/?authSource=admin&authMechanism=SCRAM-SHA-1") +// end-scramsha1-cred-string + +// start-scramsha1-mongo-cred +val credential = MongoCredential.createScramSha1Credential( + "", "", "".toCharArray() + ) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.srvHost("") + } + .applyToSslSettings { builder -> + builder.enabled(true) + } + .credential(credential) + .build() + + val mongoClient = MongoClient.create(settings) +// end-scramsha1-mongo-cred + +// AWS Authentication + +// start-aws-sdk-mcred +val credential = MongoCredential.createAwsCredential(null, null) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("")) + ) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-aws-sdk-mcred + +// start-aws-sdk-cred-string +val mongoClient = + MongoClient.create("mongodb://?authMechanism=MONGODB-AWS") +// end-aws-sdk-cred-string + + +// start-aws-env-mcred +val credential = MongoCredential.createAwsCredential(null, null) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("")) + ) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-aws-env-mcred + +// start-aws-env-cred-string +val mongoClient = + MongoClient.create("mongodb://?authMechanism=MONGODB-AWS") +// end-aws-env-cred-string + +// start-aws-mcred +val credential = MongoCredential.createAwsCredential("", "".toCharArray()) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("")) + ) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-aws-mcred + +// start-aws-mcred-wmechprop +val credential = MongoCredential.createAwsCredential("", "".toCharArray()) + .withMechanismProperty("AWS_SESSION_TOKEN", "") + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("")) + ) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-aws-mcred-wmechprop + +// start-aws-lambda-expression +val awsFreshCredentialSupplier: Supplier = Supplier { + // Add your code here to fetch new credentials + + // Return the new credentials + AwsCredential("", "", "") +} + +val credential = MongoCredential.createAwsCredential("", "".toCharArray()) + .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(listOf(ServerAddress("", ""))) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-aws-lambda-expression + +// start-aws-apply-connect-string +val credential = MongoCredential.createAwsCredential("", "".toCharArray()) +val connectionString = ConnectionString("mongodb:///?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:") + +val settings = MongoClientSettings.builder() + .applyConnectionString(connectionString) + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-aws-apply-connect-string + +// X.509 + +// start-x509-connect-string +val mongoClient = + MongoClient.create("mongodb://:@:/?authSource=&authMechanism=MONGODB-X509&tls=true") +// end-x509-connect-string + +// start-x509-mcred +val credential = MongoCredential.createMongoX509Credential() + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(listOf( + ServerAddress("", "")) + ) + } + .applyToSslSettings { builder -> + builder.enabled(true) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-x509-mcred \ No newline at end of file diff --git a/source/security/authentication.txt b/source/security/authentication.txt new file mode 100644 index 0000000..1ff8871 --- /dev/null +++ b/source/security/authentication.txt @@ -0,0 +1,567 @@ +.. _kotlin-sync-auth: + +========================= +Authentication Mechanisms +========================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: validate credentials, protocols, code example + +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 server +confirm identity and establish trust to ensure security. + +This guide describes the following authentication mechanisms: + +- :ref:`SCRAM-Based Mechanisms ` +- :ref:`MONGODB-AWS Mechanism ` +- :ref:`MONGODB-X509 Mechanism ` + +To select a specific authentication mechanism, you can specify the +mechanism, your credentials, and other necessary information +in the options of your connection string or in a ``Credential`` struct. + +In this guide, the examples demonstrate how to configure +authentication in a ``Credential`` struct. + +To learn more about the connection string options for authentication, +see the :manual:`Authentication Options +` section +of the Connection String URI Format guide in the Server manual. + +To authenticate using ``Kerberos`` or ``LDAP``, see the +:ref:`Enterprise Authentication Mechanisms guide `. + +For more information on establishing a connection to your MongoDB cluster, +see :ref:`Connect to MongoDB `. + +.. _kotlin-sync-auth-scram-mechanisms: + +SCRAM-Based Mechanisms +---------------------- + +Salted challenge response authentication mechanism (SCRAM) refers to a +group of authentication mechanisms that use a username and +password to authenticate to a server. + +MongoDB supports the following SCRAM-based authentication mechanisms: + +- :ref:`SCRAM-SHA-256 `: an authentication mechanism that + uses your database username and password, encrypted with the ``SHA-256`` + algorithm +- :ref:`SCRAM-SHA-1 `: an authentication mechanism that + uses your database username and password, encrypted with the ``SHA-1`` + algorithm + +The following code snippets show how to specify the authentication mechanism, +using the following placeholders: + +* ``db_username`` - your MongoDB database username +* ``db_password`` - your MongoDB database user's password +* ``hostname`` - network address of your MongoDB server, accessible by your client +* ``port`` - port number of your MongoDB server +* ``authenticationDb`` - MongoDB database that contains your user's + authentication data. If you omit this parameter, the driver uses the + default value ``admin``. + +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. Your code to instantiate a ``MongoClient`` + should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :start-after: start-default-cred-string + :end-before: end-default-cred-string + :dedent: + + .. tab:: + :tabid: MongoCredential + + To specify the default authentication mechanism using the + ``MongoCredential`` class, use the ``createCredential()`` 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. Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :start-after: start-default-mongo-cred + :end-before: end-default-mongo-cred + :dedent: + +For more information on salted challenge-response authentication mechanisms (SCRAM) +that MongoDB supports, see the :manual:`SCRAM ` section of +the Server manual. + +.. _kotlin-sync-auth-scramsha256: + +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: + +* ``db_username`` - your MongoDB database username. +* ``db_password`` - your MongoDB database user's password. +* ``hostname`` - network address of your MongoDB server, accessible by your client. +* ``port`` - port number of your MongoDB server. +* ``authenticationDb`` - MongoDB database that contains your user's + authentication data. If you omit this parameter, the driver uses the + default value ``admin``. + +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. Your code to instantiate + a ``MongoClient`` should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-scramsha256-cred-string + :end-before: end-scramsha256-cred-string + + .. 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. 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. Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-scramsha256-mongo-cred + :end-before: end-scramsha256-mongo-cred + +.. _kotlin-sync-auth-scramsha1: + +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: + +* ``db_username`` - your MongoDB database username. +* ``db_password`` - your MongoDB database user's password. +* ``hostname`` - network address of your MongoDB server, accessible by your client. +* ``port`` - port number of your MongoDB server. +* ``authenticationDb`` - MongoDB database that contains your user's + authentication data. If you omit this parameter, the driver uses the + default value ``admin``. + +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. Your code to instantiate + a ``MongoClient`` should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-scramsha1-cred-string + :end-before: end-scramsha1-cred-string + + .. 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. 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. Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-scramsha1-mongo-cred + :end-before: end-scramsha1-mongo-cred + +.. _kotlin-sync-auth-aws: + +MONGODB-AWS Mechanism +--------------------- + +.. 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: + +* ``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 + +.. _kotlin-mongodb-aws-sdk: + +AWS SDK +~~~~~~~ + +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 + +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/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-sdk-mcred + :end-before: end-aws-sdk-mcred + :emphasize-lines: 1, 9 + +To specify the authentication mechanism in the connection string, add +it as a parameter as shown in the following example: + +.. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-sdk-cred-string + :end-before: end-aws-sdk-cred-string + +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. + +.. _kotlin-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/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-env-mcred + :end-before: end-aws-env-mcred + :emphasize-lines: 1, 9 + +To specify the authentication mechanism in the connection string, add it as a +parameter as shown in the following example: + +.. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-env-cred-string + :end-before: end-aws-env-cred-string + +The next examples show how to provide your credentials by setting environment +variables for the following types of authentication: + +- Programmatic access keys +- 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. + +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 using **EC2 container credentials**, make sure none of the +aforementioned environment variables are set. The driver obtains the +credentials from the default IPv4 EC2 instance metadata endpoint. + +.. _kotlin-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 need to 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/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-mcred + :end-before: end-aws-mcred + :emphasize-lines: 1, 9 + +If you need to 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/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-mcred-wmechprop + :end-before: end-aws-mcred-wmechprop + :emphasize-lines: 1, 2, 10 + +To refresh your credentials, you can declare a ``Supplier`` lambda expression +that returns new credentials as shown in the following example: + +.. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-lambda-expression + :end-before: end-aws-lambda-expression + :emphasize-lines: 4-6, 9 + +If you must provide AWS IAM credentials in a connection string, you can add +it to your ``MongoClientSettings`` by calling the `applyConnectionString() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyConnectionString(com.mongodb.ConnectionString)>`__ +method: + +.. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-aws-apply-connect-string + :end-before: end-aws-apply-connect-string + :emphasize-lines: 2, 5 + +.. _kotlin-sync-auth-x509: + +MONGODB-X509 Mechanism +---------------------- + +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 server, accessible by your client. +* ``port`` - port number of your MongoDB server. +* ``authenticationDb`` - MongoDB database that contains your user's + authentication data. If you omit this parameter, the driver uses the + default value ``admin``. + +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. Your code to instantiate a ``MongoClient`` + should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-x509-connect-string + :end-before: end-x509-connect-string + + .. 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. Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-x509-mcred + :end-before: end-x509-mcred + +For additional information on configuring your application to use +certificates as well as TLS/SSL options, see our +:ref:`TLS/SSL guide `. + +Additional Information +---------------------- + +To learn more about authenticating to MongoDB, see +:manual:`Authentication ` in the Server manual. + +To learn more about managing users of your MongoDB deployment, see +:manual:`Users ` in the Server manual. diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt new file mode 100644 index 0000000..563cb8c --- /dev/null +++ b/source/security/enterprise-auth.txt @@ -0,0 +1,22 @@ +.. _kotlin-sync-enterprise-auth: + +==================================== +Enterprise Authentication Mechanisms +==================================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: ldap, encryption, principal, tls + + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- From a2f2858cd36fb80a0d8a9fc5d515b46e32523290 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 11:38:12 -0400 Subject: [PATCH 02/29] fix build --- source/includes/security/enterprise-auth.kt | 5 + source/security.txt | 0 source/security/enterprise-auth.txt | 425 ++++++++++++++++++++ 3 files changed, 430 insertions(+) create mode 100644 source/includes/security/enterprise-auth.kt create mode 100644 source/security.txt diff --git a/source/includes/security/enterprise-auth.kt b/source/includes/security/enterprise-auth.kt new file mode 100644 index 0000000..60c7a48 --- /dev/null +++ b/source/includes/security/enterprise-auth.kt @@ -0,0 +1,5 @@ +import com.mongodb.* +import com.mongodb.kotlin.client.MongoClient +import org.bson.BsonInt64 +import org.bson.Document + diff --git a/source/security.txt b/source/security.txt new file mode 100644 index 0000000..e69de29 diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index 563cb8c..821012c 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -20,3 +20,428 @@ Enterprise Authentication Mechanisms 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 ` + +For more +information on establishing a connection to your MongoDB cluster, read our +:doc:`Connection Guide `. + + +Specify an Authentication Mechanism +----------------------------------- + +You can specify your authentication mechanism and credentials when connecting +to MongoDB using either of the following: + +- A connection string +- A ``MongoCredential`` factory method + +A **connection string** (also known as a **connection URI**) specifies how to +connect and authenticate to your MongoDB cluster. + +To authenticate using a connection string, include your settings in your +connection string and pass it to the ``MongoClient.create()`` method to +instantiate your ``MongoClient``. The :guilabel:`Connection String` +tab in each section provides the syntax for authenticating using a +**connection string**. + +Alternatively, you can use the ``MongoCredential`` class to specify your +authentication details. The ``MongoCredential`` class contains static factory +methods that construct instances containing your authentication mechanism and +credentials. When you use the ``MongoCredential`` helper class, you need +to use the ``MongoClientSettings.Builder`` class to configure your +connection settings when constructing your ``MongoClient``. The +:guilabel:`MongoCredential` tab in each section provides the syntax for +authenticating using a ``MongoCredential``. + +For more information on these classes and methods, refer to the following API +documentation: + +- `MongoClient.create() <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-client/-factory/create.html>`__ +- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-client/index.html>`__ +- `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ +- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ + +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: + +* ``Kerberos principal`` - your URL-encoded principal name, e.g. "username%40REALM.ME" +* ``hostname`` - network address of your MongoDB server, accessible by your client +* ``port`` - port number of your MongoDB server + +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``. + + Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.gssapi-connection-string.kt + :language: kotlin + + .. tab:: + :tabid: MongoCredential + + To specify the GSSAPI authentication mechanism using the + ``MongoCredential`` class, use the ``createGSSAPICredential()`` + method. Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.auth-creds-gssapi.kt + :language: kotlin + +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 may 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: + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.gssapi-properties-connection-string.kt + :language: kotlin + + .. 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 + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.service-name-key.kt + :language: kotlin + + .. tab:: + :tabid: JAVA_SUBJECT_KEY + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.java-subject-key.kt + :language: kotlin + +By default, the Kotlin 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 Kotlin driver to cache Kerberos tickets + by process should resemble the following: + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.kerberos-subject-provider.kt + :language: kotlin + +.. 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: + +* ``LDAP username`` - your LDAP username +* ``password`` - your LDAP user's password +* ``hostname`` - network address of your MongoDB server, accessible by your client +* ``port`` - port number of your MongoDB server + +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``. + + Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.ldap-connection-string.kt + :language: kotlin + + .. tab:: + :tabid: MongoCredential + + To specify the LDAP (PLAIN) authentication mechanism using the + ``MongoCredential`` class, use the ``createPlainCredential()`` + method. Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.ldap-mongo-credential.kt + :language: kotlin + +.. _kotlin-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. + +.. _kotlin-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`` instance or by specifying your credentials +in 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. + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-azure-connection-string.kt + :language: kotlin + + .. 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. + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-azure-credential.kt + :language: kotlin + +.. _kotlin-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. + +You can specify GCP IMDS OIDC authentication either by +using a ``MongoCredential`` instance or by specifying your credentials +in 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. + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-connection-string.kt + :language: kotlin + + .. tab:: MongoCredential + :tabid: mongodb-gcp-mongo-credential + + Replace the ```` placeholder with the value of the + ``audience`` server parameter configured on your MongoDB deployment. + + .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-credential.kt + :language: kotlin + +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: + +.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-callback.kt + :language: kotlin + +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: + +.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-callback-file.kt + :language: kotlin From 3adcdb7f59b8c90880af18f1e80bc32a8bb78585 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 14:36:43 -0400 Subject: [PATCH 03/29] add to toc --- source/includes/security/authentication.kt | 2 +- source/index.txt | 1 + source/security.txt | 13 +++++++++++++ 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/source/includes/security/authentication.kt b/source/includes/security/authentication.kt index 382234f..6a7851e 100644 --- a/source/includes/security/authentication.kt +++ b/source/includes/security/authentication.kt @@ -203,4 +203,4 @@ val settings = MongoClientSettings.builder() .build() val mongoClient = MongoClient.create(settings) -// end-x509-mcred \ No newline at end of file +// end-x509-mcred diff --git a/source/index.txt b/source/index.txt index e6225b1..ba6ae6d 100644 --- a/source/index.txt +++ b/source/index.txt @@ -20,6 +20,7 @@ /indexes /aggregation Use Aggregation Expression Operations + /security /data-formats /builders /compatibility diff --git a/source/security.txt b/source/security.txt index e69de29..13af024 100644 --- a/source/security.txt +++ b/source/security.txt @@ -0,0 +1,13 @@ + +================ +Secure Your Data +================ + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /security/authentication + /security/enterprise-auth + +.. placeholder \ No newline at end of file From 93c7361479c9c73c7ea7854fdd037ef0ea6cad72 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 18:44:55 -0400 Subject: [PATCH 04/29] enterprise auth ex --- snooty.toml | 4 +- source/includes/security/authentication.kt | 4 +- source/includes/security/enterprise-auth.kt | 142 ++++++++++++++++++++ source/security/enterprise-auth.txt | 92 +++++++++---- 4 files changed, 212 insertions(+), 30 deletions(-) diff --git a/snooty.toml b/snooty.toml index f6e00a7..8122753 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,8 +24,8 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" driver-long = "MongoDB Kotlin Sync Driver" driver-short = "Kotlin Sync driver" language = "Kotlin" -version-number = "5.1" -full-version = "{+version-number+}.2" +version-number = "5.2" +full-version = "{+version-number+}.0" version = "v{+version-number+}" mdb-server = "MongoDB Server" stable-api = "Stable API" diff --git a/source/includes/security/authentication.kt b/source/includes/security/authentication.kt index 6a7851e..a9f3f91 100644 --- a/source/includes/security/authentication.kt +++ b/source/includes/security/authentication.kt @@ -160,7 +160,7 @@ val credential = MongoCredential.createAwsCredential("", " - builder.hosts(listOf(ServerAddress("", ""))) + builder.hosts(listOf(ServerAddress("", ))) } .credential(credential) .build() @@ -193,7 +193,7 @@ val credential = MongoCredential.createMongoX509Credential() val settings = MongoClientSettings.builder() .applyToClusterSettings { builder -> builder.hosts(listOf( - ServerAddress("", "")) + ServerAddress("", )) ) } .applyToSslSettings { builder -> diff --git a/source/includes/security/enterprise-auth.kt b/source/includes/security/enterprise-auth.kt index 60c7a48..698ce9a 100644 --- a/source/includes/security/enterprise-auth.kt +++ b/source/includes/security/enterprise-auth.kt @@ -3,3 +3,145 @@ import com.mongodb.kotlin.client.MongoClient import org.bson.BsonInt64 import org.bson.Document +// GSSAPI + +// start-gssapi-connect-string +val connectionString = ConnectionString("@:/?authSource=$external&authMechanism=GSSAPI") +val mongoClient = MongoClient.create(connectionString) +// end-gssapi-connect-string + +// start-gssapi-mongo-cred +val credential = MongoCredential.createGSSAPICredential("") + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(listOf(ServerAddress("", ))) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-gssapi-mongo-cred + +// start-gssapi-properties-connect-string +val connectionString = ConnectionString("@:/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService") +val mongoClient = MongoClient.create(connectionString) +// end-gssapi-properties-connect-string + +// start-gssapi-service-name-key +val credential = MongoCredential.createGSSAPICredential("") + .withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService") +// end-gssapi-service-name-key + +// start-gssapi-java-subject-key +val loginContext = LoginContext("") +loginContext.login() +val subject: Subject = loginContext.subject + +val credential = MongoCredential.createGSSAPICredential("") + .withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject) +// end-gssapi-java-subject-key + +// start-gssapi-java-subject-provider +/* All MongoClient instances sharing this instance of KerberosSubjectProvider +will share a Kerberos ticket cache */ +val myLoginContext = "myContext" +/* Login context defaults to "com.sun.security.jgss.krb5.initiate" +if unspecified in KerberosSubjectProvider */ +val credential = MongoCredential.createGSSAPICredential("") + .withMechanismProperty( + MongoCredential.JAVA_SUBJECT_PROVIDER_KEY, + KerberosSubjectProvider(myLoginContext) + ) +// end-gssapi-java-subject-provider + +// LDAP + +// start-ldap-connect-string +val connectionString = ConnectionString(":@:/?authSource=$external&authMechanism=PLAIN") +val mongoClient = MongoClient.create(connectionString) +// end-ldap-connect-string + +// start-ldap-mongo-cred +val credential = MongoCredential.createPlainCredential("", "$external", "".toCharArray()) + +val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(listOf(ServerAddress("", ))) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) +// end-ldap-mongo-cred + +// OIDC + +// start-oidc-azure-connect-str +val connectionString = ConnectionString( + "mongodb://@:/?" + + "?authMechanism=MONGODB-OIDC" + + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:") +val mongoClient = MongoClient.create(connectionString) +// end-oidc-azure-connect-str + +// start-oidc-azure-mongo-cred +val credential = MongoCredential.createOidcCredential("") + .withMechanismProperty("ENVIRONMENT", "azure") + .withMechanismProperty("TOKEN_RESOURCE", "") + +val mongoClient = MongoClient.create( + MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(listOf(ServerAddress("", ))) + } + .credential(credential) + .build()) +// end-oidc-azure-mongo-cred + +// start-oidc-gcp-connect-str +val connectionString = ConnectionString( + "mongodb://@:/?" + + "authMechanism=MONGODB-OIDC" + + "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:") +val mongoClient = MongoClient.create(connectionString) +// end-oidc-gcp-connect-str + +// start-oidc-gcp-mongo-cred +val credential = MongoCredential.createOidcCredential("") + .withMechanismProperty("ENVIRONMENT", "gcp") + .withMechanismProperty("TOKEN_RESOURCE", "") + +val mongoClient = MongoClient.create( + MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(listOf(ServerAddress("", ))) + } + .credential(credential) + .build()) +// end-oidc-gcp-mongo-cred + +// start-oidc-custom-callback +val credential = MongoCredential.createOidcCredential(null) + .withMechanismProperty("OIDC_CALLBACK") { context: Context -> + val accessToken = "..." + OidcCallbackResult(accessToken) + } +// end-oidc-custom-callback + +// start-oidc-custom-callback-ex +val credential = MongoCredential.createOidcCredential(null) + .withMechanismProperty("OIDC_CALLBACK") { context: Context -> + val accessToken = String(Files.readAllBytes(Paths.get("access-token.dat"))) + OidcCallbackResult(accessToken) + } + +val mongoClient = MongoClient.create( + MongoClientSettings.builder() + .applyToClusterSettings { builder -> + builder.hosts(listOf(ServerAddress("", ))) + } + .credential(credential) + .build() +) +// end-oidc-custom-callback-ex diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index 821012c..7b6b4e1 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -32,9 +32,8 @@ Enterprise Edition: - :ref:`LDAP (PLAIN) ` - :ref:`MONGODB-OIDC ` -For more -information on establishing a connection to your MongoDB cluster, read our -:doc:`Connection Guide `. +For more information on establishing a connection to your MongoDB cluster, read our +:ref:`Connection Guide `. Specify an Authentication Mechanism @@ -67,10 +66,10 @@ authenticating using a ``MongoCredential``. For more information on these classes and methods, refer to the following API documentation: -- `MongoClient.create() <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-client/-factory/create.html>`__ -- `MongoClient <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-client/index.html>`__ -- `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ -- `MongoCredential <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ +- `MongoClient.create() <{+api+}/com.mongodb.kotlin.client/-mongo-client/-factory/index.html>`__ +- `MongoClient <{+api+}/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `MongoClientSettings.Builder <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ +- `MongoCredential <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ Mechanisms ---------- @@ -120,8 +119,11 @@ mechanism: Your code to instantiate a ``MongoClient`` should resemble the following: - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.gssapi-connection-string.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-gssapi-connect-string + :end-before: end-gssapi-connect-string .. tab:: :tabid: MongoCredential @@ -130,8 +132,11 @@ mechanism: ``MongoCredential`` class, use the ``createGSSAPICredential()`` method. Your code to instantiate a ``MongoClient`` should resemble the following: - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.auth-creds-gssapi.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-gssapi-mongo-cred + :end-before: end-gssapi-mongo-cred In order to acquire a `Kerberos ticket `__, @@ -177,8 +182,11 @@ You may need to specify one or more of the following additional Your code to instantiate a ``MongoClient`` using GSSAPI and additional properties might resemble the following: - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.gssapi-properties-connection-string.kt - :language: kotlin + .. literalinclude:: /includes/security/enterprise-auth.kt + :language: kotlin + :dedent: + :start-after: start-gssapi-properties-connect-string + :end-before: end-gssapi-properties-connect-string .. tab:: :tabid: MongoCredential @@ -203,14 +211,20 @@ You may need to specify one or more of the following additional .. tab:: :tabid: SERVICE_NAME_KEY - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.service-name-key.kt - :language: kotlin + .. literalinclude:: /includes/security/enterprise-auth.kt + :language: kotlin + :dedent: + :start-after: start-gssapi-service-name-key + :end-before: end-gssapi-service-name-key .. tab:: :tabid: JAVA_SUBJECT_KEY - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.java-subject-key.kt - :language: kotlin + .. literalinclude:: /includes/security/enterprise-auth.kt + :language: kotlin + :dedent: + :start-after: start-gssapi-java-subject-key + :end-before: end-gssapi-java-subject-key By default, the Kotlin driver caches Kerberos tickets by ``MongoClient`` instance. If your deployment needs to frequently create and destroy ``MongoClient`` instances, @@ -237,8 +251,11 @@ to improve performance. in your ``MongoCredential`` instance. The code to configure the Kotlin driver to cache Kerberos tickets by process should resemble the following: - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.kerberos-subject-provider.kt - :language: kotlin + .. literalinclude:: /includes/security/enterprise-auth.kt + :language: kotlin + :dedent: + :start-after: start-gssapi-java-subject-provider + :end-before: end-gssapi-java-subject-provider .. note:: @@ -252,7 +269,6 @@ to improve performance. - `JDK-6722928 `__ - `SO 23427343 `__ - .. _plain-auth-mechanism: LDAP (PLAIN) @@ -303,8 +319,11 @@ mechanism: Your code to instantiate a ``MongoClient`` should resemble the following: - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.ldap-connection-string.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-ldap-connect-string + :end-before: end-ldap-connect-string .. tab:: :tabid: MongoCredential @@ -313,8 +332,11 @@ mechanism: ``MongoCredential`` class, use the ``createPlainCredential()`` method. Your code to instantiate a ``MongoClient`` should resemble the following: - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.ldap-mongo-credential.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-ldap-mongo-cred + :end-before: end-ldap-mongo-cred .. _kotlin-oidc: @@ -366,8 +388,11 @@ see the corresponding syntax. You must specify values that contain commas in a ``MongoCredential`` instance, as demonstrated in the :guilabel:`MongoCredential` tab. - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-azure-connection-string.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-oidc-azure-connect-str + :end-before: end-oidc-azure-connect-str .. tab:: MongoCredential :tabid: mongodb-azure-mongo-credential @@ -377,8 +402,11 @@ see the corresponding syntax. placeholder with the value of the ``audience`` server parameter configured on your MongoDB deployment. - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-azure-credential.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-oidc-azure-mongo-cred + :end-before: end-oidc-azure-mongo-cred .. _kotlin-mongodb-oidc-gcp-imds: @@ -412,8 +440,11 @@ see the corresponding syntax. You must specify values that contain commas in a ``MongoCredential`` instance, as demonstrated in the :guilabel:`MongoCredential` tab. - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-connection-string.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-oidc-gcp-connect-str + :end-before: end-oidc-gcp-connect-str .. tab:: MongoCredential :tabid: mongodb-gcp-mongo-credential @@ -421,8 +452,11 @@ see the corresponding syntax. Replace the ```` placeholder with the value of the ``audience`` server parameter configured on your MongoDB deployment. - .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-credential.kt + .. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-oidc-gcp-mongo-cred + :end-before: end-oidc-gcp-mongo-cred Custom Callback +++++++++++++++ @@ -433,8 +467,11 @@ 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: -.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-callback.kt +.. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-oidc-custom-callback + :end-before: end-oidc-custom-callback The value of the ``"OIDC_CALLBACK"`` property must be a lambda or other implementation of the ``OidcCallback`` functional interface that accepts an ``OidcCallbackContext`` @@ -443,5 +480,8 @@ 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: -.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-callback-file.kt +.. literalinclude:: /includes/security/enterprise-auth.kt :language: kotlin + :dedent: + :start-after: start-oidc-custom-callback-ex + :end-before: end-oidc-custom-callback-ex From bb380534e05d70fb07260f177a4714e1c45f97dc Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 18:59:20 -0400 Subject: [PATCH 05/29] broken link fix --- source/security/authentication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 1ff8871..7a2903a 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -258,7 +258,7 @@ MONGODB-AWS Mechanism 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 ` +:atlas:`Set Up Passwordless Authentication with AWS IAM Roles ` guide. To instruct the driver to use this authentication mechanism, you can specify From 7f14924c2a0448db5cb64085fb40fceb88542e9b Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 19:05:19 -0400 Subject: [PATCH 06/29] link fix --- source/security/authentication.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 7a2903a..c22f812 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -258,7 +258,7 @@ MONGODB-AWS Mechanism 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 ` +:atlas:`Set Up Authentication with AWS IAM ` guide. To instruct the driver to use this authentication mechanism, you can specify @@ -435,7 +435,7 @@ 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)>`__ +for ``MONGODB-AWS`` authentication, use the `createAwsCredential() <{+core-api+}/com/mongodb/MongoCredential.html#createAwsCredential(java.lang.String,char%5B%5D)>`__ factory method. You can supply only programmatic access keys to the From 0201d91d93c65074441da52be88c2fcbff7edd2d Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 19:06:11 -0400 Subject: [PATCH 07/29] link fix --- source/security/authentication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index c22f812..8b95c0c 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -462,7 +462,7 @@ in the following example: :emphasize-lines: 1, 9 If you need to specify an AWS session token, pass it to the -`withMechanismProperty() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__ +`withMechanismProperty() <{+core-api+}/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__ method as shown in the following example: .. literalinclude:: /includes/security/authentication.kt From a35a4d9c165783c63dc4b44935bf69bc7df06973 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 19:08:03 -0400 Subject: [PATCH 08/29] last link fix for auth --- source/security/authentication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 8b95c0c..a1c2dc5 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -483,7 +483,7 @@ that returns new credentials as shown in the following example: :emphasize-lines: 4-6, 9 If you must provide AWS IAM credentials in a connection string, you can add -it to your ``MongoClientSettings`` by calling the `applyConnectionString() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyConnectionString(com.mongodb.ConnectionString)>`__ +it to your ``MongoClientSettings`` by calling the `applyConnectionString() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyConnectionString(com.mongodb.ConnectionString)>`__ method: .. literalinclude:: /includes/security/authentication.kt From 0e46d1f589d0b3af258ec3946fdc0323b269e627 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 19:12:40 -0400 Subject: [PATCH 09/29] enterprise auth links --- source/security/enterprise-auth.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index 7b6b4e1..2aeb9d5 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -196,11 +196,11 @@ You may need to specify one or more of the following additional 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>`__ + - `SERVICE_NAME_KEY <{+core-api+}/com/mongodb/MongoCredential.html#SERVICE_NAME_KEY>`__ + - `CANONICALIZE_HOST_NAME_KEY <{+core-api+}/com/mongodb/MongoCredential.html#CANONICALIZE_HOST_NAME_KEY>`__ + - `JAVA_SUBJECT_KEY <{+core-api+}/com/mongodb/MongoCredential.html#JAVA_SUBJECT_KEY>`__ + - `JAVA_SASL_CLIENT_PROPERTIES_KEY <{+core-api+}/com/mongodb/MongoCredential.html#JAVA_SASL_CLIENT_PROPERTIES_KEY>`__ + - `JAVA_SUBJECT_PROVIDER_KEY <{+core-api+}/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 From 2fe9ea3d9891ff76c5a256d3b8972239834ee2e2 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 3 Oct 2024 19:23:42 -0400 Subject: [PATCH 10/29] fix --- source/security/enterprise-auth.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index 2aeb9d5..b138ccf 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -259,7 +259,7 @@ to improve performance. .. note:: - On Windows, Oracle’s JRE uses `LSA `__ + 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 From 7c55fc83c55b15f0990b2c8dd821a46561b91ac1 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 4 Oct 2024 14:34:37 -0400 Subject: [PATCH 11/29] enterprise standardize --- source/security/enterprise-auth.txt | 62 ++++++++--------------------- 1 file changed, 17 insertions(+), 45 deletions(-) diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index b138ccf..26f1577 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -35,49 +35,10 @@ Enterprise Edition: For more information on establishing a connection to your MongoDB cluster, read our :ref:`Connection Guide `. - -Specify an Authentication Mechanism ------------------------------------ - -You can specify your authentication mechanism and credentials when connecting -to MongoDB using either of the following: - -- A connection string -- A ``MongoCredential`` factory method - -A **connection string** (also known as a **connection URI**) specifies how to -connect and authenticate to your MongoDB cluster. - -To authenticate using a connection string, include your settings in your -connection string and pass it to the ``MongoClient.create()`` method to -instantiate your ``MongoClient``. The :guilabel:`Connection String` -tab in each section provides the syntax for authenticating using a -**connection string**. - -Alternatively, you can use the ``MongoCredential`` class to specify your -authentication details. The ``MongoCredential`` class contains static factory -methods that construct instances containing your authentication mechanism and -credentials. When you use the ``MongoCredential`` helper class, you need -to use the ``MongoClientSettings.Builder`` class to configure your -connection settings when constructing your ``MongoClient``. The -:guilabel:`MongoCredential` tab in each section provides the syntax for -authenticating using a ``MongoCredential``. - -For more information on these classes and methods, refer to the following API -documentation: - -- `MongoClient.create() <{+api+}/com.mongodb.kotlin.client/-mongo-client/-factory/index.html>`__ -- `MongoClient <{+api+}/com.mongodb.kotlin.client/-mongo-client/index.html>`__ -- `MongoClientSettings.Builder <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ -- `MongoCredential <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ - -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 @@ -272,7 +233,7 @@ to improve performance. .. _plain-auth-mechanism: LDAP (PLAIN) -~~~~~~~~~~~~ +------------ *Available in MongoDB Enterprise Edition 3.4 and later.* @@ -341,7 +302,7 @@ mechanism: .. _kotlin-oidc: MONGODB-OIDC -~~~~~~~~~~~~ +------------ .. important:: @@ -359,7 +320,7 @@ in the MongoDB Server manual. .. _kotlin-mongodb-oidc-azure-imds: Azure IMDS -++++++++++ +~~~~~~~~~~ If your application runs on an Azure VM, or otherwise uses the `Azure Instance Metadata Service `__ @@ -411,7 +372,7 @@ see the corresponding syntax. .. _kotlin-mongodb-oidc-gcp-imds: GCP IMDS -++++++++ +~~~~~~~~ If your application runs on a Google Compute Engine VM, or otherwise uses the `GCP Instance Metadata Service `__, @@ -459,7 +420,7 @@ see the corresponding syntax. :end-before: end-oidc-gcp-mongo-cred Custom Callback -+++++++++++++++ +~~~~~~~~~~~~~~~ The {+driver-short+} doesn't offer built-in support for all platforms, including Azure Functions and Azure Kubernetes Service (AKS). Instead, you @@ -485,3 +446,14 @@ named ``"access-token.dat"`` in the local file system: :dedent: :start-after: start-oidc-custom-callback-ex :end-before: end-oidc-custom-callback-ex + +API Documentation +----------------- + +To learn more about the classes and methods for authenticating your application +with {+driver-short+}, see the following API documentation: + +- `MongoClient.create() <{+api+}/com.mongodb.kotlin.client/-mongo-client/-factory/index.html>`__ +- `MongoClient <{+api+}/com.mongodb.kotlin.client/-mongo-client/index.html>`__ +- `MongoClientSettings.Builder <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ +- `MongoCredential <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__ From a5eb7286e1366223136d64a207b5b067ab789f87 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 4 Oct 2024 15:00:17 -0400 Subject: [PATCH 12/29] authen remodel --- source/security/authentication.txt | 53 +++++++++++------------------- 1 file changed, 20 insertions(+), 33 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index a1c2dc5..0bba13d 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -25,19 +25,10 @@ In this guide, you can learn how to authenticate with MongoDB using each Authentication mechanisms are processes by which the driver and server confirm identity and establish trust to ensure security. -This guide describes the following authentication mechanisms: - -- :ref:`SCRAM-Based Mechanisms ` -- :ref:`MONGODB-AWS Mechanism ` -- :ref:`MONGODB-X509 Mechanism ` - To select a specific authentication mechanism, you can specify the mechanism, your credentials, and other necessary information in the options of your connection string or in a ``Credential`` struct. -In this guide, the examples demonstrate how to configure -authentication in a ``Credential`` struct. - To learn more about the connection string options for authentication, see the :manual:`Authentication Options ` section @@ -49,25 +40,21 @@ To authenticate using ``Kerberos`` or ``LDAP``, see the For more information on establishing a connection to your MongoDB cluster, see :ref:`Connect to MongoDB `. -.. _kotlin-sync-auth-scram-mechanisms: +.. _kotlin-sybc-auth-default: -SCRAM-Based Mechanisms ----------------------- +Default +------- -Salted challenge response authentication mechanism (SCRAM) refers to a -group of authentication mechanisms that use a username and -password to authenticate to a server. +The default authentication mechanism setting uses one of the following +authentication mechanisms depending on what your MongoDB server supports: -MongoDB supports the following SCRAM-based authentication mechanisms: +#. ``SCRAM-SHA-256`` +#. ``SCRAM-SHA-1`` -- :ref:`SCRAM-SHA-256 `: an authentication mechanism that - uses your database username and password, encrypted with the ``SHA-256`` - algorithm -- :ref:`SCRAM-SHA-1 `: an authentication mechanism that - uses your database username and password, encrypted with the ``SHA-1`` - algorithm +Server versions 4.0 and later use ``SCRAM-SHA-256`` as the default +mechanism. -The following code snippets show how to specify the authentication mechanism, +The following code snippets show how to use the default authentication mechanism, using the following placeholders: * ``db_username`` - your MongoDB database username @@ -82,8 +69,6 @@ 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:: @@ -123,14 +108,15 @@ the Server manual. .. _kotlin-sync-auth-scramsha256: 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-SHA-256``, as defined by `RFC 7677 `__, +is a salted challenge-response authentication mechanism (SCRAM) that uses your username and password, encrypted with the ``SHA-256`` algorithm, to authenticate your user. @@ -186,13 +172,14 @@ mechanism: .. _kotlin-sync-auth-scramsha1: 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 +``SCRAM-SHA-1``, as defined by `RFC 5802 `__, +is a salted challenge-response mechanism (SCRAM) that uses your username and password, encrypted with the ``SHA-1`` algorithm, to authenticate your user. @@ -247,8 +234,8 @@ mechanism: .. _kotlin-sync-auth-aws: -MONGODB-AWS Mechanism ---------------------- +MONGODB-AWS +----------- .. note:: @@ -495,8 +482,8 @@ method: .. _kotlin-sync-auth-x509: -MONGODB-X509 Mechanism ----------------------- +MONGODB-X509 +------------ The ``X.509`` authentication mechanism uses :wikipedia:`TLS ` with X.509 certificates to From bfcc8200e01e188c8d45bfdcd39349469deb03d1 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 4 Oct 2024 15:04:11 -0400 Subject: [PATCH 13/29] move x509 up --- source/security/authentication.txt | 128 ++++++++++++++--------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 0bba13d..d295319 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -232,6 +232,70 @@ mechanism: :start-after: start-scramsha1-mongo-cred :end-before: end-scramsha1-mongo-cred +.. _kotlin-sync-auth-x509: + +MONGODB-X509 +------------ + +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 server, accessible by your client. +* ``port`` - port number of your MongoDB server. +* ``authenticationDb`` - MongoDB database that contains your user's + authentication data. If you omit this parameter, the driver uses the + default value ``admin``. + +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. Your code to instantiate a ``MongoClient`` + should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-x509-connect-string + :end-before: end-x509-connect-string + + .. 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. Your code to instantiate a ``MongoClient`` should resemble the following: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-x509-mcred + :end-before: end-x509-mcred + +For additional information on configuring your application to use +certificates as well as TLS/SSL options, see our +:ref:`TLS/SSL guide `. + .. _kotlin-sync-auth-aws: MONGODB-AWS @@ -480,70 +544,6 @@ method: :end-before: end-aws-apply-connect-string :emphasize-lines: 2, 5 -.. _kotlin-sync-auth-x509: - -MONGODB-X509 ------------- - -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 server, accessible by your client. -* ``port`` - port number of your MongoDB server. -* ``authenticationDb`` - MongoDB database that contains your user's - authentication data. If you omit this parameter, the driver uses the - default value ``admin``. - -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. Your code to instantiate a ``MongoClient`` - should resemble the following: - - .. literalinclude:: /includes/security/authentication.kt - :language: kotlin - :dedent: - :start-after: start-x509-connect-string - :end-before: end-x509-connect-string - - .. 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. Your code to instantiate a ``MongoClient`` should resemble the following: - - .. literalinclude:: /includes/security/authentication.kt - :language: kotlin - :dedent: - :start-after: start-x509-mcred - :end-before: end-x509-mcred - -For additional information on configuring your application to use -certificates as well as TLS/SSL options, see our -:ref:`TLS/SSL guide `. - Additional Information ---------------------- From 09ff82a96b340fc389ba4406d89dda53f37f3e7a Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 16 Oct 2024 14:05:48 -0400 Subject: [PATCH 14/29] add ref --- source/connect/mongoclient.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 7c8da8d..b0e6b0d 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -59,6 +59,8 @@ A standard connection string includes the following components: - Optional. Authentication credentials. If you include these, the client authenticates the user against the database specified in ``authSource``. + For more information about the ``authSource`` connection option, + see :ref:`kotlin-sync-auth`. * - ``host[:port]`` From 93f7b42e3f671173e244c1addbacf63b5f351976 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 16 Oct 2024 14:07:45 -0400 Subject: [PATCH 15/29] remove note --- source/connect/mongoclient.txt | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index b0e6b0d..8bb3103 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -40,9 +40,6 @@ Connection URI A standard connection string includes the following components: -.. TODO, add this as last sentence for ``username:password`` description once a kotlin auth page is made: -.. For more information about the ``authSource`` connection option, see :ref:`kotlin-sync-auth`. - .. list-table:: :widths: 20 80 :header-rows: 1 From e221a8907381ac3abf6b26862a5a08fbcc27b6ca Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 16 Oct 2024 16:34:49 -0400 Subject: [PATCH 16/29] review comments --- source/security/authentication.txt | 86 +++++++++++++++--------------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index d295319..6b60cd6 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -20,27 +20,24 @@ Authentication Mechanisms 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 server -confirm identity and establish trust to ensure security. +In this guide, you can learn how to authenticate to a MongoDB Server by using +each **authentication mechanism** available in the {+driver-long+}. +Authentication is the process by which the driver proves its identity to the +server to ensure security. -To select a specific authentication mechanism, you can specify the -mechanism, your credentials, and other necessary information -in the options of your connection string or in a ``Credential`` struct. +To learn more about the connection string formats and authentication options, +see the :manual:`Connection String Formats +` section +of the Connection Strings guide in the Server manual. -To learn more about the connection string options for authentication, -see the :manual:`Authentication Options -` section -of the Connection String URI Format guide in the Server manual. +.. note:: Enterprise Authentication Mechanisms -To authenticate using ``Kerberos`` or ``LDAP``, see the -:ref:`Enterprise Authentication Mechanisms guide `. + This page describes the authentication mechanisms available in MongoDB + Community Edition. To authenticate with mechanisms available in + the MongoDB Enterprise Edition, like ``Kerberos`` or ``LDAP``, see the + :ref:`Enterprise Authentication Mechanisms guide `. -For more information on establishing a connection to your MongoDB cluster, -see :ref:`Connect to MongoDB `. - -.. _kotlin-sybc-auth-default: +.. _kotlin-sync-auth-default: Default ------- @@ -48,13 +45,17 @@ Default The default authentication mechanism setting uses one of the following authentication mechanisms depending on what your MongoDB server supports: -#. ``SCRAM-SHA-256`` -#. ``SCRAM-SHA-1`` +#. ``SCRAM-SHA-256``: An authentication mechanism that + uses your database username and password, encrypted with the ``SHA-256`` + algorithm +#. ``SCRAM-SHA-1``: An authentication mechanism that + uses your database username and password, encrypted with the ``SHA-1`` + algorithm Server versions 4.0 and later use ``SCRAM-SHA-256`` as the default mechanism. -The following code snippets show how to use the default authentication mechanism, +The following code snippets show how to use the default authentication mechanism by using the following placeholders: * ``db_username`` - your MongoDB database username @@ -74,7 +75,7 @@ mechanism: .. tab:: :tabid: Connection String - To specify the default authentication mechanism using a connection + To specify the default authentication mechanism by using a connection string, omit the mechanism. Your code to instantiate a ``MongoClient`` should resemble the following: @@ -87,7 +88,7 @@ mechanism: .. tab:: :tabid: MongoCredential - To specify the default authentication mechanism using the + To specify the default authentication mechanism by using the ``MongoCredential`` class, use the ``createCredential()`` method. Also, enable TLS by calling the `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ @@ -101,9 +102,8 @@ mechanism: :end-before: end-default-mongo-cred :dedent: -For more information on salted challenge-response authentication mechanisms (SCRAM) -that MongoDB supports, see the :manual:`SCRAM ` section of -the Server manual. +For more information about using SCRAM with MongoDB, see the +:manual:`SCRAM ` section of the Server manual. .. _kotlin-sync-auth-scramsha256: @@ -116,11 +116,11 @@ SCRAM-SHA-256 in MongoDB 4.0. ``SCRAM-SHA-256``, as defined by `RFC 7677 `__, -is a salted challenge-response authentication mechanism +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, +The following code snippets show how to specify the authentication mechanism by using the following placeholders: * ``db_username`` - your MongoDB database username. @@ -140,7 +140,7 @@ mechanism: .. tab:: :tabid: Connection String - To specify the ``SCRAM-SHA-256`` authentication mechanism using a + 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. Your code to instantiate a ``MongoClient`` should resemble the following: @@ -154,7 +154,7 @@ mechanism: .. tab:: :tabid: MongoCredential - To specify the default authentication mechanism using the + To specify the default authentication mechanism by 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. Also, enable TLS by calling the @@ -179,12 +179,12 @@ SCRAM-SHA-1 3.0, 3.2, 3.4, and 3.6. ``SCRAM-SHA-1``, as defined by `RFC 5802 `__, -is a salted challenge-response mechanism (SCRAM) that uses your +is a Salted Challenge Response Authentication 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: +The following code snippets show how to specify the authentication mechanism +by using the following placeholders: * ``db_username`` - your MongoDB database username. * ``db_password`` - your MongoDB database user's password. @@ -203,7 +203,7 @@ mechanism: .. tab:: :tabid: Connection String - To specify the ``SCRAM-SHA-1`` authentication mechanism using a + 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. Your code to instantiate a ``MongoClient`` should resemble the following: @@ -217,7 +217,7 @@ mechanism: .. tab:: :tabid: MongoCredential - To specify the default authentication mechanism using the + To specify the default authentication mechanism by 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. Also, enable TLS by calling the @@ -241,11 +241,11 @@ 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 +authentication mechanism, the server authenticates the connection by using the subject name of the client certificate. -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: +The following code snippets show how to specify the authentication mechanism +by using the following placeholders: * ``hostname`` - network address of your MongoDB server, accessible by your client. * ``port`` - port number of your MongoDB server. @@ -262,7 +262,7 @@ mechanism: .. tab:: :tabid: Connection String - To specify the ``X.509`` authentication mechanism using a connection + To specify the ``X.509`` authentication mechanism by using a connection string, assign the ``authMechanism`` parameter the value ``MONGODB-X509`` and enable TLS by assigning the ``tls`` parameter a ``true`` value. Your code to instantiate a ``MongoClient`` @@ -277,7 +277,7 @@ mechanism: .. tab:: :tabid: MongoCredential - To specify the ``X.509`` authentication mechanism using the + To specify the ``X.509`` authentication mechanism by 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 @@ -345,7 +345,7 @@ 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 +#. Supply your credentials by using one of the methods in the credential provider chain To specify the authentication mechanism by using a ``MongoCredential``, @@ -379,10 +379,10 @@ AWS documentation for the version you need: .. note:: - For the AWS SDK for Java v2, the Java driver currently tests using the + For the AWS SDK for Java v2, the Java driver currently tests by using the ``software.amazon.awssdk:auth:2.18.9`` dependency. - For the AWS SDK for Java v1, the Java driver currently tests using the + For the AWS SDK for Java v1, the Java driver currently tests by using the ``com.amazonaws:aws-java-sdk-core:1.12.337`` dependency. To supply your credentials, see the following AWS documentation for the @@ -475,7 +475,7 @@ a similar shell as shown in the following example: export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= -To authenticate using **EC2 container credentials**, make sure none of the +To authenticate by using **EC2 container credentials**, make sure none of the aforementioned environment variables are set. The driver obtains the credentials from the default IPv4 EC2 instance metadata endpoint. From 8bcf76fca97cf502cb157c77d754ae6977159640 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 16 Oct 2024 16:40:37 -0400 Subject: [PATCH 17/29] fix link --- source/security/authentication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 6b60cd6..f6b50f9 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -27,7 +27,7 @@ server to ensure security. To learn more about the connection string formats and authentication options, see the :manual:`Connection String Formats -` section +` section of the Connection Strings guide in the Server manual. .. note:: Enterprise Authentication Mechanisms From 015886e3a5a92ad7d873c67fcb0fa64b7f3be7fb Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Oct 2024 17:14:17 -0400 Subject: [PATCH 18/29] first round --- source/security/authentication.txt | 52 ++++++++++++++--------------- source/security/enterprise-auth.txt | 14 ++++---- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index f6b50f9..b513478 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -52,17 +52,17 @@ authentication mechanisms depending on what your MongoDB server supports: uses your database username and password, encrypted with the ``SHA-1`` algorithm -Server versions 4.0 and later use ``SCRAM-SHA-256`` as the default -mechanism. +{+mdb-server+} versions 4.0 and later use ``SCRAM-SHA-256`` as the default +authentication mechanism. The following code snippets show how to use the default authentication mechanism by using the following placeholders: -* ``db_username`` - your MongoDB database username -* ``db_password`` - your MongoDB database user's password -* ``hostname`` - network address of your MongoDB server, accessible by your client -* ``port`` - port number of your MongoDB server -* ``authenticationDb`` - MongoDB database that contains your user's +* ``db_username``: your MongoDB database username +* ``db_password``: your MongoDB database user's password +* ``hostname``: network address of your MongoDB server, accessible by your client +* ``port``: port number of your MongoDB server +* ``authenticationDb``: MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -123,11 +123,11 @@ algorithm, to authenticate your user. The following code snippets show how to specify the authentication mechanism by using the following placeholders: -* ``db_username`` - your MongoDB database username. -* ``db_password`` - your MongoDB database user's password. -* ``hostname`` - network address of your MongoDB server, accessible by your client. -* ``port`` - port number of your MongoDB server. -* ``authenticationDb`` - MongoDB database that contains your user's +* ``db_username``: your MongoDB database username. +* ``db_password``: your MongoDB database user's password. +* ``hostname``: network address of your MongoDB server, accessible by your client. +* ``port``: port number of your MongoDB server. +* ``authenticationDb``: MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -186,11 +186,11 @@ your user. The following code snippets show how to specify the authentication mechanism by using the following placeholders: -* ``db_username`` - your MongoDB database username. -* ``db_password`` - your MongoDB database user's password. -* ``hostname`` - network address of your MongoDB server, accessible by your client. -* ``port`` - port number of your MongoDB server. -* ``authenticationDb`` - MongoDB database that contains your user's +* ``db_username``: your MongoDB database username. +* ``db_password``: your MongoDB database user's password. +* ``hostname``: network address of your MongoDB server, accessible by your client. +* ``port``: port number of your MongoDB server. +* ``authenticationDb``: MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -247,9 +247,9 @@ the subject name of the client certificate. The following code snippets show how to specify the authentication mechanism by using the following placeholders: -* ``hostname`` - network address of your MongoDB server, accessible by your client. -* ``port`` - port number of your MongoDB server. -* ``authenticationDb`` - MongoDB database that contains your user's +* ``hostname``: network address of your MongoDB deployment, accessible by your client. +* ``port``: port number of your MongoDB server. +* ``authenticationDb``: MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -321,12 +321,12 @@ provide your AWS IAM credentials in the next sections. These sections contain code examples that use the following placeholders: -* ``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 +* ``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 .. _kotlin-mongodb-aws-sdk: diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index 26f1577..3cb7f7c 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -54,9 +54,9 @@ principal name. The following code snippets show how to specify the authentication mechanism, using the following placeholders: -* ``Kerberos principal`` - your URL-encoded principal name, e.g. "username%40REALM.ME" -* ``hostname`` - network address of your MongoDB server, accessible by your client -* ``port`` - port number of your MongoDB server +* ``Kerberos principal``: your URL-encoded principal name, e.g. "username%40REALM.ME" +* ``hostname``: network address of your MongoDB deployment, accessible by your client +* ``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 @@ -253,10 +253,10 @@ parameter to ``PLAIN`` and including your LDAP username and password in the The following code snippets show how to specify the authentication mechanism, using the following placeholders: -* ``LDAP username`` - your LDAP username -* ``password`` - your LDAP user's password -* ``hostname`` - network address of your MongoDB server, accessible by your client -* ``port`` - port number of your MongoDB server +* ``LDAP username``: your LDAP username +* ``password``: your LDAP user's password +* ``hostname``: network address of your MongoDB deployment, accessible by your client +* ``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 From ade5e21975e02d3af1561b81d2430bb71ecbddef Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 23 Oct 2024 14:41:41 -0400 Subject: [PATCH 19/29] fix core api links --- source/security/authentication.txt | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index b513478..3dfe896 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -25,11 +25,6 @@ each **authentication mechanism** available in the {+driver-long+}. Authentication is the process by which the driver proves its identity to the server to ensure security. -To learn more about the connection string formats and authentication options, -see the :manual:`Connection String Formats -` section -of the Connection Strings guide in the Server manual. - .. note:: Enterprise Authentication Mechanisms This page describes the authentication mechanisms available in MongoDB @@ -156,11 +151,11 @@ mechanism: To specify the default authentication mechanism by using the ``MongoCredential`` class, use the - `createScramSha256Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__ + `createScramSha256Credential() <{+core-api+}/com/mongodb/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__ method. Also, enable TLS by calling the - `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ + `applyToSslSettings() <{+core-api+}/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>`__ + `SslSettings.Builder <{+core-api+}/com/mongodb/connection/SslSettings.Builder.html>`__ block. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt @@ -219,11 +214,11 @@ mechanism: To specify the default authentication mechanism by using the ``MongoCredential`` class, use the - `createScramSha1Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ + `createScramSha1Credential() <{+core-api+}/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ method. Also, enable TLS by calling the - `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ + `applyToSslSettings() <{+api+}/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>`__ + `SslSettings.Builder <{+api+}/com/mongodb/connection/SslSettings.Builder.html>`__ block. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt @@ -279,11 +274,11 @@ mechanism: To specify the ``X.509`` authentication mechanism by using the ``MongoCredential`` class, use the - `createMongoX509Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createMongoX509Credential(java.lang.String)>`__ + `createMongoX509Credential() <{+api+}/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)>`__ + `applyToSslSettings() <{+api+}/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>`__ + `SslSettings.Builder <{+api+}/com/mongodb/connection/SslSettings.Builder.html>`__ block. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt From d75ca0a8a04665228b04516ba4f8e1b198ee6451 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 23 Oct 2024 16:06:21 -0400 Subject: [PATCH 20/29] last comments --- source/security/authentication.txt | 136 +++++++++++++++-------------- 1 file changed, 72 insertions(+), 64 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 3dfe896..9582822 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -53,11 +53,11 @@ authentication mechanism. The following code snippets show how to use the default authentication mechanism by using the following placeholders: -* ``db_username``: your MongoDB database username -* ``db_password``: your MongoDB database user's password -* ``hostname``: network address of your MongoDB server, accessible by your client -* ``port``: port number of your MongoDB server -* ``authenticationDb``: MongoDB database that contains your user's +* ``db_username``: Your MongoDB database username. +* ``db_password``: Your MongoDB database user's password. +* ``hostname``: The network address of your MongoDB deployment, accessible by your client. +* ``port``: The port number of your MongoDB deployment. +* ``authenticationDb``: The MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -107,8 +107,8 @@ SCRAM-SHA-256 .. note:: - ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting - in MongoDB 4.0. + ``SCRAM-SHA-256`` is the default authentication method for {+mdb-server+} + versions 4.0 and later. ``SCRAM-SHA-256``, as defined by `RFC 7677 `__, is a Salted Challenge Response Authentication Mechanism @@ -118,11 +118,11 @@ algorithm, to authenticate your user. The following code snippets show how to specify the authentication mechanism by using the following placeholders: -* ``db_username``: your MongoDB database username. -* ``db_password``: your MongoDB database user's password. -* ``hostname``: network address of your MongoDB server, accessible by your client. -* ``port``: port number of your MongoDB server. -* ``authenticationDb``: MongoDB database that contains your user's +* ``db_username``: Your MongoDB database username. +* ``db_password``: Your MongoDB database user's password. +* ``hostname``: The network address of your MongoDB deployment, accessible by your client. +* ``port``: The port number of your MongoDB deployment. +* ``authenticationDb``: The MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -171,7 +171,7 @@ SCRAM-SHA-1 .. note:: ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions - 3.0, 3.2, 3.4, and 3.6. + {+mdb-server+} versions 3.6 and earlier. ``SCRAM-SHA-1``, as defined by `RFC 5802 `__, is a Salted Challenge Response Authentication Mechanism (SCRAM) that uses your @@ -181,11 +181,11 @@ your user. The following code snippets show how to specify the authentication mechanism by using the following placeholders: -* ``db_username``: your MongoDB database username. -* ``db_password``: your MongoDB database user's password. -* ``hostname``: network address of your MongoDB server, accessible by your client. -* ``port``: port number of your MongoDB server. -* ``authenticationDb``: MongoDB database that contains your user's +* ``db_username``: Your MongoDB database username. +* ``db_password``: Your MongoDB database user's password. +* ``hostname``: The network address of your MongoDB deployment, accessible by your client. +* ``port``: The port number of your MongoDB deployment. +* ``authenticationDb``: The MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -232,10 +232,9 @@ mechanism: MONGODB-X509 ------------ -The ``X.509`` authentication mechanism uses +The ``MONGODB-X509`` 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`` +authenticate your user. When you specify the ``X.509`` authentication mechanism, the server authenticates the connection by using the subject name of the client certificate. @@ -288,7 +287,7 @@ mechanism: :end-before: end-x509-mcred For additional information on configuring your application to use -certificates as well as TLS/SSL options, see our +certificates as well as TLS/SSL options, see the :ref:`TLS/SSL guide `. .. _kotlin-sync-auth-aws: @@ -307,12 +306,12 @@ user. To learn more about configuring MongoDB Atlas, see the :atlas:`Set Up Authentication with AWS IAM ` 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 +To instruct the driver to use this authentication mechanism, you can either +specify ``MONGODB-AWS`` as a parameter in the connection string or call 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. +In the following sections, you can learn different ways to specify the +``MONGODB-AWS`` authentication mechanism and provide your AWS IAM credentials. These sections contain code examples that use the following placeholders: @@ -328,24 +327,32 @@ These sections contain code examples that use the following placeholders: AWS SDK ~~~~~~~ -You can use one of the AWS SDK for Java v1 or v2 to specify your credentials. -This method offers the following features: +.. note:: End of Support for AWS SDK for Java v1 + + The AWS SDK for Java v1 will reach end of support on Decemeber 31, 2025. + AWS recommends migrating to AWS SDK for Java v2. For more information, + see the `end of support announcement + `__ + on the AWS site. + +AWS provides software development kits (SDKs) for Java v1 and v2. +The AWS SDK 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 `__. +- 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: +To use the AWS SDK for ``MONGODB-AWS`` authentication, you must +perform the following steps: -1. Specify the authentication mechanism -#. Add the SDK as a dependency to your project +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 + 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 +To specify the ``MONGODB-AWS`` authentication mechanism by using a ``MongoCredential`` +object, call the ``MongoCredential.createAwsCredential()`` factory method +and add the ``MongoCredential`` instance to your ``MongoClient``, as shown in the following example: .. literalinclude:: /includes/security/authentication.kt @@ -355,8 +362,8 @@ in the following example: :end-before: end-aws-sdk-mcred :emphasize-lines: 1, 9 -To specify the authentication mechanism in the connection string, add -it as a parameter as shown in the following example: +To specify the ``MONGODB-AWS`` authentication mechanism in the connection string, +add it as a parameter, as shown in the following example: .. literalinclude:: /includes/security/authentication.kt :language: kotlin @@ -416,15 +423,15 @@ 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 +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. +You can specify the ``MONGODB-AWS`` authentication mechanism by using a +``MongoCredential`` object 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 +To specify the authentication mechanism by using a ``MongoCredential`` object, +call the ``MongoCredential.createAwsCredential()`` factory method and add the +``MongoCredential`` instance to your ``MongoClient``, as shown in the following example: .. literalinclude:: /includes/security/authentication.kt @@ -434,8 +441,8 @@ example: :end-before: end-aws-env-mcred :emphasize-lines: 1, 9 -To specify the authentication mechanism in the connection string, add it as a -parameter as shown in the following example: +To specify the ``MONGODB-AWS`` authentication mechanism in the connection +string, add it as a parameter as shown in the following example: .. literalinclude:: /includes/security/authentication.kt :language: kotlin @@ -464,7 +471,7 @@ session token for that role. 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: +a similar shell, as shown in the following example: .. code-block:: bash @@ -481,23 +488,24 @@ 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() <{+core-api+}/com/mongodb/MongoCredential.html#createAwsCredential(java.lang.String,char%5B%5D)>`__ +for ``MONGODB-AWS`` authentication, call the +`createAwsCredential() <{+core-api+}/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 need to supply ECS -or EC2 container credentials, use the instructions in +or EC2 container credentials, follow the instructions in :ref:`` or :ref:``. -To use the ``MongoCredential`` for ``MONGODB-AWS`` authentication, you -must perform the following: +To use a ``MongoCredential`` object for ``MONGODB-AWS`` authentication, you +must perform the following steps: -1. Specify the authentication mechanism -#. Supply the credentials +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 +To specify the authentication mechanism by using a ``MongoCredential`` object, +call the ``MongoCredential.createAwsCredential()`` factory method +and add the ``MongoCredential`` instance to your ``MongoClient``, as shown in the following example: .. literalinclude:: /includes/security/authentication.kt @@ -509,7 +517,7 @@ in the following example: If you need to specify an AWS session token, pass it to the `withMechanismProperty() <{+core-api+}/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__ -method as shown in the following example: +method, as shown in the following example: .. literalinclude:: /includes/security/authentication.kt :language: kotlin @@ -519,7 +527,7 @@ method as shown in the following example: :emphasize-lines: 1, 2, 10 To refresh your credentials, you can declare a ``Supplier`` lambda expression -that returns new credentials as shown in the following example: +that returns new credentials, as shown in the following example: .. literalinclude:: /includes/security/authentication.kt :language: kotlin @@ -529,7 +537,7 @@ that returns new credentials as shown in the following example: :emphasize-lines: 4-6, 9 If you must provide AWS IAM credentials in a connection string, you can add -it to your ``MongoClientSettings`` by calling the `applyConnectionString() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyConnectionString(com.mongodb.ConnectionString)>`__ +it to your ``MongoClientSettings`` object by calling the `applyConnectionString() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyConnectionString(com.mongodb.ConnectionString)>`__ method: .. literalinclude:: /includes/security/authentication.kt @@ -543,7 +551,7 @@ Additional Information ---------------------- To learn more about authenticating to MongoDB, see -:manual:`Authentication ` in the Server manual. +:manual:`Authentication ` in the {+mdb-server+} manual. To learn more about managing users of your MongoDB deployment, see -:manual:`Users ` in the Server manual. +:manual:`Users ` in the {+mdb-server+} manual. From a018a87acc04d59396d16264f5559241c91b0467 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 23 Oct 2024 16:12:03 -0400 Subject: [PATCH 21/29] link run through --- source/security/authentication.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 9582822..e728436 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -86,9 +86,9 @@ mechanism: To specify the default authentication mechanism by using the ``MongoCredential`` class, use the ``createCredential()`` method. Also, enable TLS by calling the - `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ + `applyToSslSettings() <{+core-api+}/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>`__ + `SslSettings.Builder <{+core-api+}/com/mongodb/connection/SslSettings.Builder.html>`__ block. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt @@ -216,9 +216,9 @@ mechanism: ``MongoCredential`` class, use the `createScramSha1Credential() <{+core-api+}/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ method. Also, enable TLS by calling the - `applyToSslSettings() <{+api+}/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ + `applyToSslSettings() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ method and setting the ``enabled`` property to ``true`` in the - `SslSettings.Builder <{+api+}/com/mongodb/connection/SslSettings.Builder.html>`__ + `SslSettings.Builder <{+core-api+}/com/mongodb/connection/SslSettings.Builder.html>`__ block. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt @@ -273,11 +273,11 @@ mechanism: To specify the ``X.509`` authentication mechanism by using the ``MongoCredential`` class, use the - `createMongoX509Credential() <{+api+}/com/mongodb/MongoCredential.html#createMongoX509Credential(java.lang.String)>`__ + `createMongoX509Credential() <{+core-api+}/com/mongodb/MongoCredential.html#createMongoX509Credential(java.lang.String)>`__ method. Also, enable TLS by calling the - `applyToSslSettings() <{+api+}/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ + `applyToSslSettings() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ method and setting the ``enabled`` property to ``true`` in the - `SslSettings.Builder <{+api+}/com/mongodb/connection/SslSettings.Builder.html>`__ + `SslSettings.Builder <{+core-api+}/com/mongodb/connection/SslSettings.Builder.html>`__ block. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt From 769c97bdece1d68d7bdffff0f48d4c7bac50c449 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 23 Oct 2024 16:21:37 -0400 Subject: [PATCH 22/29] quick --- source/security/authentication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index e728436..38d3bdd 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -98,7 +98,7 @@ mechanism: :dedent: For more information about using SCRAM with MongoDB, see the -:manual:`SCRAM ` section of the Server manual. +:manual:`SCRAM ` section of the {+mdb-server+} manual. .. _kotlin-sync-auth-scramsha256: From ecd78d87e19015231bc853c213058551ae3caa33 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 1 Nov 2024 17:46:38 -0400 Subject: [PATCH 23/29] last inernal review comments --- source/security/authentication.txt | 20 ++++++++++---------- source/security/enterprise-auth.txt | 14 +++++++------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 38d3bdd..7239dc4 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -241,9 +241,9 @@ the subject name of the client certificate. The following code snippets show how to specify the authentication mechanism by using the following placeholders: -* ``hostname``: network address of your MongoDB deployment, accessible by your client. -* ``port``: port number of your MongoDB server. -* ``authenticationDb``: MongoDB database that contains your user's +* ``hostname``: The network address of your MongoDB deployment, accessible by your client. +* ``port``: The port number of your MongoDB server. +* ``authenticationDb``: The MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. @@ -315,12 +315,12 @@ In the following sections, you can learn different ways to specify the These sections contain code examples that use the following placeholders: -* ``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 +* ``awsKeyId``: The value of your AWS access key ID +* ``awsSecretKey``: The value of your AWS secret access key +* ``atlasUri``: The network address of your MongoDB Atlas deployment +* ``hostname``: The hostname of your MongoDB Atlas deployment +* ``port``: The port of your MongoDB Atlas deployment +* ``awsSessionToken``: The value of your AWS session token .. _kotlin-mongodb-aws-sdk: @@ -329,7 +329,7 @@ AWS SDK .. note:: End of Support for AWS SDK for Java v1 - The AWS SDK for Java v1 will reach end of support on Decemeber 31, 2025. + The AWS SDK for Java v1 will reach end of support on December 31, 2025. AWS recommends migrating to AWS SDK for Java v2. For more information, see the `end of support announcement `__ diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index 3cb7f7c..512e429 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -54,9 +54,9 @@ principal name. The following code snippets show how to specify the authentication mechanism, using the following placeholders: -* ``Kerberos principal``: your URL-encoded principal name, e.g. "username%40REALM.ME" -* ``hostname``: network address of your MongoDB deployment, accessible by your client -* ``port``: port number of your MongoDB deployment +* ``Kerberos principal``: Your URL-encoded principal name, e.g. "username%40REALM.ME" +* ``hostname``: The network address of your MongoDB deployment, accessible by your client +* ``port``: Your 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 @@ -253,10 +253,10 @@ parameter to ``PLAIN`` and including your LDAP username and password in the The following code snippets show how to specify the authentication mechanism, using the following placeholders: -* ``LDAP username``: your LDAP username -* ``password``: your LDAP user's password -* ``hostname``: network address of your MongoDB deployment, accessible by your client -* ``port``: port number of your MongoDB deployment +* ``LDAP username``: Your LDAP username +* ``password``: Your LDAP user's password +* ``hostname``: The network address of your MongoDB deployment, accessible by your client +* ``port``: The 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 From 895650516daea995714b0006c68d919df632710e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 26 Nov 2024 14:58:45 -0500 Subject: [PATCH 24/29] back to standard form --- source/includes/security/authentication.kt | 68 +++++++++++----------- source/security/authentication.txt | 18 +----- 2 files changed, 36 insertions(+), 50 deletions(-) diff --git a/source/includes/security/authentication.kt b/source/includes/security/authentication.kt index a9f3f91..3962d4e 100644 --- a/source/includes/security/authentication.kt +++ b/source/includes/security/authentication.kt @@ -6,7 +6,7 @@ import org.bson.Document // SCRAM Authentication // start-default-cred-string val mongoClient = - MongoClient.create("mongodb+srv://:@:/?authSource=") + MongoClient.create("mongodb://:@:/?authSource=") // end-default-cred-string // start-default-mongo-cred @@ -14,63 +14,61 @@ val credential = MongoCredential.createCredential( "", "", "".toCharArray() ) +val credential = MongoCredential.createCredential( + "", "", "".toCharArray() +) val settings = MongoClientSettings.builder() - .applyToClusterSettings { builder: ClusterSettings.Builder -> - builder.srvHost("") - } - .credential(credential) - .applyToSslSettings { builder -> - builder.enabled(true) - } - .build() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("", "")) + ) + } + .credential(credential) + .build() val mongoClient = MongoClient.create(settings) // end-default-mongo-cred // start-scramsha256-cred-string val mongoClient = - MongoClient.create("mongodb+srv://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256") + MongoClient.create("mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256") // end-scramsha256-cred-string // start-scramsha256-mongo-cred val credential = MongoCredential.createScramSha256Credential( - "", "", "".toCharArray() - ) - + "", "", "".toCharArray() +) val settings = MongoClientSettings.builder() - .applyToClusterSettings { builder: ClusterSettings.Builder -> - builder.srvHost("") - } - .applyToSslSettings { builder -> - builder.enabled(true) - } - .credential(credential) - .build() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("", "")) + ) + } + .credential(credential) + .build() val mongoClient = MongoClient.create(settings) // end-scramsha256-mongo-cred // start-scramsha1-cred-string val mongoClient = - MongoClient.create("mongodb+srv://:@:/?authSource=admin&authMechanism=SCRAM-SHA-1") + MongoClient.create("mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-1") // end-scramsha1-cred-string // start-scramsha1-mongo-cred val credential = MongoCredential.createScramSha1Credential( - "", "", "".toCharArray() - ) - + "", "", "".toCharArray() +) val settings = MongoClientSettings.builder() - .applyToClusterSettings { builder: ClusterSettings.Builder -> - builder.srvHost("") - } - .applyToSslSettings { builder -> - builder.enabled(true) - } - .credential(credential) - .build() - - val mongoClient = MongoClient.create(settings) + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("", "")) + ) + } + .credential(credential) + .build() + +val mongoClient = MongoClient.create(settings) // end-scramsha1-mongo-cred // AWS Authentication diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 7239dc4..cfff198 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -85,11 +85,7 @@ mechanism: To specify the default authentication mechanism by using the ``MongoCredential`` class, use the ``createCredential()`` method. - Also, enable TLS by calling the - `applyToSslSettings() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ - method and setting the ``enabled`` property to ``true`` in the - `SslSettings.Builder <{+core-api+}/com/mongodb/connection/SslSettings.Builder.html>`__ - block. Your code to instantiate a ``MongoClient`` should resemble the following: + Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt :language: kotlin @@ -152,11 +148,7 @@ mechanism: To specify the default authentication mechanism by using the ``MongoCredential`` class, use the `createScramSha256Credential() <{+core-api+}/com/mongodb/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__ - method. Also, enable TLS by calling the - `applyToSslSettings() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ - method and setting the ``enabled`` property to ``true`` in the - `SslSettings.Builder <{+core-api+}/com/mongodb/connection/SslSettings.Builder.html>`__ - block. Your code to instantiate a ``MongoClient`` should resemble the following: + method. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt :language: kotlin @@ -215,11 +207,7 @@ mechanism: To specify the default authentication mechanism by using the ``MongoCredential`` class, use the `createScramSha1Credential() <{+core-api+}/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ - method. Also, enable TLS by calling the - `applyToSslSettings() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ - method and setting the ``enabled`` property to ``true`` in the - `SslSettings.Builder <{+core-api+}/com/mongodb/connection/SslSettings.Builder.html>`__ - block. Your code to instantiate a ``MongoClient`` should resemble the following: + method. Your code to instantiate a ``MongoClient`` should resemble the following: .. literalinclude:: /includes/security/authentication.kt :language: kotlin From ce0480614c834952d1d2929864de8e38a03e781e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 26 Nov 2024 15:20:47 -0500 Subject: [PATCH 25/29] edit --- source/includes/security/authentication.kt | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/source/includes/security/authentication.kt b/source/includes/security/authentication.kt index 3962d4e..9f9a4b2 100644 --- a/source/includes/security/authentication.kt +++ b/source/includes/security/authentication.kt @@ -10,10 +10,6 @@ val mongoClient = // end-default-cred-string // start-default-mongo-cred -val credential = MongoCredential.createCredential( - "", "", "".toCharArray() -) - val credential = MongoCredential.createCredential( "", "", "".toCharArray() ) @@ -67,7 +63,7 @@ val settings = MongoClientSettings.builder() } .credential(credential) .build() - + val mongoClient = MongoClient.create(settings) // end-scramsha1-mongo-cred From 8d2fb54e51ea39ab9458b21c38466ccef6ca13d4 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 27 Nov 2024 17:34:22 -0500 Subject: [PATCH 26/29] port as integer --- source/includes/security/authentication.kt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/security/authentication.kt b/source/includes/security/authentication.kt index 9f9a4b2..b1acfbf 100644 --- a/source/includes/security/authentication.kt +++ b/source/includes/security/authentication.kt @@ -16,7 +16,7 @@ val credential = MongoCredential.createCredential( val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( - listOf(ServerAddress("", "")) + listOf(ServerAddress("", )) ) } .credential(credential) @@ -37,7 +37,7 @@ val credential = MongoCredential.createScramSha256Credential( val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( - listOf(ServerAddress("", "")) + listOf(ServerAddress("", )) ) } .credential(credential) @@ -58,7 +58,7 @@ val credential = MongoCredential.createScramSha1Credential( val settings = MongoClientSettings.builder() .applyToClusterSettings { builder: ClusterSettings.Builder -> builder.hosts( - listOf(ServerAddress("", "")) + listOf(ServerAddress("", )) ) } .credential(credential) From 21a888f1225d2ba3c37910d39f73a15595b12406 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 27 Nov 2024 18:04:28 -0500 Subject: [PATCH 27/29] add security section --- source/index.txt | 1 + source/security.txt | 1 + source/{ => security}/encrypt-fields.txt | 0 3 files changed, 2 insertions(+) rename source/{ => security}/encrypt-fields.txt (100%) diff --git a/source/index.txt b/source/index.txt index f92711c..908c1c0 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,6 +22,7 @@ Aggregation Operations Specialized Data Formats Builders + Security In-Use Encryption Compatibility Validate Driver Signatures diff --git a/source/security.txt b/source/security.txt index 13af024..00db297 100644 --- a/source/security.txt +++ b/source/security.txt @@ -9,5 +9,6 @@ Secure Your Data /security/authentication /security/enterprise-auth + /encrypt-fields .. placeholder \ No newline at end of file diff --git a/source/encrypt-fields.txt b/source/security/encrypt-fields.txt similarity index 100% rename from source/encrypt-fields.txt rename to source/security/encrypt-fields.txt From 4e757107e6ca040b0f5ce08b57d18f851a2dc0ad Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 27 Nov 2024 18:05:26 -0500 Subject: [PATCH 28/29] fix sncrypt fileds toc --- source/security.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security.txt b/source/security.txt index 00db297..e3b9d26 100644 --- a/source/security.txt +++ b/source/security.txt @@ -9,6 +9,6 @@ Secure Your Data /security/authentication /security/enterprise-auth - /encrypt-fields + /security/encrypt-fields .. placeholder \ No newline at end of file From c4db472dabb254466aa999b4e3c6e73a300dd2a6 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 27 Nov 2024 18:11:55 -0500 Subject: [PATCH 29/29] add toc labels --- source/security.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/security.txt b/source/security.txt index e3b9d26..08969d5 100644 --- a/source/security.txt +++ b/source/security.txt @@ -7,8 +7,8 @@ Secure Your Data :titlesonly: :maxdepth: 1 - /security/authentication - /security/enterprise-auth - /security/encrypt-fields + Authentication + Enterprise Authentication + In-Use Encryption .. placeholder \ No newline at end of file