From 3a2a4d485c0fab99cacd7bf8ee2d3d4ada2e8cc1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Sep 2024 13:33:24 -0400 Subject: [PATCH 01/14] DOCSP-41990: Authentication mechanisms --- source/includes/authentication.php | 44 +++++ source/index.txt | 1 + source/security.txt | 11 ++ source/security/authentication.txt | 286 +++++++++++++++++++++++++++++ 4 files changed, 342 insertions(+) create mode 100644 source/includes/authentication.php create mode 100644 source/security.txt create mode 100644 source/security/authentication.txt diff --git a/source/includes/authentication.php b/source/includes/authentication.php new file mode 100644 index 00000000..1df7b283 --- /dev/null +++ b/source/includes/authentication.php @@ -0,0 +1,44 @@ +:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; +$client = new Client($uri); +// end-scram-sha-256 + +// start-scram-sha-1 +$uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-1'; +$client = new Client($uri); +// end-scram-sha-1 + +// start-x509 +$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=path/to/client.pem&authMechanism=MONGODB-X509'; +$client = new Client($uri); +// end-x509 + +// start-aws-connection-uri +$uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS'; +$client = new Client($uri); +// end-aws-connection-uri + +// start-aws-connection-uri-session +$uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:'; +$client = new Client($uri); +// end-aws-connection-uri-session + +// start-aws-environment +$uri = 'mongodb://:/?authMechanism=MONGODB-AWS'; +$client = new Client($uri); +// end-aws-environment + +// start-kerberos +$uri = 'mongodb://@:/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:'; +$client = new Client($uri); +// end-kerberos + +// start-plain +$uri = 'mongodb://:@:/?authMechanism=PLAIN&tls=true'; +$client = new Client($uri); +// end-plain diff --git a/source/index.txt b/source/index.txt index b4b4841a..707a62d2 100644 --- a/source/index.txt +++ b/source/index.txt @@ -15,6 +15,7 @@ MongoDB PHP Library /write /aggregation /indexes + /security /tutorial /upgrade /reference diff --git a/source/security.txt b/source/security.txt new file mode 100644 index 00000000..d2a7afbe --- /dev/null +++ b/source/security.txt @@ -0,0 +1,11 @@ +.. _php-security: + +================ +Secure Your Data +================ + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /security/authentication \ No newline at end of file diff --git a/source/security/authentication.txt b/source/security/authentication.txt new file mode 100644 index 00000000..86566fb1 --- /dev/null +++ b/source/security/authentication.txt @@ -0,0 +1,286 @@ +.. _php-auth: + +========================= +Authentication Mechanisms +========================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: authorize, secure, connect, code example + +Overview +-------- + +This guide describes the {+php-library+} mechanisms you can use to authenticate +users. + +.. _php-scram-sha-256: + +SCRAM-SHA-256 +------------- + +SCRAM-SHA-256, as defined by `RFC 7677 `__, +is the default authentication mechanism on MongoDB deployments +running MongoDB v4.0 or later. + +To authenticate with this mechanism, set the following connection options: + +- ``db_username``: The database username to authenticate. +- ``db_password``: The database password to authenticate. +- ``authSource``: The MongoDB database to authenticate against. By default, + the {+php-library+} authenticates against the database in the connection + URI, if you include one. If you don't, it authenticates against the ``admin`` database. +- ``authMechanism``: Set to ``'SCRAM-SHA-256'``. + +You can set these options in the connection string when creating a +``MongoDB\Client`` object, as shown in the following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-scram-sha-256 + :end-before: // end-scram-sha-256 + +.. _php-scram-sha-1: + +SCRAM-SHA-1 +----------- + +SCRAM-SHA-1, as defined by `RFC 5802 `__, +is the default authentication mechanism on MongoDB deployments +running MongoDB v3.6. + +To authenticate with this mechanism, set the following connection options: + +- ``db_username``: The username to authenticate. +- ``db_password``: The password to authenticate. +- ``authSource``: The MongoDB database to authenticate against. By default, + the {+php-library+} authenticates against the ``admin`` database. +- ``authMechanism``: Set to ``'SCRAM-SHA-1'``. + +You can set these options in the connection string when creating a +``MongoDB\Client`` object, as shown in the following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-scram-sha-1 + :end-before: // end-scram-sha-1 + +.. _php-x509: + +MONGODB X.509 +------------- + +If you enable TLS, during the TLS handshake, the {+php-library+} can present an X.509 +client certificate to MongoDB to prove its identity. The ``MONGODB-X509`` authentication +mechanism uses this certificate to authenticate the client. + +To authenticate with this mechanism, set the following connection options: + +- ``tls``: Set to ``True``. +- ``tlsCertificateKeyFile``: The file path of the ``.pem`` file that contains your + client certificate and private key. +- ``authMechanism``: Set to ``'MONGODB-X509'``. + +You can set these options in the connection string when creating a +``MongoDB\Client`` object, as shown in the following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-x509 + :end-before: // end-x509 + +To learn more about enabling TLS, see the :ref:`php-tls` guide. + +.. _php-mongo-aws: + +MONGODB-AWS +----------- + +.. important:: + + The MONGODB-AWS authentication mechanism requires MongoDB Server v4.4 or later. + +The ``MONGODB-AWS`` authentication mechanism uses AWS IAM (Amazon Web Services Identity and +Access Management) or AWS Lambda credentials to authenticate your application. +To authenticate using this mechanism, first create a user with an associated Amazon Resource Name (ARN) on +the ``$external`` database, then specify the ``MONGODB-AWS`` authMechanism in the +URI. + +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. Named parameters passed to the Connection URI +#. Environment variables +#. AWS EKS AssumeRoleWithWebIdentity request +#. ECS container metadata +#. EC2 instance metadata + +The following sections describe how to use the {+php-library+} to retrieve credentials from +these sources and use them to authenticate your application. + +Connection URI +~~~~~~~~~~~~~~ + +First, the {+php-library+} checks whether you passed AWS credentials to the +``MongoDB\Client`` constructor as part of the connection +URI. To pass your credentials in the connection URI, set the following connection +options: + +- ``username``: The AWS IAM access key ID to authenticate. +- ``password``: The AWS IAM secret access key. +- ``authMechanism``: Set to ``'MONGODB-AWS'``. + +You can set these options in the connection string when creating a +``MongoDB\Client`` object, as shown in the following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-aws-connection-uri + :end-before: // end-aws-connection-uri + +You can also include an AWS session token by passing it into the +``authMechanismProperties`` parameter: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-aws-connection-uri-session + :end-before: // end-aws-connection-uri-session + +.. _php-mongo-aws-environment: + +Environment Variables +~~~~~~~~~~~~~~~~~~~~~ + +If you don't provide a username and password when you construct your ``MongoDB\Client`` +object, the {+php-library+} tries to retrieve AWS credentials from the following +environment variables: + +- ``AWS_ACCESS_KEY_ID`` +- ``AWS_SECRET_ACCESS_KEY`` +- ``AWS_SESSION_TOKEN`` (optional) + +To use these environment variables to authenticate your application, first set them to the +AWS IAM values needed for authentication, as shown in the following code +example: + +.. code-block:: sh + + export AWS_ACCESS_KEY_ID= + export AWS_SECRET_ACCESS_KEY= + export AWS_SESSION_TOKEN= + +After you set these environment variables, set the ``authMechanism`` +parameter in your connection URI to ``'MONGODB-AWS'``, as shown in the +following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-aws-environment + :end-before: // end-aws-environment + +.. _php-mongo-aws-assume-role: + +AssumeRoleWithWebIdentity Request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) +identity provider, the {+php-library+} can make an ``AssumeRoleWithWebIdentity`` request +to exchange the OIDC token for temporary AWS credentials for your application. + +To authenticate with temporary AWS IAM credentials returned by an +``AssumeRoleWithWebIdentity`` request, ensure that the AWS config file exists in your +environment and is configured with the ``AWS_WEB_IDENTITY_TOKEN_FILE`` +and ``AWS_ROLE_ARN`` environment variables. To learn how to create and configure +an AWS config file, see `Configuration `__ +in the AWS documentation. + +After you configure your environment for an ``AssumeRoleWithWebIdentity`` request, +set the ``authMechanism`` parameter in your connection URI to ``'MONGODB-AWS'``, +as shown in the following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-aws-environment + :end-before: // end-aws-environment + +For more information about using an ``AssumeRoleWithWebIdentity`` request to +authenticate your application, see the following AWS documentation: + +- `AssumeRoleWithWebIdentity `__ +- `Authenticating users for your cluster from an OpenID Connect identity provider `__ + +.. _php-mongo-aws-ecs: + +ECS Metadata +~~~~~~~~~~~~ + +If your application runs in an Elastic Container Service (ECS) container, +the {+php-library+} can automatically retrieve temporary AWS credentials from an +ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called +``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``, as shown in the following example: + +.. code-block:: sh + + export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= + +After you set the environment variable, set the ``authMechanism`` +parameter in your connection URI to ``'MONGODB-AWS'``, as shown in the +following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-aws-environment + :end-before: // end-aws-environment + +.. _php-mongo-aws-ec2: + +EC2 Instance Metadata +~~~~~~~~~~~~~~~~~~~~~ + +the {+php-library+} can automatically retrieve temporary AWS credentials from an +Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from +within an EC2 instance, set the ``authMechanism`` parameter in your connection +URI to ``'MONGODB-AWS'``, as shown in the following example: + +.. literalinclude:: /includes/authentication.php + :language: php + :copyable: true + :start-after: // start-aws-environment + :end-before: // end-aws-environment + +.. note:: + + If you set any of the environment variables from the preceding AWS authentication + methods, the {+php-library+} attempts to retrieve credentials by using those + methods before attempting to retrieve them from an EC2 instance. To attempt + to retrieve credentials only from an EC2 instance, ensure that the + environment variables are not set. + +Additional Information +---------------------- + +To learn more about creating a ``MongoDB\Client`` object in the {+php-library+}, +see the :ref:`php-client` guide. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``MongoDB\Client`` class, see :phpclass:`MongoDB\Client` +in the API documentation. From 123d73801f2835bfcecd8ebfefb84d01b73da10d Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Sep 2024 16:12:06 -0400 Subject: [PATCH 02/14] client tabs --- source/includes/authentication.php | 44 ---- source/security/authentication.txt | 379 +++++++++++++++++++---------- 2 files changed, 245 insertions(+), 178 deletions(-) delete mode 100644 source/includes/authentication.php diff --git a/source/includes/authentication.php b/source/includes/authentication.php deleted file mode 100644 index 1df7b283..00000000 --- a/source/includes/authentication.php +++ /dev/null @@ -1,44 +0,0 @@ -:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; -$client = new Client($uri); -// end-scram-sha-256 - -// start-scram-sha-1 -$uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-1'; -$client = new Client($uri); -// end-scram-sha-1 - -// start-x509 -$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=path/to/client.pem&authMechanism=MONGODB-X509'; -$client = new Client($uri); -// end-x509 - -// start-aws-connection-uri -$uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS'; -$client = new Client($uri); -// end-aws-connection-uri - -// start-aws-connection-uri-session -$uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:'; -$client = new Client($uri); -// end-aws-connection-uri-session - -// start-aws-environment -$uri = 'mongodb://:/?authMechanism=MONGODB-AWS'; -$client = new Client($uri); -// end-aws-environment - -// start-kerberos -$uri = 'mongodb://@:/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:'; -$client = new Client($uri); -// end-kerberos - -// start-plain -$uri = 'mongodb://:@:/?authMechanism=PLAIN&tls=true'; -$client = new Client($uri); -// end-plain diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 86566fb1..6aae1621 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -20,9 +20,19 @@ Authentication Mechanisms Overview -------- -This guide describes the {+php-library+} mechanisms you can use to authenticate +This guide describes the mechanisms you can use in the {+driver-short+} to authenticate users. +.. important:: Percent-Encoding + + You must :wikipedia:`percent-encode ` a username and password before + you include them in a MongoDB URI. To encode these values, you can use the ``rawurlencode()`` + PHP method. For more information, see `rawurlencode <{+php-manual+}/rawurlencode>`__ in + the PHP manual. + + Don't percent-encode the username or password when passing them to the + ``MongoDB\Client`` constructor. + .. _php-scram-sha-256: SCRAM-SHA-256 @@ -30,25 +40,48 @@ SCRAM-SHA-256 SCRAM-SHA-256, as defined by `RFC 7677 `__, is the default authentication mechanism on MongoDB deployments -running MongoDB v4.0 or later. +running {+mdb-server+} v4.0 or later. To authenticate with this mechanism, set the following connection options: -- ``db_username``: The database username to authenticate. -- ``db_password``: The database password to authenticate. +- ``username``: The username to authenticate. Percent-encode this value before including + it in a connection URI. +- ``password``: The password to authenticate. Percent-encode this value before including + it in a connection URI. - ``authSource``: The MongoDB database to authenticate against. By default, - the {+php-library+} authenticates against the database in the connection + {+driver-short+} authenticates against the database in the connection URI, if you include one. If you don't, it authenticates against the ``admin`` database. -- ``authMechanism``: Set to ``'SCRAM-SHA-256'``. +- ``authMechanism``: Set to ``SCRAM-SHA-256``. + +You can set these options in two ways: by passing arguments to the +``MongoDB\Client`` constructor or through parameters in your connection string. + +.. tabs:: + + .. tab:: MongoDB\Client + :tabid: Client + + .. code-block:: php -You can set these options in the connection string when creating a -``MongoDB\Client`` object, as shown in the following example: + $options = [ + 'username' => '', + 'password' => '', + 'authSource' => '', + 'authMechanism' => 'SCRAM-SHA-256', + ]; -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-scram-sha-256 - :end-before: // end-scram-sha-256 + $client = new Client( + 'mongodb://:', + $options, + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; + $client = new Client($uri); .. _php-scram-sha-1: @@ -57,110 +90,161 @@ SCRAM-SHA-1 SCRAM-SHA-1, as defined by `RFC 5802 `__, is the default authentication mechanism on MongoDB deployments -running MongoDB v3.6. +running {+mdb-server+} v3.6. To authenticate with this mechanism, set the following connection options: -- ``db_username``: The username to authenticate. -- ``db_password``: The password to authenticate. -- ``authSource``: The MongoDB database to authenticate against. By default, - the {+php-library+} authenticates against the ``admin`` database. +- ``username``: The username to authenticate. Percent-encode this value before including + it in a connection URI. +- ``password``: The password to authenticate. Percent-encode this value before including + it in a connection URI. +- ``authSource``: The MongoDB database to authenticate against. By default, the + {+php-library+} authenticates against the ``admin`` database. - ``authMechanism``: Set to ``'SCRAM-SHA-1'``. -You can set these options in the connection string when creating a -``MongoDB\Client`` object, as shown in the following example: +You can set these options in two ways: by passing arguments to the +``MongoDB\Client`` constructor or through parameters in your connection string. -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-scram-sha-1 - :end-before: // end-scram-sha-1 +.. tabs:: -.. _php-x509: + .. tab:: MongoDB\Client + :tabid: Client -MONGODB X.509 -------------- + .. code-block:: php + + $options = [ + 'username' => '', + 'password' => '', + 'authSource' => '', + 'authMechanism' => 'SCRAM-SHA-1', + ]; + + $client = new Client( + 'mongodb://:', + $options, + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-1'; + $client = new Client($uri); + +.. _php-mongodb-x509: + +MONGODB-X509 +------------ If you enable TLS, during the TLS handshake, the {+php-library+} can present an X.509 -client certificate to MongoDB to prove its identity. The ``MONGODB-X509`` authentication +client certificate to MongoDB to prove its identity. The MONGODB-X509 authentication mechanism uses this certificate to authenticate the client. To authenticate with this mechanism, set the following connection options: -- ``tls``: Set to ``True``. +- ``tls``: Set to ``true``. - ``tlsCertificateKeyFile``: The file path of the ``.pem`` file that contains your client certificate and private key. - ``authMechanism``: Set to ``'MONGODB-X509'``. -You can set these options in the connection string when creating a -``MongoDB\Client`` object, as shown in the following example: +You can set these options in two ways: by passing arguments to the +``MongoDB\Client`` constructor or through parameters in your connection string. + +.. tabs:: + + .. tab:: MongoDB\Client + :tabid: Client -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-x509 - :end-before: // end-x509 + .. code-block:: php -To learn more about enabling TLS, see the :ref:`php-tls` guide. + $options = [ + 'tls' => true, + 'tlsCertificateKeyFile' => '', + 'authMechanism' => 'MONGODB-X509', + ]; -.. _php-mongo-aws: + $client = new Client( + 'mongodb://:', + $options, + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=&authMechanism=MONGODB-X509'; + $client = new Client($uri); + +.. _php-mongodb-aws: MONGODB-AWS ----------- .. important:: - The MONGODB-AWS authentication mechanism requires MongoDB Server v4.4 or later. - -The ``MONGODB-AWS`` authentication mechanism uses AWS IAM (Amazon Web Services Identity and -Access Management) or AWS Lambda credentials to authenticate your application. -To authenticate using this mechanism, first create a user with an associated Amazon Resource Name (ARN) on -the ``$external`` database, then specify the ``MONGODB-AWS`` authMechanism in the -URI. + The MONGODB-AWS authentication mechanism requires MongoDB v4.4 or later. -When you use the ``MONGODB-AWS`` mechanism, the {+php-library+} attempts to -retrieve your AWS credentials from the following sources, in the order listed: +The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and +Access Management) or AWS Lambda credentials to authenticate your application. The +{+php-library+} tries to retrieve AWS credentials from the following sources, in the order listed: -1. Named parameters passed to the Connection URI +1. Named arguments passed to the ``MongoDB\Client`` constructor or parameters in the + connection URI #. Environment variables -#. AWS EKS AssumeRoleWithWebIdentity request -#. ECS container metadata -#. EC2 instance metadata +#. ``AssumeRoleWithWebIdentity`` request to the AWS STS +#. Instance metadata service on an Amazon EC2 instance with an IAM role configured The following sections describe how to use the {+php-library+} to retrieve credentials from these sources and use them to authenticate your application. -Connection URI -~~~~~~~~~~~~~~ +.. _php-mongodb-aws-credentials: + +``MongoDB\Client`` Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, the {+php-library+} checks whether you passed AWS credentials to the -``MongoDB\Client`` constructor as part of the connection -URI. To pass your credentials in the connection URI, set the following connection -options: +First, the {+php-library+} checks whether you passed AWS credentials +to the ``MongoDB\Client`` constructor, either as an options parameter or as part of the +connection URI. To pass your credentials to ``MongoDB\Client``, +set the following connection options: -- ``username``: The AWS IAM access key ID to authenticate. -- ``password``: The AWS IAM secret access key. +- ``username``: The AWS IAM access key ID to authenticate. Percent-encode this value + before including it in a connection URI. +- ``password``: The AWS IAM secret access key. Percent-encode this value before including + it in a connection URI. - ``authMechanism``: Set to ``'MONGODB-AWS'``. -You can set these options in the connection string when creating a -``MongoDB\Client`` object, as shown in the following example: +You can set these options in two ways: by passing parameter to the +``MongoDB\Client`` constructor or through parameters in your connection string. -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-aws-connection-uri - :end-before: // end-aws-connection-uri +.. tabs:: -You can also include an AWS session token by passing it into the -``authMechanismProperties`` parameter: + .. tab:: MongoDB\Client + :tabid: Client -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-aws-connection-uri-session - :end-before: // end-aws-connection-uri-session + .. code-block:: php -.. _php-mongo-aws-environment: + $options = [ + 'username' => '', + 'password' => '', + 'authMechanism' => 'MONGODB-AWS', + ]; + + $client = new Client( + 'mongodb://:', + $options, + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS'; + $client = new Client($uri); + +.. _php-mongodb-aws-env-vars: Environment Variables ~~~~~~~~~~~~~~~~~~~~~ @@ -171,7 +255,7 @@ environment variables: - ``AWS_ACCESS_KEY_ID`` - ``AWS_SECRET_ACCESS_KEY`` -- ``AWS_SESSION_TOKEN`` (optional) +- ``AWS_SESSION_TOKEN`` To use these environment variables to authenticate your application, first set them to the AWS IAM values needed for authentication, as shown in the following code @@ -183,20 +267,47 @@ example: export AWS_SECRET_ACCESS_KEY= export AWS_SESSION_TOKEN= +.. important:: + + Don't percent-encode the values in these environment variables. + After you set these environment variables, set the ``authMechanism`` -parameter in your connection URI to ``'MONGODB-AWS'``, as shown in the -following example: +connection option to ``'MONGODB-AWS'``. +You can set this option in two ways: by passing an argument to the +``MongoDB\Client`` constructor or through a parameter in your connection string. + +.. tabs:: + + .. tab:: MongoDB\Client + :tabid: Client + + .. code-block:: php + + $client = new Client( + 'mongodb://:', + ['authMechanism' => 'MONGODB-AWS'], + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-aws-environment - :end-before: // end-aws-environment + $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; + $client = new Client($uri); -.. _php-mongo-aws-assume-role: +.. tip:: AWS Lambda + + AWS Lambda runtimes can automatically set these environment variables during + initialization. For more information about using environment variables in an AWS Lambda + environment, see + `Using Lambda environment variables `__ + in the AWS documentation. -AssumeRoleWithWebIdentity Request -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _php-mongodb-aws-oidc: + +AssumeRoleWithWebIdentity +~~~~~~~~~~~~~~~~~~~~~~~~~ If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) identity provider, the {+php-library+} can make an ``AssumeRoleWithWebIdentity`` request @@ -204,74 +315,74 @@ to exchange the OIDC token for temporary AWS credentials for your application. To authenticate with temporary AWS IAM credentials returned by an ``AssumeRoleWithWebIdentity`` request, ensure that the AWS config file exists in your -environment and is configured with the ``AWS_WEB_IDENTITY_TOKEN_FILE`` -and ``AWS_ROLE_ARN`` environment variables. To learn how to create and configure +environment and is configured correctly. To learn how to create and configure an AWS config file, see `Configuration `__ in the AWS documentation. After you configure your environment for an ``AssumeRoleWithWebIdentity`` request, -set the ``authMechanism`` parameter in your connection URI to ``'MONGODB-AWS'``, -as shown in the following example: +set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. +You can set this option in two ways: by passing an argument to the +``MongoDB\Client`` constructor or through a parameter in your connection string. + +.. tabs:: + + .. tab:: MongoDB\Client + :tabid: Client + + .. code-block:: php + + $client = new Client( + 'mongodb://:', + ['authMechanism' => 'MONGODB-AWS'], + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-aws-environment - :end-before: // end-aws-environment + $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; + $client = new Client($uri); For more information about using an ``AssumeRoleWithWebIdentity`` request to authenticate your application, see the following AWS documentation: -- `AssumeRoleWithWebIdentity `__ - `Authenticating users for your cluster from an OpenID Connect identity provider `__ +- `AssumeRoleWithWebIdentity `__ -.. _php-mongo-aws-ecs: - -ECS Metadata -~~~~~~~~~~~~ - -If your application runs in an Elastic Container Service (ECS) container, -the {+php-library+} can automatically retrieve temporary AWS credentials from an -ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called -``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``, as shown in the following example: +.. _php-mongodb-aws-ec: -.. code-block:: sh +ECS Container or EC2 Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= +If your application runs in an Amazon Elastic Cloud Compute (EC2) instance in an +Elastic Container Service (ECS) container, the {+php-library+} can automatically retrieve +temporary AWS credentials from an ECS endpoint. -After you set the environment variable, set the ``authMechanism`` -parameter in your connection URI to ``'MONGODB-AWS'``, as shown in the -following example: +To use temporary credentials from within an EC2 instance, set the ``authMechanism`` +connection option to ``'MONGODB-AWS'``. +You can set this option in two ways: by passing an argument to the +``MongoDB\Client`` constructor or through a parameter in your connection string. -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-aws-environment - :end-before: // end-aws-environment +.. tabs:: -.. _php-mongo-aws-ec2: + .. tab:: MongoDB\Client + :tabid: Client -EC2 Instance Metadata -~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: php -the {+php-library+} can automatically retrieve temporary AWS credentials from an -Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from -within an EC2 instance, set the ``authMechanism`` parameter in your connection -URI to ``'MONGODB-AWS'``, as shown in the following example: + $client = new Client( + 'mongodb://:', + ['authMechanism' => 'MONGODB-AWS'], + ); -.. literalinclude:: /includes/authentication.php - :language: php - :copyable: true - :start-after: // start-aws-environment - :end-before: // end-aws-environment + .. tab:: Connection String + :tabid: connectionstring -.. note:: + .. code-block:: php - If you set any of the environment variables from the preceding AWS authentication - methods, the {+php-library+} attempts to retrieve credentials by using those - methods before attempting to retrieve them from an EC2 instance. To attempt - to retrieve credentials only from an EC2 instance, ensure that the - environment variables are not set. + $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; + $client = new Client($uri); Additional Information ---------------------- @@ -283,4 +394,4 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about the ``MongoDB\Client`` class, see :phpclass:`MongoDB\Client` -in the API documentation. +in the API documentation. \ No newline at end of file From f7653913a652628f7083df1180b27de161312a67 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Sep 2024 16:15:28 -0400 Subject: [PATCH 03/14] edits --- source/security/authentication.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 6aae1621..b85fb6d8 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -53,7 +53,7 @@ To authenticate with this mechanism, set the following connection options: URI, if you include one. If you don't, it authenticates against the ``admin`` database. - ``authMechanism``: Set to ``SCRAM-SHA-256``. -You can set these options in two ways: by passing arguments to the +You can set these options in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through parameters in your connection string. .. tabs:: @@ -102,7 +102,7 @@ To authenticate with this mechanism, set the following connection options: {+php-library+} authenticates against the ``admin`` database. - ``authMechanism``: Set to ``'SCRAM-SHA-1'``. -You can set these options in two ways: by passing arguments to the +You can set these options in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through parameters in your connection string. .. tabs:: @@ -148,7 +148,7 @@ To authenticate with this mechanism, set the following connection options: client certificate and private key. - ``authMechanism``: Set to ``'MONGODB-X509'``. -You can set these options in two ways: by passing arguments to the +You can set these options in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through parameters in your connection string. .. tabs:: @@ -215,7 +215,7 @@ set the following connection options: it in a connection URI. - ``authMechanism``: Set to ``'MONGODB-AWS'``. -You can set these options in two ways: by passing parameter to the +You can set these options in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through parameters in your connection string. .. tabs:: @@ -273,7 +273,7 @@ example: After you set these environment variables, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. -You can set this option in two ways: by passing an argument to the +You can set this option in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through a parameter in your connection string. .. tabs:: @@ -321,7 +321,7 @@ in the AWS documentation. After you configure your environment for an ``AssumeRoleWithWebIdentity`` request, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. -You can set this option in two ways: by passing an argument to the +You can set this option in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through a parameter in your connection string. .. tabs:: @@ -361,7 +361,7 @@ temporary AWS credentials from an ECS endpoint. To use temporary credentials from within an EC2 instance, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. -You can set this option in two ways: by passing an argument to the +You can set this option in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through a parameter in your connection string. .. tabs:: From 878fa7e69f0a302ea8b48b21637f9e90633942a5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Sep 2024 10:09:53 -0400 Subject: [PATCH 04/14] edits --- source/security/authentication.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index b85fb6d8..90193dcc 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -26,8 +26,8 @@ users. .. important:: Percent-Encoding You must :wikipedia:`percent-encode ` a username and password before - you include them in a MongoDB URI. To encode these values, you can use the ``rawurlencode()`` - PHP method. For more information, see `rawurlencode <{+php-manual+}/rawurlencode>`__ in + you include them in a MongoDB URI. You can use the ``rawurlencode()`` method to encode + these values. To learn more, see `rawurlencode <{+php-manual+}/rawurlencode>`__ in the PHP manual. Don't percent-encode the username or password when passing them to the @@ -48,10 +48,10 @@ To authenticate with this mechanism, set the following connection options: it in a connection URI. - ``password``: The password to authenticate. Percent-encode this value before including it in a connection URI. -- ``authSource``: The MongoDB database to authenticate against. By default, - {+driver-short+} authenticates against the database in the connection +- ``authSource``: The MongoDB database to authenticate against. By default, the + {+php-library+} authenticates against the database in the connection URI, if you include one. If you don't, it authenticates against the ``admin`` database. -- ``authMechanism``: Set to ``SCRAM-SHA-256``. +- ``authMechanism``: Set to ``'SCRAM-SHA-256'``. You can set these options in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through parameters in your connection string. From 264b1590f56491f0e25dbbb4333ec42989e62b49 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Sep 2024 12:05:46 -0400 Subject: [PATCH 05/14] add info --- source/security/authentication.txt | 80 ++++++++++++++++++++++++------ 1 file changed, 65 insertions(+), 15 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 90193dcc..e5882475 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -187,14 +187,20 @@ MONGODB-AWS The MONGODB-AWS authentication mechanism requires MongoDB v4.4 or later. The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and -Access Management) or AWS Lambda credentials to authenticate your application. The -{+php-library+} tries to retrieve AWS credentials from the following sources, in the order listed: +Access Management) or AWS Lambda credentials to authenticate your application. To +authenticate using this mechanism, first create a user with an associated Amazon Resource +Name (ARN) on the ``$external`` database, then specify the MONGODB-AWS authMechanism +in the URI. + +When you use the MONGODB-AWS mechanism, the {+php-library+} tries to retrieve AWS +credentials from the following sources, in the order listed: 1. Named arguments passed to the ``MongoDB\Client`` constructor or parameters in the connection URI #. Environment variables -#. ``AssumeRoleWithWebIdentity`` request to the AWS STS -#. Instance metadata service on an Amazon EC2 instance with an IAM role configured +#. AWS EKS ``AssumeRoleWithWebIdentity`` request +#. ECS container metadata +#. EC2 instance metadata The following sections describe how to use the {+php-library+} to retrieve credentials from these sources and use them to authenticate your application. @@ -300,14 +306,14 @@ You can set this option in two ways: by passing an options array to the AWS Lambda runtimes can automatically set these environment variables during initialization. For more information about using environment variables in an AWS Lambda - environment, see - `Using Lambda environment variables `__ + environment, see `Using Lambda environment variables + `__ in the AWS documentation. .. _php-mongodb-aws-oidc: -AssumeRoleWithWebIdentity -~~~~~~~~~~~~~~~~~~~~~~~~~ +``AssumeRoleWithWebIdentity`` Request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) identity provider, the {+php-library+} can make an ``AssumeRoleWithWebIdentity`` request @@ -350,16 +356,21 @@ authenticate your application, see the following AWS documentation: - `Authenticating users for your cluster from an OpenID Connect identity provider `__ - `AssumeRoleWithWebIdentity `__ -.. _php-mongodb-aws-ec: +.. _php-mongodb-aws-ecs: + +ECS Metadata +~~~~~~~~~~~~ -ECS Container or EC2 Instance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If your application runs in an Elastic Container Service (ECS) container, +the {+php-library+} can automatically retrieve temporary AWS credentials from an +ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called +``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``, as shown in the following example: + +.. code-block:: sh -If your application runs in an Amazon Elastic Cloud Compute (EC2) instance in an -Elastic Container Service (ECS) container, the {+php-library+} can automatically retrieve -temporary AWS credentials from an ECS endpoint. + export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= -To use temporary credentials from within an EC2 instance, set the ``authMechanism`` +After you set the environment variable, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. You can set this option in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through a parameter in your connection string. @@ -384,6 +395,45 @@ You can set this option in two ways: by passing an options array to the $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; $client = new Client($uri); +.. _php-mongo-aws-ec2: + +EC2 Instance Metadata +~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} can automatically retrieve temporary AWS credentials from an +Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from +within an EC2 instance, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. +You can set this option in two ways: by passing an options array to the +``MongoDB\Client`` constructor or through a parameter in your connection string. + +.. tabs:: + + .. tab:: MongoDB\Client + :tabid: Client + + .. code-block:: php + + $client = new Client( + 'mongodb://:', + ['authMechanism' => 'MONGODB-AWS'], + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; + $client = new Client($uri); + +.. note:: + + If you set any of the environment variables from the preceding AWS authentication + methods, the {+php-library+} attempts to retrieve credentials by using those + methods before attempting to retrieve them from an EC2 instance. To attempt + to retrieve credentials only from an EC2 instance, ensure that the + environment variables are not set. + Additional Information ---------------------- From 8825046d762ba2813d85f13ba35fb524e188752a Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Sep 2024 12:15:40 -0400 Subject: [PATCH 06/14] reduce repetition --- source/security/authentication.txt | 95 +++++++----------------------- 1 file changed, 22 insertions(+), 73 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index e5882475..0ad60076 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -190,12 +190,12 @@ The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Ident Access Management) or AWS Lambda credentials to authenticate your application. To authenticate using this mechanism, first create a user with an associated Amazon Resource Name (ARN) on the ``$external`` database, then specify the MONGODB-AWS authMechanism -in the URI. +connection option. When you use the MONGODB-AWS mechanism, the {+php-library+} tries to retrieve AWS credentials from the following sources, in the order listed: -1. Named arguments passed to the ``MongoDB\Client`` constructor or parameters in the +1. Options parameter passed to the ``MongoDB\Client`` constructor or parameters in the connection URI #. Environment variables #. AWS EKS ``AssumeRoleWithWebIdentity`` request @@ -327,34 +327,18 @@ in the AWS documentation. After you configure your environment for an ``AssumeRoleWithWebIdentity`` request, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. -You can set this option in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through a parameter in your connection string. - -.. tabs:: - - .. tab:: MongoDB\Client - :tabid: Client - - .. code-block:: php - - $client = new Client( - 'mongodb://:', - ['authMechanism' => 'MONGODB-AWS'], - ); - - .. tab:: Connection String - :tabid: connectionstring +To view an example that sets the ``authMechanism`` option, see the :ref:`php-mongodb-aws-env-vars` +section of this guide. - .. code-block:: php +.. tip:: - $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; - $client = new Client($uri); + For more information about using an ``AssumeRoleWithWebIdentity`` request to + authenticate your application, see the following AWS documentation: -For more information about using an ``AssumeRoleWithWebIdentity`` request to -authenticate your application, see the following AWS documentation: - -- `Authenticating users for your cluster from an OpenID Connect identity provider `__ -- `AssumeRoleWithWebIdentity `__ + - `Authenticating users for your cluster from an OpenID Connect identity provider + `__ + - `AssumeRoleWithWebIdentity + `__ .. _php-mongodb-aws-ecs: @@ -371,29 +355,9 @@ ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment va export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= After you set the environment variable, set the ``authMechanism`` -connection option to ``'MONGODB-AWS'``. -You can set this option in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through a parameter in your connection string. - -.. tabs:: - - .. tab:: MongoDB\Client - :tabid: Client - - .. code-block:: php - - $client = new Client( - 'mongodb://:', - ['authMechanism' => 'MONGODB-AWS'], - ); - - .. tab:: Connection String - :tabid: connectionstring - - .. code-block:: php - - $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; - $client = new Client($uri); +connection option to ``'MONGODB-AWS'``. To view an example that sets the +``authMechanism`` option, see the :ref:`php-mongodb-aws-env-vars` +section of this guide. .. _php-mongo-aws-ec2: @@ -403,28 +367,8 @@ EC2 Instance Metadata The {+driver-short+} can automatically retrieve temporary AWS credentials from an Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from within an EC2 instance, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. -You can set this option in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through a parameter in your connection string. - -.. tabs:: - - .. tab:: MongoDB\Client - :tabid: Client - - .. code-block:: php - - $client = new Client( - 'mongodb://:', - ['authMechanism' => 'MONGODB-AWS'], - ); - - .. tab:: Connection String - :tabid: connectionstring - - .. code-block:: php - - $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; - $client = new Client($uri); +To view an example that sets the ``authMechanism`` option, see the :ref:`php-mongodb-aws-env-vars` +section of this guide. .. note:: @@ -444,4 +388,9 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about the ``MongoDB\Client`` class, see :phpclass:`MongoDB\Client` -in the API documentation. \ No newline at end of file +in the library API documentation. + +To view a full list of URI options that you can pass to a ``MongoDB\Client``, see +`MongoDB\\Driver\\Manager::__construct Parameters +<{+php-manual+}\mongodb-driver-manager.construct.php#refsect1-mongodb-driver-manager.construct-parameters>`__ +in the extension API documentation. \ No newline at end of file From dd43825005ce6da91861cb4b59d9b0bf74b523b1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Sep 2024 12:27:23 -0400 Subject: [PATCH 07/14] add section --- source/security/authentication.txt | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 0ad60076..8ea99cda 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -189,8 +189,8 @@ MONGODB-AWS The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and Access Management) or AWS Lambda credentials to authenticate your application. To authenticate using this mechanism, first create a user with an associated Amazon Resource -Name (ARN) on the ``$external`` database, then specify the MONGODB-AWS authMechanism -connection option. +Name (ARN) on the ``$external`` database, then specify ``'MONGODB-AWS'`` as the value of +the ``authMechanism`` connection option. When you use the MONGODB-AWS mechanism, the {+php-library+} tries to retrieve AWS credentials from the following sources, in the order listed: @@ -279,6 +279,13 @@ example: After you set these environment variables, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. + +.. _php-mongodb-aws-env-example: + +Example +``````` + +The following example sets the ``authMechanism`` connection option. You can set this option in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through a parameter in your connection string. @@ -327,8 +334,8 @@ in the AWS documentation. After you configure your environment for an ``AssumeRoleWithWebIdentity`` request, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. -To view an example that sets the ``authMechanism`` option, see the :ref:`php-mongodb-aws-env-vars` -section of this guide. +To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example +` on this page. .. tip:: @@ -356,8 +363,8 @@ ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment va After you set the environment variable, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. To view an example that sets the -``authMechanism`` option, see the :ref:`php-mongodb-aws-env-vars` -section of this guide. +``authMechanism`` option, see the :ref:`authMechanism example +` on this page. .. _php-mongo-aws-ec2: @@ -367,8 +374,8 @@ EC2 Instance Metadata The {+driver-short+} can automatically retrieve temporary AWS credentials from an Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from within an EC2 instance, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. -To view an example that sets the ``authMechanism`` option, see the :ref:`php-mongodb-aws-env-vars` -section of this guide. +To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example +` on this page. .. note:: From d4f14df137a3fd80e5c0acef9ae6fcf578e7cce3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Sep 2024 12:28:41 -0400 Subject: [PATCH 08/14] fix link --- source/security/authentication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 8ea99cda..3e7294f5 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -399,5 +399,5 @@ in the library API documentation. To view a full list of URI options that you can pass to a ``MongoDB\Client``, see `MongoDB\\Driver\\Manager::__construct Parameters -<{+php-manual+}\mongodb-driver-manager.construct.php#refsect1-mongodb-driver-manager.construct-parameters>`__ +<{+php-manual+}/mongodb-driver-manager.construct.php#refsect1-mongodb-driver-manager.construct-parameters>`__ in the extension API documentation. \ No newline at end of file From 02e2245e7b22ed7da8a46bc8cab1596d6ac42cd0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 17 Sep 2024 15:38:14 -0400 Subject: [PATCH 09/14] MW feedback --- source/security/authentication.txt | 54 ++++++++++++++---------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 3e7294f5..df8d528c 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -54,11 +54,11 @@ To authenticate with this mechanism, set the following connection options: - ``authMechanism``: Set to ``'SCRAM-SHA-256'``. You can set these options in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through parameters in your connection string. +``MongoDB\Client`` constructor or through parameters in your connection URI. .. tabs:: - .. tab:: MongoDB\Client + .. tab:: MongoDB\\Client :tabid: Client .. code-block:: php @@ -75,7 +75,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: Connection String + .. tab:: connection URI :tabid: connectionstring .. code-block:: php @@ -103,11 +103,11 @@ To authenticate with this mechanism, set the following connection options: - ``authMechanism``: Set to ``'SCRAM-SHA-1'``. You can set these options in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through parameters in your connection string. +``MongoDB\Client`` constructor or through parameters in your connection URI. .. tabs:: - .. tab:: MongoDB\Client + .. tab:: MongoDB\\Client :tabid: Client .. code-block:: php @@ -124,7 +124,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: Connection String + .. tab:: connection URI :tabid: connectionstring .. code-block:: php @@ -149,11 +149,11 @@ To authenticate with this mechanism, set the following connection options: - ``authMechanism``: Set to ``'MONGODB-X509'``. You can set these options in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through parameters in your connection string. +``MongoDB\Client`` constructor or through parameters in your connection URI. .. tabs:: - .. tab:: MongoDB\Client + .. tab:: MongoDB\\Client :tabid: Client .. code-block:: php @@ -169,7 +169,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: Connection String + .. tab:: connection URI :tabid: connectionstring .. code-block:: php @@ -184,12 +184,12 @@ MONGODB-AWS .. important:: - The MONGODB-AWS authentication mechanism requires MongoDB v4.4 or later. + The MONGODB-AWS authentication mechanism requires {+mdb-server+} v4.4 or later. The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and -Access Management) or AWS Lambda credentials to authenticate your application. To -authenticate using this mechanism, first create a user with an associated Amazon Resource -Name (ARN) on the ``$external`` database, then specify ``'MONGODB-AWS'`` as the value of +Access Management) or AWS Lambda credentials to authenticate your application. To use this +method to authenticate, create a user with an associated Amazon Resource +Name (ARN) on the ``$external`` database. Then, specify ``'MONGODB-AWS'`` as the value of the ``authMechanism`` connection option. When you use the MONGODB-AWS mechanism, the {+php-library+} tries to retrieve AWS @@ -207,8 +207,8 @@ these sources and use them to authenticate your application. .. _php-mongodb-aws-credentials: -``MongoDB\Client`` Credentials -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +MongoDB\Client Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~ First, the {+php-library+} checks whether you passed AWS credentials to the ``MongoDB\Client`` constructor, either as an options parameter or as part of the @@ -222,11 +222,11 @@ set the following connection options: - ``authMechanism``: Set to ``'MONGODB-AWS'``. You can set these options in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through parameters in your connection string. +``MongoDB\Client`` constructor or through parameters in your connection URI. .. tabs:: - .. tab:: MongoDB\Client + .. tab:: MongoDB\\Client :tabid: Client .. code-block:: php @@ -242,7 +242,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: Connection String + .. tab:: connection URI :tabid: connectionstring .. code-block:: php @@ -287,11 +287,11 @@ Example The following example sets the ``authMechanism`` connection option. You can set this option in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through a parameter in your connection string. +``MongoDB\Client`` constructor or through a parameter in your connection URI. .. tabs:: - .. tab:: MongoDB\Client + .. tab:: MongoDB\\Client :tabid: Client .. code-block:: php @@ -301,7 +301,7 @@ You can set this option in two ways: by passing an options array to the ['authMechanism' => 'MONGODB-AWS'], ); - .. tab:: Connection String + .. tab:: connection URI :tabid: connectionstring .. code-block:: php @@ -319,8 +319,8 @@ You can set this option in two ways: by passing an options array to the .. _php-mongodb-aws-oidc: -``AssumeRoleWithWebIdentity`` Request -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +AssumeRoleWithWebIdentity Request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) identity provider, the {+php-library+} can make an ``AssumeRoleWithWebIdentity`` request @@ -379,11 +379,9 @@ To view an example that sets the ``authMechanism`` option, see the :ref:`authMec .. note:: - If you set any of the environment variables from the preceding AWS authentication - methods, the {+php-library+} attempts to retrieve credentials by using those - methods before attempting to retrieve them from an EC2 instance. To attempt - to retrieve credentials only from an EC2 instance, ensure that the - environment variables are not set. + The {+php-library+} retrieves credentials from an EC2 instance only if the + environment variables described in the :ref:`php-mongodb-aws-env-vars` section + are not set. Additional Information ---------------------- From 4f5cb4344886dbb0139469488f710c1bd5026ef6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 17 Sep 2024 15:48:43 -0400 Subject: [PATCH 10/14] fix --- source/security/authentication.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index df8d528c..fa67050c 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -75,7 +75,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: connection URI + .. tab:: Connection URI :tabid: connectionstring .. code-block:: php @@ -124,7 +124,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: connection URI + .. tab:: Connection URI :tabid: connectionstring .. code-block:: php @@ -169,7 +169,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: connection URI + .. tab:: Connection URI :tabid: connectionstring .. code-block:: php @@ -242,7 +242,7 @@ You can set these options in two ways: by passing an options array to the $options, ); - .. tab:: connection URI + .. tab:: Connection URI :tabid: connectionstring .. code-block:: php @@ -301,7 +301,7 @@ You can set this option in two ways: by passing an options array to the ['authMechanism' => 'MONGODB-AWS'], ); - .. tab:: connection URI + .. tab:: Connection URI :tabid: connectionstring .. code-block:: php From d7cc5bac58a5ca5e608965d9bd5295b3793809b0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 24 Sep 2024 13:32:15 -0400 Subject: [PATCH 11/14] JM most feedback --- source/security/authentication.txt | 132 ++++++++++++++--------------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index fa67050c..79cf17ca 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -27,11 +27,14 @@ users. You must :wikipedia:`percent-encode ` a username and password before you include them in a MongoDB URI. You can use the ``rawurlencode()`` method to encode - these values. To learn more, see `rawurlencode <{+php-manual+}/rawurlencode>`__ in - the PHP manual. + these values according to the URI syntax specified in RFC 3986. Don't percent-encode the + username or password when passing them in an options array parameter to the ``MongoDB\Client`` + constructor. - Don't percent-encode the username or password when passing them to the - ``MongoDB\Client`` constructor. + To learn more, see the following resources: + + - `RFC 3986 `__ + - `rawurlencode <{+php-manual+}/rawurlencode>`__ in the PHP manual .. _php-scram-sha-256: @@ -63,16 +66,16 @@ You can set these options in two ways: by passing an options array to the .. code-block:: php - $options = [ + $uriOptions = [ 'username' => '', 'password' => '', 'authSource' => '', 'authMechanism' => 'SCRAM-SHA-256', ]; - $client = new Client( + $client = new MongoDB\Client( 'mongodb://:', - $options, + $uriOptions, ); .. tab:: Connection URI @@ -81,7 +84,7 @@ You can set these options in two ways: by passing an options array to the .. code-block:: php $uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; - $client = new Client($uri); + $client = new MongoDB\Client($uri); .. _php-scram-sha-1: @@ -92,45 +95,14 @@ SCRAM-SHA-1, as defined by `RFC 5802 `__ is the default authentication mechanism on MongoDB deployments running {+mdb-server+} v3.6. -To authenticate with this mechanism, set the following connection options: - -- ``username``: The username to authenticate. Percent-encode this value before including - it in a connection URI. -- ``password``: The password to authenticate. Percent-encode this value before including - it in a connection URI. -- ``authSource``: The MongoDB database to authenticate against. By default, the - {+php-library+} authenticates against the ``admin`` database. -- ``authMechanism``: Set to ``'SCRAM-SHA-1'``. - -You can set these options in two ways: by passing an options array to the -``MongoDB\Client`` constructor or through parameters in your connection URI. - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. code-block:: php - - $options = [ - 'username' => '', - 'password' => '', - 'authSource' => '', - 'authMechanism' => 'SCRAM-SHA-1', - ]; - - $client = new Client( - 'mongodb://:', - $options, - ); - - .. tab:: Connection URI - :tabid: connectionstring +.. note:: - .. code-block:: php + {+php-library+} v1.20 drops support for {+mdb-server+} v3.6. When using v1.20+ of + the library, all supported server versions default to the SCRAM-SHA-256 authentication + mechanism. - $uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-1'; - $client = new Client($uri); +To authenticate with this mechanism, use the same syntax as the :ref:`php-scram-sha-256`, +but change the value of the ``authMechanism`` option to ``'SCRAM-SHA-1'``. .. _php-mongodb-x509: @@ -158,15 +130,15 @@ You can set these options in two ways: by passing an options array to the .. code-block:: php - $options = [ + $uriOptions = [ 'tls' => true, 'tlsCertificateKeyFile' => '', 'authMechanism' => 'MONGODB-X509', ]; - $client = new Client( + $client = new MongoDB\Client( 'mongodb://:', - $options, + $uriOptions, ); .. tab:: Connection URI @@ -175,7 +147,7 @@ You can set these options in two ways: by passing an options array to the .. code-block:: php $uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=&authMechanism=MONGODB-X509'; - $client = new Client($uri); + $client = new MongoDB\Client($uri); .. _php-mongodb-aws: @@ -231,15 +203,15 @@ You can set these options in two ways: by passing an options array to the .. code-block:: php - $options = [ + $uriOptions = [ 'username' => '', 'password' => '', 'authMechanism' => 'MONGODB-AWS', ]; - $client = new Client( + $client = new MongoDB\Client( 'mongodb://:', - $options, + $uriOptions, ); .. tab:: Connection URI @@ -248,7 +220,7 @@ You can set these options in two ways: by passing an options array to the .. code-block:: php $uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS'; - $client = new Client($uri); + $client = new MongoDB\Client($uri); .. _php-mongodb-aws-env-vars: @@ -264,14 +236,28 @@ environment variables: - ``AWS_SESSION_TOKEN`` To use these environment variables to authenticate your application, first set them to the -AWS IAM values needed for authentication, as shown in the following code -example: +AWS IAM values needed for authentication. You can run the ``export`` command in your shell or +add the variables to a ``.env`` file, as shown in the following code example: + +.. tabs:: + + .. tab:: Shell Commands + :tabid: shell + + .. code-block:: sh -.. code-block:: sh + export AWS_ACCESS_KEY_ID= + export AWS_SECRET_ACCESS_KEY= + export AWS_SESSION_TOKEN= - export AWS_ACCESS_KEY_ID= - export AWS_SECRET_ACCESS_KEY= - export AWS_SESSION_TOKEN= + .. tab:: .env File + :tabid: dotenv + + .. code-block:: php + + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_SESSION_TOKEN= .. important:: @@ -296,7 +282,7 @@ You can set this option in two ways: by passing an options array to the .. code-block:: php - $client = new Client( + $client = new MongoDB\Client( 'mongodb://:', ['authMechanism' => 'MONGODB-AWS'], ); @@ -306,8 +292,8 @@ You can set this option in two ways: by passing an options array to the .. code-block:: php - $uri = 'mongodb://:/?&authMechanism=MONGODB-AWS'; - $client = new Client($uri); + $uri = 'mongodb://:/?authMechanism=MONGODB-AWS'; + $client = new MongoDB\Client($uri); .. tip:: AWS Lambda @@ -355,11 +341,25 @@ ECS Metadata If your application runs in an Elastic Container Service (ECS) container, the {+php-library+} can automatically retrieve temporary AWS credentials from an ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called -``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``, as shown in the following example: +``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``. You can set this variable by running +the ``export`` shell command or adding it to your ``.env`` file, as shown in the following +example: + +.. tabs:: -.. code-block:: sh + .. tab:: Shell Commands + :tabid: shell + + .. code-block:: sh + + export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= + + .. tab:: .env File + :tabid: dotenv + + .. code-block:: php - export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= + AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= After you set the environment variable, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. To view an example that sets the @@ -396,6 +396,6 @@ To learn more about the ``MongoDB\Client`` class, see :phpclass:`MongoDB\Client` in the library API documentation. To view a full list of URI options that you can pass to a ``MongoDB\Client``, see -`MongoDB\\Driver\\Manager::__construct Parameters +`MongoDB\\Driver\\Manager::__construct() Parameters <{+php-manual+}/mongodb-driver-manager.construct.php#refsect1-mongodb-driver-manager.construct-parameters>`__ in the extension API documentation. \ No newline at end of file From c1371569e08e160c6fe71ac55a7c0161f963dc8a Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 24 Sep 2024 13:42:26 -0400 Subject: [PATCH 12/14] move to code file --- source/includes/authentication.php | 70 +++++++++++++++++++++ source/security/authentication.txt | 99 ++++++++++++------------------ 2 files changed, 110 insertions(+), 59 deletions(-) create mode 100644 source/includes/authentication.php diff --git a/source/includes/authentication.php b/source/includes/authentication.php new file mode 100644 index 00000000..58557aca --- /dev/null +++ b/source/includes/authentication.php @@ -0,0 +1,70 @@ + '', + 'password' => '', + 'authSource' => '', + 'authMechanism' => 'SCRAM-SHA-256', +]; + +$client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, +); +// end-scram-sha-256-client + +// start-scram-sha-256-uri +$uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; +$client = new MongoDB\Client($uri); +// end-scram-sha-256-uri + +// start-mongodb-X509-client +$uriOptions = [ + 'tls' => true, + 'tlsCertificateKeyFile' => '', + 'authMechanism' => 'MONGODB-X509', +]; + +$client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, +); +// end-mongodb-X509-client + +// start-mongodb-X509-uri +$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=&authMechanism=MONGODB-X509'; +$client = new MongoDB\Client($uri); +// end-mongodb-X509-uri + +// start-mongodb-aws-client +$uriOptions = [ + 'username' => '', + 'password' => '', + 'authMechanism' => 'MONGODB-AWS', +]; + +$client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, +); +// end-mongodb-aws-client + +// start-mongodb-aws-uri +$uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS'; +$client = new MongoDB\Client($uri); +// end-mongodb-aws-uri + +// start-mongodb-aws-env-client +$client = new MongoDB\Client( + 'mongodb://:', + ['authMechanism' => 'MONGODB-AWS'] +); +// end-mongodb-aws-env-client + +// start-mongodb-aws-env-uri +$uri = 'mongodb://:/?authMechanism=MONGODB-AWS'; +$client = new MongoDB\Client($uri); +// end-mongodb-aws-env-uri diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 79cf17ca..134e2608 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -64,27 +64,20 @@ You can set these options in two ways: by passing an options array to the .. tab:: MongoDB\\Client :tabid: Client - .. code-block:: php - - $uriOptions = [ - 'username' => '', - 'password' => '', - 'authSource' => '', - 'authMechanism' => 'SCRAM-SHA-256', - ]; - - $client = new MongoDB\Client( - 'mongodb://:', - $uriOptions, - ); + .. 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 - .. code-block:: php - - $uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; - $client = new MongoDB\Client($uri); + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-scram-sha-256-uri + :end-before: end-scram-sha-256-uri .. _php-scram-sha-1: @@ -128,26 +121,20 @@ You can set these options in two ways: by passing an options array to the .. tab:: MongoDB\\Client :tabid: Client - .. code-block:: php - - $uriOptions = [ - 'tls' => true, - 'tlsCertificateKeyFile' => '', - 'authMechanism' => 'MONGODB-X509', - ]; - - $client = new MongoDB\Client( - 'mongodb://:', - $uriOptions, - ); + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-mongodb-X509-client + :end-before: end-mongodb-X509-client .. tab:: Connection URI :tabid: connectionstring - .. code-block:: php - - $uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=&authMechanism=MONGODB-X509'; - $client = new MongoDB\Client($uri); + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-mongodb-X509-uri + :end-before: end-mongodb-X509-uri .. _php-mongodb-aws: @@ -201,26 +188,20 @@ You can set these options in two ways: by passing an options array to the .. tab:: MongoDB\\Client :tabid: Client - .. code-block:: php - - $uriOptions = [ - 'username' => '', - 'password' => '', - 'authMechanism' => 'MONGODB-AWS', - ]; - - $client = new MongoDB\Client( - 'mongodb://:', - $uriOptions, - ); + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-mongodb-aws-client + :end-before: end-mongodb-aws-client .. tab:: Connection URI :tabid: connectionstring - .. code-block:: php - - $uri = 'mongodb://:@:/?authMechanism=MONGODB-AWS'; - $client = new MongoDB\Client($uri); + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-mongodb-aws-uri + :end-before: end-mongodb-aws-uri .. _php-mongodb-aws-env-vars: @@ -280,20 +261,20 @@ You can set this option in two ways: by passing an options array to the .. tab:: MongoDB\\Client :tabid: Client - .. code-block:: php - - $client = new MongoDB\Client( - 'mongodb://:', - ['authMechanism' => 'MONGODB-AWS'], - ); + .. 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 - .. code-block:: php - - $uri = 'mongodb://:/?authMechanism=MONGODB-AWS'; - $client = new MongoDB\Client($uri); + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-mongodb-aws-env-uri + :end-before: end-mongodb-aws-env-uri .. tip:: AWS Lambda From 197b72677c44ffa6d0b1780faee791b4d086b6ac Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 24 Sep 2024 15:35:49 -0400 Subject: [PATCH 13/14] more JM edits --- source/security/authentication.txt | 32 +++++++++++++++++++----------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 134e2608..5453dab8 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -54,7 +54,8 @@ To authenticate with this mechanism, set the following connection options: - ``authSource``: The MongoDB database to authenticate against. By default, the {+php-library+} authenticates against the database in the connection URI, if you include one. If you don't, it authenticates against the ``admin`` database. -- ``authMechanism``: Set to ``'SCRAM-SHA-256'``. +- ``authMechanism``: Set to ``'SCRAM-SHA-256'``. When connected to {+mdb-server+} v4.0, + setting ``authMechanism`` is optional. You can set these options in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through parameters in your connection URI. @@ -147,11 +148,18 @@ MONGODB-AWS The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and Access Management) or AWS Lambda credentials to authenticate your application. To use this -method to authenticate, create a user with an associated Amazon Resource -Name (ARN) on the ``$external`` database. Then, specify ``'MONGODB-AWS'`` as the value of +method to authenticate, you must specify ``'MONGODB-AWS'`` as the value of the ``authMechanism`` connection option. -When you use the MONGODB-AWS mechanism, the {+php-library+} tries to retrieve AWS +.. note:: + + The {+php-library+} uses the C driver's implementation of the MONGODB-AWS + authentication mechanism. To learn more about using this authentication mechanism + with the C driver, see `Authentication via AWS IAM + `__ + in the C documentation. + +When you use the MONGODB-AWS mechanism, the C driver tries to retrieve AWS credentials from the following sources, in the order listed: 1. Options parameter passed to the ``MongoDB\Client`` constructor or parameters in the @@ -161,16 +169,16 @@ credentials from the following sources, in the order listed: #. ECS container metadata #. EC2 instance metadata -The following sections describe how to use the {+php-library+} to retrieve credentials from -these sources and use them to authenticate your application. +The following sections describe how to retrieve credentials from +these sources and use them to authenticate your PHP application. .. _php-mongodb-aws-credentials: MongoDB\Client Credentials ~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, the {+php-library+} checks whether you passed AWS credentials -to the ``MongoDB\Client`` constructor, either as an options parameter or as part of the +First, the C driver checks whether you passed AWS credentials to the +``MongoDB\Client`` constructor, either as an options parameter or as part of the connection URI. To pass your credentials to ``MongoDB\Client``, set the following connection options: @@ -209,7 +217,7 @@ Environment Variables ~~~~~~~~~~~~~~~~~~~~~ If you don't provide a username and password when you construct your ``MongoDB\Client`` -object, the {+php-library+} tries to retrieve AWS credentials from the following +object, the driver tries to retrieve AWS credentials from the following environment variables: - ``AWS_ACCESS_KEY_ID`` @@ -290,7 +298,7 @@ AssumeRoleWithWebIdentity Request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) -identity provider, the {+php-library+} can make an ``AssumeRoleWithWebIdentity`` request +identity provider, the C driver can make an ``AssumeRoleWithWebIdentity`` request to exchange the OIDC token for temporary AWS credentials for your application. To authenticate with temporary AWS IAM credentials returned by an @@ -320,7 +328,7 @@ ECS Metadata ~~~~~~~~~~~~ If your application runs in an Elastic Container Service (ECS) container, -the {+php-library+} can automatically retrieve temporary AWS credentials from an +the C driver can automatically retrieve temporary AWS credentials from an ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``. You can set this variable by running the ``export`` shell command or adding it to your ``.env`` file, as shown in the following @@ -352,7 +360,7 @@ connection option to ``'MONGODB-AWS'``. To view an example that sets the EC2 Instance Metadata ~~~~~~~~~~~~~~~~~~~~~ -The {+driver-short+} can automatically retrieve temporary AWS credentials from an +The C driver can automatically retrieve temporary AWS credentials from an Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from within an EC2 instance, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example From 4d42c3c7bc54251e604986afdacdf23cb8286c2e Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 25 Sep 2024 13:04:20 -0400 Subject: [PATCH 14/14] JM feedback 2 --- source/security/authentication.txt | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 5453dab8..13050e19 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -153,17 +153,17 @@ the ``authMechanism`` connection option. .. note:: - The {+php-library+} uses the C driver's implementation of the MONGODB-AWS + The {+php-library+} uses libmongoc's implementation of the MONGODB-AWS authentication mechanism. To learn more about using this authentication mechanism - with the C driver, see `Authentication via AWS IAM + with libmongoc, see `Authentication via AWS IAM `__ - in the C documentation. + in the C driver documentation. -When you use the MONGODB-AWS mechanism, the C driver tries to retrieve AWS +When you use the MONGODB-AWS mechanism, the driver tries to retrieve 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 +1. Options passed to the ``MongoDB\Client`` either as part of the connection + URI or an options parameter #. Environment variables #. AWS EKS ``AssumeRoleWithWebIdentity`` request #. ECS container metadata @@ -177,10 +177,10 @@ these sources and use them to authenticate your PHP application. MongoDB\Client Credentials ~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, the C driver checks whether you passed AWS credentials to the -``MongoDB\Client`` constructor, either as an options parameter or as part of the -connection URI. To pass your credentials to ``MongoDB\Client``, -set the following connection options: +First, the driver checks whether you passed AWS credentials to the +``MongoDB\Client`` constructor, either as as part of the connection +URI or the ``$uriOptions`` array parameter. To pass your credentials to +``MongoDB\Client``, set the following connection options: - ``username``: The AWS IAM access key ID to authenticate. Percent-encode this value before including it in a connection URI. @@ -298,7 +298,7 @@ AssumeRoleWithWebIdentity Request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) -identity provider, the C driver can make an ``AssumeRoleWithWebIdentity`` request +identity provider, the driver can make an ``AssumeRoleWithWebIdentity`` request to exchange the OIDC token for temporary AWS credentials for your application. To authenticate with temporary AWS IAM credentials returned by an @@ -328,7 +328,7 @@ ECS Metadata ~~~~~~~~~~~~ If your application runs in an Elastic Container Service (ECS) container, -the C driver can automatically retrieve temporary AWS credentials from an +the driver can automatically retrieve temporary AWS credentials from an ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``. You can set this variable by running the ``export`` shell command or adding it to your ``.env`` file, as shown in the following @@ -360,7 +360,7 @@ connection option to ``'MONGODB-AWS'``. To view an example that sets the EC2 Instance Metadata ~~~~~~~~~~~~~~~~~~~~~ -The C driver can automatically retrieve temporary AWS credentials from an +The driver can automatically retrieve temporary AWS credentials from an Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from within an EC2 instance, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``. To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example