Skip to content

DOCSP-13829 authentication mechanism #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Aug 16, 2021
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion source/fundamentals.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ Fundamentals
:titlesonly:
:maxdepth: 1

/fundamentals/auth


..
/fundamentals/connection
/fundamentals/auth
/fundamentals/enterprise-auth
/fundamentals/databases-collections
/fundamentals/data-formats
Expand Down
256 changes: 248 additions & 8 deletions source/fundamentals/auth.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ Authentication Mechanisms
:depth: 2
:class: singlecol

Overview
--------

In this guide, we show you 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
Expand All @@ -18,14 +21,251 @@ confirm identity and establish trust to ensure security.
The mechanisms that you can use with the latest version of MongoDB Community
Edition are as follows:

* Default
* SCRAM-SHA-256
* SCRAM-SHA-1
* MONGODB-CR
* MONGODB-AWS
* X.509
* :ref:`Default <default-auth-mechanism>`
* :ref:`SCRAM-SHA-256 <scram-sha-256-auth-mechanism>`
* :ref:`SCRAM-SHA-1 <scram-sha-1-auth-mechanism>`
* :ref:`MONGODB-CR <mongodb-cr-auth-mechanism>`
* :ref:`MONGODB-AWS <mongodb-aws-auth-mechanism>`
* :ref:`X.509 <x509-auth-mechanism>`

To authenticate using ``Kerberos`` or ``LDAP``, see the
:doc:`Enterprise Authentication Mechanisms guide </fundamentals/enterprise-auth>`.
For more information on establishing a connection to your MongoDB cluster,
read our :doc:`Connection Guide </fundamentals/connection>`.

Mechanisms
----------

Authenticate a mechanism by specifying the authentication options
through an ``Credential`` type. The ``Credential`` gets passed to
a ``ClientOptions`` type, which contains the options related to the
``Client``. The ``ClientOptions`` gets passed to a ``Client`` type to
establish a connection.

In the following sections, each ``ClientOptions`` contains the following
authentication options:

* ``username`` - your MongoDB username
* ``password`` - your MongoDB 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``.

For more information on the types mentioned, see the following API
Documentation:

- `Credential <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo/options#Credential>`__
- `ClientOptions <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo/options#ClientOptions>`__
- `Client <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo#Client>`__

.. _default-auth-mechanism:

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``
#. ``MONGODB-CR``

Server versions 3.6 and earlier use ``MONGODB-CR`` as the default
mechanism. Newer versions of the server use one of the mechanisms for
which they advertise support.

To specify the default authentication mechanism, omit the
``AuthMechanism`` parameter:

.. code-block:: go

credential := options.Credential{
AuthSource: "<authenticationDb>",
Username: "<username>",
Password: "<password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
SetAuth(credential)

client, err := mongo.Connect(context.TODO(), clientOpts)

For more information on the challenge-response (CR) and salted
challenge-response authentication mechanisms (SCRAM) that MongoDB supports,
see the :manual:`SCRAM </core/security-scram/>` section of the server manual.

.. _scram-sha-256-auth-mechanism:

``SCRAM-SHA-256``
~~~~~~~~~~~~~~~~~

.. important::

``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.

To specify the ``SCRAM-SHA-256`` authentication mechanism, assign the
``AuthMechanism`` parameter the value ``SCRAM-SHA-256``:

.. code-block:: go
:emphasize-lines: 2

credential := options.Credential{
AuthMechanism: "SCRAM-SHA-256",
AuthSource: "<authenticationDb>",
Username: "<username>",
Password: "<password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
SetAuth(credential)

client, err := mongo.Connect(context.TODO(), clientOpts)

.. _scram-sha-1-auth-mechanism:

``SCRAM-SHA-1``
~~~~~~~~~~~~~~~

.. important::

``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.

To specify the ``SCRAM-SHA-1`` authentication mechanism, assign the
``AuthMechanism`` parameter the value ``SCRAM-SHA-1``:

.. code-block:: go
:emphasize-lines: 2

credential := options.Credential{
AuthMechanism: "SCRAM-SHA-1",
AuthSource: "<authenticationDb>",
Username: "<username>",
Password: "<password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
SetAuth(credential)

client, err := mongo.Connect(context.TODO(), clientOpts)

.. _mongodb-cr-auth-mechanism:

``MONGODB-CR``
~~~~~~~~~~~~~~

``MONGODB-CR`` is a challenge-response authentication mechanism that uses your
username and password to authenticate your user. This authentication
mechanism was deprecated starting in MongoDB 3.6 and is no longer
supported as of MongoDB 4.0.

You cannot specify this method explicitly; refer to the fallback provided
by the :ref:`default authentication mechanism <default-auth-mechanism>` to
connect using ``MONGODB-CR``.

.. _mongodb-aws-auth-mechanism:

``MONGODB-AWS``
~~~~~~~~~~~~~~~

.. important::

The MONGODB-AWS authentication mechanism is only available in MongoDB
versions 4.4 and later.

The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services
Identity and Access Management (AWS IAM) credentials to authenticate your
user.

To specify the ``MONGODB-AWS`` authentication mechanism, perform the
following:

- Assign the ``AuthMechanism`` parameter the value ``MONGODB-AWS``
- Assign the ``Username`` parameter the value of your ``accessKeyID``
- Assign the ``Password`` parameter the value of your ``secretAccessKey``

.. code-block:: go
:emphasize-lines: 3, 5-6

var accessKeyID, secretAccessKey string
awsCredential := options.Credential{
AuthMechanism: "MONGODB-AWS",
AuthSource: "<authenticationDb>",
Username: accessKeyID,
Password: secretAccessKey,
}
awsIAMClient, err := mongo.Connect(
context.TODO(),
options.Client().SetAuth(awsCredential))
if err != nil {
panic(err)
}
_ = awsIAMClient

If you need to specify an AWS session token, use the temporary
credentials returned from an assume role request.

To use temporary credentials, assign the ``AuthMechanismProperties``
parameter the value of your ``sessionToken``:

.. code-block:: go
:emphasize-lines: 7-9

var sessionToken string
assumeRoleCredential := options.Credential{
AuthMechanism: "MONGODB-AWS",
AuthSource: "<authenticationDb>",
Username: accessgKeyID,
Password: secretAccessKey,
AuthMechanismProperties: map[string]string{
"AWS_SESSION_TOKEN": sessionToken,
},
}
assumeRoleClient, err := mongo.Connect(context.TODO(),
options.Client().SetAuth(assumeRoleCredential))

.. _x509-auth-mechanism:

``X.509``
~~~~~~~~~

The ``X.509`` authentication mechanism uses
:wikipedia:`TLS <Transport_Layer_Security>` 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 paths of the following files:

- ``tlsCAFile`` which contains either a single or a bundle of certificate authorities to trust when making a TLS connection
- ``tlsCertificateKeyFile`` which references the path to the client certificate file or the client private key file

To specify the ``X.509`` authentication mechanism, perform the
following:

- Assign the ``tlsCAFile`` the path to its file in the connection string
- Assign the ``tlsCertificateKeyFile`` the path to its file in the connection string
- Assign the ``AuthMechanism`` parameter the value ``X.509``

.. code-block:: go
:emphasize-lines: 4-5, 7

caFilePath := "<cafile_path>"
certificateKeyFilePath := "<client_certificate_path>"

uri := "mongodb://<hostname>:<port>/?tlsCAFile=%s&tlsCertificateKeyFile=%s"
uri = fmt.Sprintf(uri, caFilePath, certificateKeyFilePath)
credential := options.Credential{
AuthMechanism: "MONGODB-X509",
}

clientOpts := options.Client().ApplyURI(uri).SetAuth(credential)

For additional information on configuring your application to use
certificates as well as TLS/SSL options, see our
:doc:`TLS/SSL guide </fundamentals/connection/tls>`.