diff --git a/snooty.toml b/snooty.toml index 752e3cee..6dd53417 100644 --- a/snooty.toml +++ b/snooty.toml @@ -17,7 +17,8 @@ toc_landing_pages = [ "/connect/connection-options", "/logging-and-monitoring", "/databases-and-collections", - "/api" + "/api", + "/security/authentication" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 1f8ae90f..78d0b8e9 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -17,493 +17,49 @@ Authentication Mechanisms .. meta:: :keywords: validate credentials, protocols, code example -Overview --------- - -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. - -.. note:: Enterprise Authentication Mechanisms - - 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 `. - -.. _kotlin-sync-auth-default: -.. _kotlin-sync-auth-scramsha256: - -SCRAM-SHA-256 -------------- - -``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. This is the default authentication -mechanism. - -The following code snippets show how to specify this default authentication mechanism by -using the following placeholders: - -* ``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``. - -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 default authentication mechanism by 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 by using the - ``MongoCredential`` class, use the ``createCredential()`` method. - 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: - -You can also explicitly specify the ``SCRAM-SHA-256`` authentication mechanism, -as shown in the following code snippets. - -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 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: - - .. 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 by using the - ``MongoCredential`` class, use the - `createScramSha256Credential() <{+core-api+}/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__ - method. 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 ------------ - -``SCRAM-SHA-1``, as defined by `RFC 5802 `__, -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 -by using the following placeholders: - -* ``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``. - -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 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: - - .. 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 by using the - ``MongoCredential`` class, use the - `createScramSha1Credential() <{+core-api+}/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ - method. 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-x509: - -MONGODB-X509 ------------- - -The ``MONGODB-X509`` authentication mechanism uses -:wikipedia:`TLS ` with X.509 certificates to -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. - -The following code snippets show how to specify the authentication mechanism -by using the following placeholders: - -* ``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``. - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the ``X.509`` authentication mechanism by using a connection - string, assign the ``authMechanism`` parameter 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 by using the - ``MongoCredential`` class, use the - `createMongoX509Credential() <{+core-api+}/MongoCredential.html#createMongoX509Credential(java.lang.String)>`__ - method. Also, enable TLS by calling the - `applyToSslSettings() <{+core-api+}/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ - method and setting the ``enabled`` property to ``true`` in the - `SslSettings.Builder <{+core-api+}/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 the -:ref:`TLS/SSL guide `. - -.. _kotlin-sync-auth-aws: - -MONGODB-AWS ------------ - -.. 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 Authentication with AWS IAM ` -guide. - -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. - -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: - -* ``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 +.. toctree:: + :caption: Authentication -.. _kotlin-mongodb-aws-sdk: + SCRAM + X.509 + AWS IAM -AWS SDK -~~~~~~~ - -.. note:: End of Support for AWS SDK for Java v1 - - 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 - `__ - 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 `__ - -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. -#. Supply your credentials by using one of the methods in the credential - provider chain. - -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 - :language: kotlin - :dedent: - :start-after: start-aws-sdk-mcred - :end-before: end-aws-sdk-mcred - :emphasize-lines: 1, 9 - -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 - :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 by using the - ``software.amazon.awssdk:auth:2.30.31`` dependency. - - For the AWS SDK for Java v1, the Java driver currently tests by using the - ``com.amazonaws:aws-java-sdk-core:1.12.782`` 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 ``MONGODB-AWS`` authentication mechanism by using a -``MongoCredential`` object or in the connection string. - -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 - :language: kotlin - :dedent: - :start-after: start-aws-env-mcred - :end-before: end-aws-env-mcred - :emphasize-lines: 1, 9 - -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 - :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 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. - -.. _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, call the -`createAwsCredential() <{+core-api+}/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, follow the instructions in -:ref:`` or :ref:``. - -To use a ``MongoCredential`` object for ``MONGODB-AWS`` authentication, you -must perform the following steps: - -1. Specify the authentication mechanism. -#. Supply the credentials. - -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 - :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() <{+core-api+}/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`` object by calling the `applyConnectionString() <{+core-api+}/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 - -Additional Information ----------------------- - -To learn more about authenticating to MongoDB, see -:manual:`Authentication ` in the {+mdb-server+} manual. +Overview +-------- -To learn more about managing users of your MongoDB deployment, see -:manual:`Users ` in the {+mdb-server+} manual. +This guide describes the authentication mechanisms that the {+driver-short+} supports. +Authentication mechanisms are processes by which the driver and server confirm the +identity of a client to ensure security before connecting. + +.. tip:: Connect to MongoDB + + To learn how to connect to MongoDB by using the {+driver-short+}, see the + :ref:`kotlin-sync-mongoclient` guide. + +MongoDB Edition Compatibility +----------------------------- + +The following table lists the authentication mechanisms supported by MongoDB and +the {+mdb-server+} editions that each mechanism is compatible with. Click the name of +a mechanism to learn more about how to use it with your application. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - Authentication Mechanism + - Atlas + - Enterprise Advanced + - Community + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - No + - No diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt new file mode 100644 index 00000000..88f6382e --- /dev/null +++ b/source/security/authentication/aws-iam.txt @@ -0,0 +1,323 @@ +.. _kotlin-sync-auth-aws: + +====================== +AWS IAM Authentication +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: atlas, amazon web services, code example + +Overview +-------- + +The **MONGODB-AWS** authentication mechanism uses Amazon Web Services +Identity and Access Management (AWS IAM) credentials to authenticate a user to MongoDB. +You can use this mechanism only when authenticating to MongoDB Atlas. + +.. tip:: Configure Atlas for AWS IAM Authentication + + To learn more about configuring MongoDB Atlas for AWS IAM authentication, see + :atlas:`Set Up Authentication with AWS IAM ` in + the Atlas documentation. + +Specify MONGODB-AWS Authentication +---------------------------------- + +To instruct the {+driver-short+} to use the ``MONGODB-AWS`` authentication mechanism, +you can either specify ``MONGODB-AWS`` as a parameter in the connection string or call +the ``MongoCredential.createAwsCredential()`` factory method. + +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: + +- ``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: + +AWS SDK +~~~~~~~ + +.. note:: End of Support for AWS SDK for Java v1 + + 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 + `__ + 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 `__ + +To use the AWS SDK for ``MONGODB-AWS`` authentication, perform +the following steps: + +1. :ref:`Specify the authentication mechanism `. +#. :ref:`Add the SDK as a dependency to your project `. +#. :ref:`Supply your credentials by using one of the methods in the credential provider chain `. + +.. _kotlin-mongodb-aws-sdk-specify: + +Specify the Authentication Mechanism +```````````````````````````````````` + +You can specify the ``MONGODB-AWS`` authentication mechanism by using a connection +string or a ``MongoCredential`` object. Select the :guilabel:`Connection String` +or the :guilabel:`MongoCredential` tab below for corresponding instructions and sample code: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the ``MONGODB-AWS`` authentication mechanism in the connection string, + set the ``authMechanism`` parameter to ``MONGODB-AWS``, 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 + + .. tab:: + :tabid: MongoCredential + + 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 + :language: kotlin + :dedent: + :start-after: start-aws-sdk-mcred + :end-before: end-aws-sdk-mcred + :emphasize-lines: 1, 9 + +.. _kotlin-mongodb-aws-sdk-dependency: + +Add the AWS SDK Dependency +`````````````````````````` + +To add the AWS SDK as a dependency to your project, see the following +AWS documentation for the version you need: + +- For the **AWS SDK for Java v2**, see the `Setting Up `__ + guide. +- For the **AWS SDK for Java v1**, see the `Getting Started `__ + guide. + +.. note:: + + For the AWS SDK for Java v2, the Java driver tests by using the + ``software.amazon.awssdk:auth:2.30.31`` dependency. + + For the AWS SDK for Java v1, the Java driver tests by using the + ``com.amazonaws:aws-java-sdk-core:1.12.782`` dependency. + +.. _kotlin-mongodb-aws-sdk-credentials: + +Supply Your Credentials +``````````````````````` + +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, perform +the following steps: + +1. :ref:`Specify the authentication mechanism `. +#. :ref:`Add the appropriate environment variables `. + +.. _kotlin-mongodb-aws-env-specify: + +Specify the Authentication Mechanism +```````````````````````````````````` + +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`` 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 + :language: kotlin + :dedent: + :start-after: start-aws-env-mcred + :end-before: end-aws-env-mcred + :emphasize-lines: 1, 9 + +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 + :dedent: + :start-after: start-aws-env-cred-string + :end-before: end-aws-env-cred-string + +.. _kotlin-mongodb-aws-env-set-vars: + +Set Environment Variables +````````````````````````` + +This section shows 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 that sets the ``AWS_SESSION_TOKEN`` variable 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 by using **EC2 container credentials**, do not set +the AWS environment variables. 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, call the +`createAwsCredential() <{+core-api+}/MongoCredential.html#createAwsCredential(java.lang.String,char%5B%5D)>`__ +factory method. + +.. tip:: + + You can supply only programmatic access keys to the + ``MongoCredential.createAwsCredential()`` method. If you must supply ECS + or EC2 container credentials, follow the instructions in + :ref:``. + +To use a ``MongoCredential`` object for ``MONGODB-AWS`` authentication, perform +the following steps: + +1. Specify the authentication mechanism. +#. Supply the credentials. + +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 + :language: kotlin + :dedent: + :start-after: start-aws-mcred + :end-before: end-aws-mcred + :emphasize-lines: 1, 9 + +If you must specify an AWS session token, pass it to the +`withMechanismProperty() <{+core-api+}/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`` object by calling the `applyConnectionString() <{+core-api+}/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 + +Additional Information +---------------------- + +To learn more about authenticating to MongoDB, see +:manual:`Authentication ` in the {+mdb-server+} manual. + +To learn more about creating a ``MongoClient`` object by using the +{+driver-short+}, see the :ref:`kotlin-sync-mongoclient` guide. \ No newline at end of file diff --git a/source/security/authentication/scram.txt b/source/security/authentication/scram.txt new file mode 100644 index 00000000..c6072caa --- /dev/null +++ b/source/security/authentication/scram.txt @@ -0,0 +1,189 @@ +.. _kotlin-sync-auth-scram: + +==================== +SCRAM Authentication +==================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: salt, default, code example + +Overview +-------- + +**Salted Challenge Response Authentication Mechanism (SCRAM)** is a family of +authentication mechanisms that use a challenge-response mechanism to authenticate +the user. ``SCRAM-SHA-256``, which uses the ``SHA-256`` algorithm to hash your password, is the +default authentication mechanism in {+mdb-server+} version 4.0 +and later. ``SCRAM-SHA-1``, which uses the ``SHA-1`` algorithm, is the default +authentication mechanism in {+mdb-server+} versions earlier than 4.0. + +You can use ``SCRAM`` to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: SCRAM Mechanisms + + To learn more about the ``SCRAM`` family of authentication mechanisms, see + `RFC 5802 `__ and + :wikipedia:`Salted Challenge Response Authentication Mechanism ` + on Wikipedia. + + For more information about the MongoDB implementation of ``SCRAM``, see + :manual:`SCRAM ` in the {+mdb-server+} manual. + +.. _kotlin-sync-auth-default: +.. _kotlin-sync-auth-scramsha256: + +Specify SCRAM-SHA-256 Authentication +------------------------------------ + +``SCRAM-SHA-256``, as defined by `RFC 7677 `__, +encrypts your username and password with the ``SHA-256`` algorithm to authenticate +your user. This is the default authentication mechanism. + +The examples in this section show how to specify this default authentication +mechanism and use the following placeholder values: + +- ``db_username``: Your MongoDB database username. +- ``db_password``: Your MongoDB database user's password. +- ``hostname``: The network address of your MongoDB deployment, open to 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``. + +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 default authentication mechanism by using a connection + string, omit the mechanism as shown in the following example: + + .. 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 by using the + ``MongoCredential`` class, use the ``createCredential()`` method + as shown in the following example: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :start-after: start-default-mongo-cred + :end-before: end-default-mongo-cred + :dedent: + +Alternatively, you can explicitly specify the ``SCRAM-SHA-256`` authentication mechanism. +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 by using a + connection string, assign the ``authMechanism`` parameter the value + ``SCRAM-SHA-256`` in your connection string as shown in the following example: + + .. 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 by using the + ``MongoCredential`` class, use the + `createScramSha256Credential() <{+core-api+}/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__ + method as shown in the following example: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-scramsha256-mongo-cred + :end-before: end-scramsha256-mongo-cred + +.. _kotlin-sync-auth-scramsha1: + +Specify SCRAM-SHA-1 Authentication +---------------------------------- + +``SCRAM-SHA-1``, as defined by `RFC 5802 `__, +encrypts your username and password with the ``SHA-1`` algorithm to authenticate +your user. + +The examples in this section show how to specify this authentication +mechanism and use the following placeholder values: + +- ``db_username``: Your MongoDB database username. +- ``db_password``: Your MongoDB database user's password. +- ``hostname``: The network address of your MongoDB deployment, open to 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``. + +Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab below for instructions and sample code for specifying the ``SCRAM-SHA-1`` authentication +mechanism: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the ``SCRAM-SHA-1`` authentication mechanism by using a + connection string, assign the ``authMechanism`` parameter the value + ``SCRAM-SHA-1`` in your connection string as shown in the following example: + + .. 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 by using the + ``MongoCredential`` class, use the + `createScramSha1Credential() <{+core-api+}/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ + method as shown in the following example: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-scramsha1-mongo-cred + :end-before: end-scramsha1-mongo-cred + +Additional Information +---------------------- + +To learn more about authenticating to MongoDB, see +:manual:`Authentication ` in the {+mdb-server+} manual. + +To learn more about creating a ``MongoClient`` object by using the +{+driver-short+}, see the :ref:`kotlin-sync-mongoclient` guide. \ No newline at end of file diff --git a/source/security/authentication/x509.txt b/source/security/authentication/x509.txt new file mode 100644 index 00000000..3e4079ec --- /dev/null +++ b/source/security/authentication/x509.txt @@ -0,0 +1,90 @@ +.. _kotlin-sync-auth-x509: + +==================== +X.509 Authentication +==================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: certificate, code example + +Overview +-------- + +In the **X.509** authentication mechanism, the server and client use the +:wikipedia:`TLS ` protocol to exchange X.509 public-key +certificates. You can use this mechanism to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: X.509 Mechanism + + To learn how to use TLS/SSL with the {+driver-short+}, + see the :ref:`kotlin-sync-tls` guide. + + For more information about X.509 certificates, see + :manual:`Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments + ` in the {+mdb-server+} manual. + +Specify X.509 Authentication +---------------------------- + +The examples in this section show how to specify the ``X.509`` authentication mechanism +and use the following placeholder values: + +* ``hostname``: The network address of your MongoDB deployment, open to 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``. + +Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` +tab below for instructions and sample code for specifying this authentication +mechanism: + +.. tabs:: + + .. tab:: + :tabid: Connection String + + To specify the ``X.509`` authentication mechanism by using a connection + string, set the ``authMechanism`` parameter to ``MONGODB-X509`` + and the ``tls`` parameter to ``true`` as shown in the following example: + + .. 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 by using the + ``MongoCredential`` class, use the + `createMongoX509Credential() <{+core-api+}/MongoCredential.html#createMongoX509Credential(java.lang.String)>`__ + and `applyToSslSettings() <{+core-api+}/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ + builder methods as shown in the following example: + + .. literalinclude:: /includes/security/authentication.kt + :language: kotlin + :dedent: + :start-after: start-x509-mcred + :end-before: end-x509-mcred + +Additional Information +---------------------- + +To learn more about authenticating to MongoDB, see +:manual:`Authentication ` in the {+mdb-server+} manual. + +To learn more about creating a ``MongoClient`` object by using the +{+driver-short+}, see the :ref:`kotlin-sync-mongoclient` guide. \ No newline at end of file