-
Notifications
You must be signed in to change notification settings - Fork 34
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
kyuan-mongodb
merged 10 commits into
mongodb:master
from
kyuan-mongodb:DOCSP-13829-AuthMechanisms
Aug 16, 2021
Merged
Changes from 3 commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
31b993f
added authentication mechanism page
kyuan-mongodb cecf88d
proofread
kyuan-mongodb b8d5245
proofread 2
kyuan-mongodb 41b7c6d
added section to explain how autenticating works
kyuan-mongodb 7baea67
TS suggestions
kyuan-mongodb 9cb0cfc
proofread
kyuan-mongodb efa048d
clarified intros
kyuan-mongodb d8f4145
BR suggestions
kyuan-mongodb 9f1b2bd
fixed MongoDB-CR versioning
kyuan-mongodb 252e8eb
removed mention about using MONGODB-CR
kyuan-mongodb File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
@@ -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 | ||
terakilobyte marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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``. | ||
benjirewis marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
.. _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, | ||
kyuan-mongodb marked this conversation as resolved.
Show resolved
Hide resolved
|
||
} | ||
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, | ||
kyuan-mongodb marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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>`. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.