authentication.txt

.. _cpp-auth:

=========================
Authentication Mechanisms
=========================

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

.. facet::
   :name: genre
   :values: reference
 
.. meta::
   :keywords: authorize, secure, connect

Overview
--------

This guide describes the mechanisms you can use in the {+driver-short+} to authenticate
users.

.. _cpp-scram-sha-256:

SCRAM-SHA-256
-------------

SCRAM-SHA-256, as defined by `RFC 7677 <https://www.rfc-editor.org/rfc/rfc7677>`__,
is the default authentication mechanism on MongoDB deployments
running MongoDB v4.0 or later.

To authenticate with this mechanism, set the following connection options:

- ``db_username``: The database username to authenticate.
- ``db_password``: The database password to authenticate.
- ``authSource``: The MongoDB database to authenticate against. By default,
  {+driver-short+} authenticates against the database in the connection
  URI, if you include one. If you don't, it authenticates against the ``admin`` database.
- ``authMechanism``: Set to ``"SCRAM-SHA-256"``.

You can set these options in the connection string when creating a
``mongocxx::client`` object, as shown in the following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-scram-sha-256
   :end-before: // end-scram-sha-256

.. _cpp-scram-sha-1:

SCRAM-SHA-1
-----------

SCRAM-SHA-1, as defined by `RFC 5802 <https://www.rfc-editor.org/rfc/rfc5802>`__,
is the default authentication mechanism on MongoDB deployments
running MongoDB v3.6.

To authenticate with this mechanism, set the following connection options:

- ``db_username``: The database username to authenticate. 
- ``db_password``: The databse password to authenticate.
- ``authSource``: The MongoDB database to authenticate against. By default,
  {+driver-short+} authenticates against the ``admin`` database.
- ``authMechanism``: Set to ``"SCRAM-SHA-1"``.

You can set these options in the connection string when creating a
``mongocxx::client`` object, as shown in the following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-scram-sha-1
   :end-before: // end-scram-sha-1

.. _cpp-x509:

MONGODB X.509
-------------

If you enable TLS, during the TLS handshake, the {+driver-short+} can present an X.509
client certificate to MongoDB to prove its identity. The ``MONGODB-X509`` authentication
mechanism uses this certificate to authenticate the client.

To authenticate with this mechanism, set the following connection options:

- ``tls``: Set to ``True``.
- ``tlsCertificateKeyFile``: The file path of the ``.pem`` file that contains your
  client certificate and private key.
- ``authMechanism``: Set to ``"MONGODB-X509"``.

You can set these options in the connection string when creating a
``mongocxx::client`` object, as shown in the following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-x509
   :end-before: // end-x509

To learn more about enabling TLS, see :ref:`cpp-tls`.

.. _cpp-mongo-aws:

MONGODB-AWS
-----------

.. important::

   The MONGODB-AWS authentication mechanism requires MongoDB v4.4 or later.

The ``MONGODB-AWS`` authentication mechanism uses AWS IAM (Amazon Web Services Identity and
Access Management) or AWS Lambda credentials to authenticate your application.
To authenticate using this mechanism, first create a user with an associated Amazon Resource Name (ARN) on
the ``$external`` database, then specify the ``MONGODB-AWS`` authMechanism in the
URI.

When you use the ``MONGODB-AWS`` mechanism, the {+driver-short+} attempts to
retrieve your AWS credentials from the following sources, in the order listed:

1. Named parameters passed to the Connection URI
#. Environment variables
#. AWS EKS AssumeRoleWithWebIdentity request
#. ECS container metadata
#. EC2 instance metadata

The following sections describe how to use the {+driver-short+} to retrieve credentials from
these sources and use them to authenticate your application.

Connection URI
~~~~~~~~~~~~~~

First, the {+driver-short+} checks whether you passed AWS credentials to the
``MongoClient`` constructor as part of the connection
URI. To pass your credentials in the connection URI, set the following connection
options:

- ``username``: The AWS IAM access key ID to authenticate.
- ``password``: The AWS IAM secret access key.
- ``authMechanism``: Set to ``"MONGODB-AWS"``.

You can set these options in the connection string when creating a
``mongocxx::client`` object, as shown in the following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-aws-connection-uri
   :end-before: // end-aws-connection-uri

You can also include an AWS session token by passing it into the
``authMechanismProperties`` parameter:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-aws-connection-uri-session
   :end-before: // end-aws-connection-uri-session

.. _cpp-mongo-aws-environment:

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

If you don't provide a username and password when you construct your ``MongoClient``
object, the {+driver-short+} tries to retrieve AWS credentials from the following
environment variables:

- ``AWS_ACCESS_KEY_ID``
- ``AWS_SECRET_ACCESS_KEY``
- ``AWS_SESSION_TOKEN`` (optional)

To use these environment variables to authenticate your application, first set them to the
AWS IAM values needed for authentication, as shown in the following code
example:

.. code-block:: sh

   export AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
   export AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
   export AWS_SESSION_TOKEN=<AWS session token>

After you set these environment variables, set the ``authMechanism``
parameter in your connection URI to ``"MONGODB-AWS"``, as shown in the
following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-aws-environment
   :end-before: // end-aws-environment

.. _cpp-mongo-aws-assume-role:

AssumeRoleWithWebIdentity Request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC)
identity provider, the {+driver-short+} can make an ``AssumeRoleWithWebIdentity`` request
to exchange the OIDC token for temporary AWS credentials for your application. 

To authenticate with temporary AWS IAM credentials returned by an
``AssumeRoleWithWebIdentity`` request, ensure that the AWS config file exists in your
environment and is configured with the ``AWS_WEB_IDENTITY_TOKEN_FILE``
and ``AWS_ROLE_ARN`` environment variables. To learn how to create and configure
an AWS config file, see `Configuration <https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html>`__
in the AWS documentation.

After you configure your environment for an ``AssumeRoleWithWebIdentity`` request,
set the ``authMechanism`` parameter in your connection URI to ``"MONGODB-AWS"``,
as shown in the following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-aws-environment
   :end-before: // end-aws-environment

For more information about using an ``AssumeRoleWithWebIdentity`` request to
authenticate your application, see the following AWS documentation:

- `AssumeRoleWithWebIdentity <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`__
- `Authenticating users for your cluster from an OpenID Connect identity provider <https://docs.aws.amazon.com/eks/latest/userguide/authenticate-oidc-identity-provider.html>`__

.. _cpp-mongo-aws-ecs:

ECS Metadata
~~~~~~~~~~~~

If your application runs in an Elastic Container Service (ECS) container,
the {+driver-short+} can automatically retrieve temporary AWS credentials from an
ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called
``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``, as shown in the following example:

.. code-block:: sh

   export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

After you set the environment variable, set the ``authMechanism``
parameter in your connection URI to ``"MONGODB-AWS"``, as shown in the
following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-aws-environment
   :end-before: // end-aws-environment

.. _cpp-mongo-aws-ec2:

EC2 Instance Metadata
~~~~~~~~~~~~~~~~~~~~~

The {+driver-short+} can automatically retrieve temporary AWS credentials from an
Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from
within an EC2 instance, set the ``authMechanism`` parameter in your connection
URI to ``"MONGODB-AWS"``, as shown in the following example:

.. literalinclude:: /includes/authentication.cpp
   :language: cpp
   :copyable: true
   :start-after: // start-aws-environment
   :end-before: // end-aws-environment

.. note::

   If you set any of the environment variables from the preceding AWS authentication
   methods, the {+driver-short+} attempts to retrieve credentials by using those
   methods before attempting to retrieve them from an EC2 instance. To attempt
   to retrieve credentials only from an EC2 instance, ensure that the
   environment variables are not set.

API Documentation
-----------------

To learn more about creating a ``mongocxx::client`` object in {+driver-short+},
see the following API documentation:

- `mongocxx::client <{+api+}/classmongocxx_1_1v__noabi_1_1client.html>`__