DOCSP-41989: Security landing page

snooty.toml

@@ -23,7 +23,8 @@ toc_landing_pages = [
     "/reference/class/MongoDBModelIndexInfo",
     "/get-started",
     "/write",
-    "/indexes"
+    "/indexes",
+    "/security"
 ]
 
 sharedinclude_root =  "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/includes/authentication.php

@@ -0,0 +1,89 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+// start-scram-sha-256-client
+$uriOptions = [
+    'username' => '<username>',
+    'password' => '<password>',
+    'authSource' => '<authentication database>',
+    'authMechanism' => 'SCRAM-SHA-256',
+];
+
+$client = new MongoDB\Client(
+   'mongodb://<hostname>:<port>',
+   $uriOptions,
+);
+// end-scram-sha-256-client
+
+// start-scram-sha-256-uri
+$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-256';
+$client = new MongoDB\Client($uri);
+// end-scram-sha-256-uri
+
+// start-scram-sha-1-client
+$uriOptions = [
+    'username' => '<username>',
+    'password' => '<password>',
+    'authSource' => '<authentication database>',
+    'authMechanism' => 'SCRAM-SHA-1',
+];
+
+$client = new MongoDB\Client(
+   'mongodb://<hostname>:<port>',
+   $uriOptions,
+);
+// end-scram-sha-1-client
+
+// start-scram-sha-1-uri
+$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-1';
+$client = new MongoDB\Client($uri);
+// end-scram-sha-1-uri
+
+// start-mongodb-X509-client
+$uriOptions = [
+    'tls' => true,
+    'tlsCertificateKeyFile' => '<file path>',
+    'authMechanism' => 'MONGODB-X509',
+];
+
+$client = new MongoDB\Client(
+   'mongodb://<hostname>:<port>',
+   $uriOptions,
+);
+// end-mongodb-X509-client
+
+// start-mongodb-X509-uri
+$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=<file path>&authMechanism=MONGODB-X509';
+$client = new MongoDB\Client($uri);
+// end-mongodb-X509-uri
+
+// start-mongodb-aws-client
+$uriOptions = [
+    'username' => '<AWS IAM access key ID>',
+    'password' => '<AWS IAM secret access key>',
+    'authMechanism' => 'MONGODB-AWS',
+];
+
+$client = new MongoDB\Client(
+   'mongodb://<hostname>:<port>',
+   $uriOptions,
+);
+// end-mongodb-aws-client
+
+// start-mongodb-aws-uri
+$uri = 'mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?authMechanism=MONGODB-AWS';
+$client = new MongoDB\Client($uri);
+// end-mongodb-aws-uri
+
+// start-mongodb-aws-env-client
+$client = new MongoDB\Client(
+   'mongodb://<hostname>:<port>',
+   ['authMechanism' => 'MONGODB-AWS']
+);
+// end-mongodb-aws-env-client
+
+// start-mongodb-aws-env-uri
+$uri = 'mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS';
+$client = new MongoDB\Client($uri);
+// end-mongodb-aws-env-uri

source/includes/usage-examples/connect-sample-app.php

@@ -0,0 +1,16 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+// Start example code here
+
+// End example code here
+
+$admin = $client->admin;
+$result = $admin->command(['ping' => 1]);
+
+if ($result) {
+    echo 'Successfully pinged the MongoDB server.', PHP_EOL;
+} else {
+    echo 'Ping to MongoDB server failed.', PHP_EOL;
+}

source/security.txt

@@ -4,8 +4,217 @@
 Secure Your Data
 ================
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: ldap, authorize, ecs, aws, authenticate
+   :description: Learn how to use the PHP library to secure your data.
+
 .. toctree::
    :titlesonly:
    :maxdepth: 1
 
-   /security/in-use-encryption
+   /security/authentication
+   /security/in-use-encryption
+
+Overview
+--------
+
+MongoDB supports multiple mechanisms that you can use to authenticate your application.
+This page contains code examples that demonstrate each of these mechanisms.
+
+.. tip::
+
+   To learn more about any of the mechanisms shown on this page, see the link
+   provided in each section.
+
+To use an authentication example from this page, copy the code example into the
+:ref:`sample application <php-auth-sample>` or your own application.
+Make sure to replace all placeholders in the code examples, such as ``<hostname>``, with
+the relevant values for your MongoDB deployment.
+
+.. _php-auth-sample:
+
+.. include:: /includes/usage-examples/sample-app-intro.rst
+
+.. literalinclude:: /includes/usage-examples/connect-sample-app.php
+      :language: php
+      :copyable: true
+      :linenos:
+      :emphasize-lines: 5-7
+
+SCRAM-SHA-256
+-------------
+
+The following code shows how to authenticate by using the ``SCRAM-SHA-256``
+authentication mechanism:
+
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: Client
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-scram-sha-256-client
+         :end-before: end-scram-sha-256-client
+
+   .. tab:: Connection URI
+      :tabid: connectionstring
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-scram-sha-256-uri
+         :end-before: end-scram-sha-256-uri
+
+To learn more about SCRAM-SHA-256 authentication, see :ref:`php-scram-sha-256` in
+the Authentication guide.
+
+SCRAM-SHA-1
+-----------
+
+The following code shows how to authenticate by using the ``SCRAM-SHA-1``
+authentication mechanism:
+
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: Client
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-scram-sha-1-client
+         :end-before: end-scram-sha-1-client
+
+   .. tab:: Connection URI
+      :tabid: connectionstring
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-scram-sha-1-uri
+         :end-before: end-scram-sha-1-uri
+
+To learn more about SCRAM-SHA-1 authentication, see :ref:`php-scram-sha-1` in
+the Authentication guide.
+
+MONGODB X.509
+-------------
+
+The following code shows how to create a connection URI to authenticate by using
+the ``X.509`` authentication mechanism:
+
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: Client
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-mongodb-X509-client
+         :end-before: end-mongodb-X509-client
+
+   .. tab:: Connection URI
+      :tabid: connectionstring
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-mongodb-X509-uri
+         :end-before: end-mongodb-X509-uri
+
+To learn more about X.509 authentication, see :ref:`php-x509` in
+the Authentication guide.
+
+MONGODB-AWS
+-----------
+
+The following sections show how to connect to MongoDB by using the ``MONGODB-AWS``
+authentication mechanism. When you use the ``MONGODB-AWS`` mechanism, the {+php-library+}
+attempts to retrieve your AWS credentials from the following sources, in the order listed:
+
+1. Options parameter passed to the ``MongoDB\Client`` constructor or parameters in the
+   connection URI
+#. Environment variables
+#. AWS EKS ``AssumeRoleWithWebIdentity`` request
+#. ECS container metadata
+#. EC2 instance metadata
+
+Each section shows how to authenticate with ``MONGODB-AWS`` when retrieving your
+AWS credentials from options passed to your client or the alternative external sources.
+
+To learn more about authenticating with AWS, see :ref:`php-mongo-aws` in the
+Authentication guide.
+
+MongoDB\Client Credentials
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to pass AWS credentials to the ``MongoDB\Client`` constructor
+to authenticate with ``MONGODB-AWS``:
+
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: Client
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-mongodb-aws-client
+         :end-before: end-mongodb-aws-client
+
+   .. tab:: Connection URI
+      :tabid: connectionstring
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-mongodb-aws-uri
+         :end-before: end-mongodb-aws-uri
+
+External Credentials
+~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to authenticate with ``MONGODB-AWS`` when
+obtaining credentials from environment variables, an ``AssumeRoleWithWebIdentity``
+request, ECS metadata, or EC2 instance metadata:
+
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: Client
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-mongodb-aws-env-client
+         :end-before: end-mongodb-aws-env-client
+
+   .. tab:: Connection URI
+      :tabid: connectionstring
+
+      .. literalinclude:: /includes/authentication.php
+         :language: php
+         :dedent:
+         :start-after: start-mongodb-aws-env-uri
+         :end-before: end-mongodb-aws-env-uri
+
+To learn more about authenticating with AWS by obtaining external
+credentials, see the following sections in the Authentication guide:
+
+- :ref:`php-mongo-aws-environment`
+- :ref:`php-mongo-aws-assume-role`
+- :ref:`php-mongo-aws-ecs`
+- :ref:`php-mongo-aws-ec2`