DOCSP-41989: Security landing page

snooty.toml

@@ -25,6 +25,7 @@ toc_landing_pages = [
     "/databases-collections",
     "/write",
     "/indexes",
+    "/security"
     "/data-formats"
 ]
 

source/includes/authentication.php

@@ -11,8 +11,8 @@
 ];
 
 $client = new MongoDB\Client(
-   'mongodb://<hostname>:<port>',
-   $uriOptions,
+    'mongodb://<hostname>:<port>',
+    $uriOptions,
 );
 // end-scram-sha-256-client
 
@@ -21,6 +21,25 @@
 $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,
@@ -29,8 +48,8 @@
 ];
 
 $client = new MongoDB\Client(
-   'mongodb://<hostname>:<port>',
-   $uriOptions,
+    'mongodb://<hostname>:<port>',
+    $uriOptions,
 );
 // end-mongodb-X509-client
 
@@ -47,8 +66,8 @@
 ];
 
 $client = new MongoDB\Client(
-   'mongodb://<hostname>:<port>',
-   $uriOptions,
+    'mongodb://<hostname>:<port>',
+    $uriOptions,
 );
 // end-mongodb-aws-client
 
@@ -59,8 +78,8 @@
 
 // start-mongodb-aws-env-client
 $client = new MongoDB\Client(
-   'mongodb://<hostname>:<port>',
-   ['authMechanism' => 'MONGODB-AWS']
+    'mongodb://<hostname>:<port>',
+    ['authMechanism' => 'MONGODB-AWS']
 );
 // end-mongodb-aws-env-client
 

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

@@ -0,0 +1,14 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+// Start example code here
+
+// End example code here
+
+try {
+    $client->test->command(['ping' => 1]);
+    echo 'Successfully pinged the MongoDB server.', PHP_EOL;
+} catch (MongoDB\Driver\Exception\RuntimeException $e) {
+    printf("Failed to ping the MongoDB server: %s\n", $e->getMessage());
+}

source/security.txt

@@ -4,9 +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/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 passed to the ``MongoDB\Client`` constructor, either as part of the connection
+   string or the ``$uriOptions`` array parameter
+#. 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`