DOCSP-45209: Authentication landing + Authentication mechanisms

snooty.toml

@@ -4,7 +4,8 @@ toc_landing_pages = [
     "/get-started",
     "/connect",
     "/write",
-    "/indexes"
+    "/indexes",
+    "/authentication",
 ]
 
 intersphinx = ["https://www.mongodb.com/docs/manual/objects.inv"]

source/authentication.txt

@@ -0,0 +1,76 @@
+.. _ruby-authentication-mechanisms:
+
+=========================
+Authentication Mechanisms
+=========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: .NET, community, security
+
+.. toctree::
+   :caption: Authentication
+
+   SCRAM </authentication/scram>
+   X.509 </authentication/x509>
+   AWS IAM </authentication/aws-iam>
+   LDAP (PLAIN) </authentication/ldap>
+   Kerberos (GSSAPI) </authentication/kerberos>
+
+Overview
+--------
+
+In this guide, you can learn how to authenticate to MongoDB by using the
+**authentication mechanisms** available in {+mdb-server+}.
+Authentication mechanisms are processes by which the driver and server confirm
+the identity of a client to ensure security before connecting.
+
+.. tip:: Connecting to MongoDB
+
+   To learn how to establish a connection to your MongoDB deployment, see the
+   :ref:`ruby-get-started-connect-to-mongodb` 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:`<ruby-authentication-scram>`
+     - Yes
+     - Yes
+     - Yes
+   * - :ref:`<ruby-authentication-x509>`
+     - Yes
+     - Yes
+     - Yes
+   * - :ref:`<ruby-authentication-aws>`
+     - Yes
+     - No
+     - No
+   * - :ref:`<ruby-authentication-ldap>`
+     - Yes
+     - Yes
+     - No
+   * - :ref:`Kerberos (GSSAPI) <ruby-authentication-kerberos>`
+     - No
+     - Yes
+     - No

source/authentication/aws-iam.txt

@@ -0,0 +1,203 @@
+.. _ruby-authentication-aws:
+
+==================================
+AWS Identity and Access Management
+==================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 3
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: .NET, amazon web services, code example
+
+Overview
+--------
+
+.. note::
+
+   AWS authentication is available only in the MongoDB Enterprise Edition for MongoDB 4.4
+   and later.
+
+The AWS authentication mechanism uses AWS `Identity and Access Management (IAM)
+<https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html>`_
+and AWS `Security Token Service (STS)
+<https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html>`_
+to prove the client's identity to a MongoDB server. AWS authentication
+works as follows:
+
+1. The client uses AWS IAM credentials to create a signature that is sent to
+   the MongoDB server.
+2. The server sends a request to AWS STS using the client's signature.
+3. A successful STS request returns the username (technically, the ARN of
+   the IAM user or role) corresponding to the credentials that the client used.
+   The IAM user ARN is used by the server to look up a defined user, and the
+   client is considered to have authenticated as this user.
+
+.. note::
+
+  Unlike other authentication mechanisms, the username that the application
+  provides when creating a client and the username of the server user are
+  different: the username on the client is the AWS access key ID, but the
+  username on the server is the ARN of the IAM user or role corresponding
+  to the access key ID.
+
+AWS credentials are comprised of:
+
+- The access key ID
+- The secret access key
+- The optional session token
+
+Authentication with `AWS IAM credentials
+<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html>`_,
+uses the access key ID and the secret access key. Authentication with
+`temporary AWS IAM credentials
+<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html>`_
+uses all three components.
+
+.. note::
+
+  The driver never sends the secret access key or the session token over
+  the network.
+
+Temporary credentials are used with:
+
+- STS `Assume Role <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-api.html>`_
+  requests.
+- `EC2 instance roles <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html>`_.
+- `ECS task roles <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`_.
+- `AWS Lambda environment <https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html>`_.
+- `IAM roles for service accounts <https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html>`_.
+
+The {+driver-short+} allows providing both regular and temporary credentials
+explicitly as {+language+} options or URI options. If you do not explicitly provide
+credentials, the driver will attempt to retrieve them from environment variables
+described below and from EC2 instance and ECS task metadata endpoints.
+
+Providing Credentials Explicitly
+--------------------------------
+
+You can provide regular (non-temporary) IAM credentials as Ruby options,
+as shown in the following example:
+
+.. literalinclude:: /includes/authentication/aws-iam.rb
+   :start-after: start-aws
+   :end-before: end-aws
+   :language: ruby
+   :copyable:
+   :dedent:
+
+They can also be provided by using a URI:
+
+.. literalinclude:: /includes/authentication/aws-iam.rb
+   :start-after: start-aws-connection-string
+   :end-before: end-aws-connection-string
+   :language: ruby
+   :copyable:
+   :dedent:
+
+.. note::
+
+  When credentials are provided by using a URI, they must be percent-escaped.
+
+To provide temporary credentials, specify the session token in the
+authentication mechanism properties a shown in the following example:
+
+.. literalinclude:: /includes/authentication/aws-iam.rb
+   :start-after: start-aws-temp
+   :end-before: end-aws-temp
+   :language: ruby
+   :copyable:
+   :dedent:
+
+You can also provide temporary credentials by using a URI:
+
+.. literalinclude:: /includes/authentication/aws-iam.rb
+   :start-after: start-aws-temp-connection-string
+   :end-before: end-aws-temp-connection-string
+   :language: ruby
+   :copyable:
+   :dedent:
+
+Automatically Retrieving Credentials
+------------------------------------
+
+The client can retrieve credentials from the environment or from EC2 or ECS
+metadata endpoints. To retrieve credentials automatically, specify the
+AWS authentication mechanism but do not specify a username nor a password:
+
+.. literalinclude:: /includes/authentication/aws-iam.rb
+   :start-after: start-aws-automatic-retrieval
+   :end-before: end-aws-automatic-retrieval
+   :language: ruby
+   :copyable:
+   :dedent:
+
+You can also use a connection string to retrieve credentials automatically:
+
+.. literalinclude:: /includes/authentication/aws-iam.rb
+   :start-after: start-aws-automatic-retrieval-connection-string
+   :end-before: end-aws-automatic-retrieval-connection-string
+   :language: ruby
+   :copyable:
+   :dedent:
+
+The driver will try to obtain credentials from the following sources, in
+the specified order:
+
+- ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY`` and ``AWS_SESSION_TOKEN``
+  environment variables. These environment variables are recognized by
+  a variety of AWS-related libraries and tools such as the official
+  AWS Ruby SDK and the AWS CLI. They are also defined when running in an
+  AWS Lambda environment.
+- The AWS STS `AssumeRoleWithWebIdentity action
+  <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`_.
+  This returns credentials associated with the service account token. This mechanism
+  requires the following environment variables to be set:
+
+  - ``AWS_WEB_IDENTITY_TOKEN_FILE`` - path to a file containing the service
+    account token.
+  - ``AWS_ROLE_ARN`` - the Amazon Resource Name (ARN) of the role that the
+    caller is assuming.
+  - ``AWS_ROLE_SESSION_NAME`` (optional) - An identifier for the assumed role
+    session. If omitted, a random name will be generated by the driver.
+
+- The AWS `ECS task metadata endpoint
+  <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`_.
+  This returns credentials associated with the ECS task role assigned to
+  the container.
+- The AWS `EC2 instance metadata endpoint
+  <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html>`_.
+  This returns credentials associated with the EC2 instance role assigned to
+  the instance.
+
+.. note::
+
+  A credentials source that provides any credentials must provide a complete
+  set of credentials. For example, the driver will raise an error if only
+  one of ``AWS_ACCESS_KEY_ID`` or ``AWS_SECRET_ACCESS_KEY`` environment
+  variables is populated but not the other.
+
+.. note::
+
+  If an application is running in an ECS container on an EC2 instance and
+  `the container is allowed access to the instance metadata
+  <https://aws.amazon.com/premiumsupport/knowledge-center/ecs-container-ec2-metadata/>`_,
+  the driver will attempt to retrieve credentials for the AWS authentication
+  mechanism from the EC2 instance metadata endpoint, thus potentially
+  authenticating as the IAM role assigned to the EC2 instance, if it was not
+  able to retrieve ECS task role credentials from the ECS task endpoint.
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed on this
+page, see the following API documentation:
+
+- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__

source/authentication/kerberos.txt

@@ -0,0 +1,93 @@
+.. _ruby-authentication-kerberos:
+
+=================
+Kerberos (GSSAPI)
+=================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: .NET, code example
+
+Overview
+--------
+
+The Generic Security Services API (GSSAPI) authentication mechanism allows you to
+use your principal name to authenticate to a Kerberos service.
+You can use this mechanism only when authenticating to MongoDB Enterprise Advanced.
+
+Using GSSAPI Authentication in Your Application
+-----------------------------------------------
+
+To configure the MongoDB server to use Kerberos, please refer to the
+:manual:`server Kerberos documentation
+</tutorial/control-access-to-mongodb-with-kerberos-authentication/>`.
+
+To use the Kerberos authentication mechanism with the Ruby MongoDB driver,
+an additional library implementing the Kerberos authenticator -
+`mongo_kerberos <https://rubygems.org/gems/mongo_kerberos>`_ - must be
+installed and loaded. To do so, add the following lines to your ``Gemfile``:
+
+.. code-block:: ruby
+
+  gem 'mongo', '~> 2'
+  gem 'mongo_kerberos', '~> 2'
+
+Then, add the following lines to your application code:
+
+.. code-block:: ruby
+
+  require 'mongo'
+  require 'mongo_kerberos'
+
+If using Kerberos authentication with **MRI**, the password is not specified
+in driver configuration and it is not sent to the MongoDB server by the driver.
+Instead a Kerberos session must be established externally to the driver
+and this session is used by the driver to prove the user's identity to
+the server. Establishing this session requires that the host system is
+configured for Kerberos authentication; see the `Kerberos documentation
+<https://web.mit.edu/kerberos/krb5-latest/doc/admin/install_clients.html>`_
+or your operating system documentation for details. Use the `kinit utility
+<https://web.mit.edu/kerberos/krb5-latest/doc/user/user_commands/kinit.html>`_
+to establish a Kerberos session.
+
+If using Kerberos authentication with **JRuby**, the Kerberos session may
+be estabished externally to the driver using the process described above
+for MRI; alternatively, the password may be provided directly to the driver
+by using client configuration, or the path to a keytab file may be provided by using
+configuration stored in the ``java.security.auth.login.config`` system property.
+Additionally, the Java runtime environment must be configured for Kerberos. See the 
+`MongoDB Java Driver Kerberos documentation
+<https://mongodb.github.io/mongo-java-driver/4.0/driver/tutorials/authentication/#gssapi>`_
+for more information.
+
+.. note::
+
+  Per the server Kerberos documentation, the FQDN of the host
+  running MongoDB must be specified when using Kerberos authentication.
+
+.. note::
+
+  If using MongoDB URIs, be sure to percent-escape special characters like
+  ``/`` and ``@`` when they appear in the username.
+
+.. code-block:: ruby
+
+  # Authenticate as appuser@MYREALM:
+  client = Mongo::Client.new("mongodb://appuser%40MYREALM@myserver.mycompany.com:27017/mydb?authMechanism=GSSAPI")
+
+  # Authenticate as myapp/appuser@MYREALM:
+  client = Mongo::Client.new("mongodb://myapp%2Fappuser%40MYREALM@myserver.mycompany.com:27017/mydb?authMechanism=GSSAPI")
+
+  # Authenticate using Ruby options:
+  client = Mongo::Client.new(['myserver.mycompany.com:27017'],
+                             auth_mech: :gssapi,
+                             user: 'myapp/appuser@MYREALM')