diff --git a/snooty.toml b/snooty.toml index efd33899..9cd0f222 100644 --- a/snooty.toml +++ b/snooty.toml @@ -25,6 +25,7 @@ toc_landing_pages = [ "/databases-collections", "/write", "/indexes", + "/security" "/data-formats" ] diff --git a/source/includes/authentication.php b/source/includes/authentication.php index 58557aca..7810406b 100644 --- a/source/includes/authentication.php +++ b/source/includes/authentication.php @@ -11,8 +11,8 @@ ]; $client = new MongoDB\Client( - 'mongodb://:', - $uriOptions, + 'mongodb://:', + $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' => '', + 'password' => '', + 'authSource' => '', + 'authMechanism' => 'SCRAM-SHA-1', +]; + +$client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, +); +// end-scram-sha-1-client + +// start-scram-sha-1-uri +$uri = 'mongodb://:@:/?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://:', - $uriOptions, + 'mongodb://:', + $uriOptions, ); // end-mongodb-X509-client @@ -47,8 +66,8 @@ ]; $client = new MongoDB\Client( - 'mongodb://:', - $uriOptions, + 'mongodb://:', + $uriOptions, ); // end-mongodb-aws-client @@ -59,8 +78,8 @@ // start-mongodb-aws-env-client $client = new MongoDB\Client( - 'mongodb://:', - ['authMechanism' => 'MONGODB-AWS'] + 'mongodb://:', + ['authMechanism' => 'MONGODB-AWS'] ); // end-mongodb-aws-env-client diff --git a/source/includes/usage-examples/connect-sample-app.php b/source/includes/usage-examples/connect-sample-app.php new file mode 100644 index 00000000..d89319ff --- /dev/null +++ b/source/includes/usage-examples/connect-sample-app.php @@ -0,0 +1,14 @@ +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()); +} diff --git a/source/security.txt b/source/security.txt index b70e1a59..485595de 100644 --- a/source/security.txt +++ b/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 ` or your own application. +Make sure to replace all placeholders in the code examples, such as ````, 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`