diff --git a/snooty.toml b/snooty.toml index 8fe30017..e8f02011 100644 --- a/snooty.toml +++ b/snooty.toml @@ -28,6 +28,7 @@ toc_landing_pages = [ "/indexes", "/security", "/upgrade", + "/security/authentication", ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/includes/authentication.php b/source/includes/authentication.php index ea7973ed..d1ee266d 100644 --- a/source/includes/authentication.php +++ b/source/includes/authentication.php @@ -2,6 +2,24 @@ require __DIR__ . '/../vendor/autoload.php'; +// start-default-client +$uriOptions = [ + 'username' => '', + 'password' => '', + 'authSource' => '', +]; + +$client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, +); +// end-default-client + +// start-default-uri +$uri = 'mongodb://:@:/?authSource=admin'; +$client = new MongoDB\Client($uri); +// end-default-uri + // start-scram-sha-256-client $uriOptions = [ 'username' => '', diff --git a/source/security/authentication.txt b/source/security/authentication.txt index f4be9f13..812d70d9 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -17,6 +17,13 @@ Authentication Mechanisms .. meta:: :keywords: authorize, secure, connect, code example +.. toctree:: + :caption: Authentication + + SCRAM + X.509 + AWS IAM + Overview -------- @@ -36,354 +43,30 @@ users. - `RFC 3986 `__ - :php:`rawurlencode ` in the PHP manual -.. _php-scram-sha-256: - -SCRAM-SHA-256 -------------- - -SCRAM-SHA-256, as defined by `RFC 7677 `__, -is the default authentication mechanism on MongoDB deployments -running {+mdb-server+} v4.0 or later. - -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 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'``. 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. - -.. 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 - -.. _php-scram-sha-1: - -SCRAM-SHA-1 ------------ - -SCRAM-SHA-1, as defined by `RFC 5802 `__, -is the default authentication mechanism on MongoDB deployments -running {+mdb-server+} v3.6. - -.. note:: - - {+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. - -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: - -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 -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 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 - - .. 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 - -.. _php-mongodb-aws: - -MONGODB-AWS ------------ - -.. important:: - - 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 use this -method to authenticate, you must specify ``'MONGODB-AWS'`` as the value of -the ``authMechanism`` connection option. - -.. note:: - - The {+php-library+} uses libmongoc's implementation of the MONGODB-AWS - authentication mechanism. To learn more about using this authentication mechanism - with libmongoc, see `Authentication via AWS IAM - `__ - in the C driver documentation. - -When you use the MONGODB-AWS mechanism, the driver tries to retrieve AWS -credentials from the following sources, in the order listed: - -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 -#. EC2 instance metadata - -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 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. -- ``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 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 - - .. 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 - -.. _php-mongodb-aws-env-vars: - -Environment Variables -~~~~~~~~~~~~~~~~~~~~~ - -If you don't provide a username and password when you construct your ``MongoDB\Client`` -object, the driver tries to retrieve AWS credentials from the following -environment variables: - -- ``AWS_ACCESS_KEY_ID`` -- ``AWS_SECRET_ACCESS_KEY`` -- ``AWS_SESSION_TOKEN`` - -To use these environment variables to authenticate your application, first set them to the -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 - - 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:: - - Don't percent-encode the values in these environment variables. - -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 URI. - -.. 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 - -.. 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. - -.. _php-mongodb-aws-oidc: - -AssumeRoleWithWebIdentity Request -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) -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 -``AssumeRoleWithWebIdentity`` request, ensure that the AWS config file exists in your -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`` connection option to ``'MONGODB-AWS'``. -To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example -` on this page. - -.. tip:: - - 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 - `__ - -.. _php-mongodb-aws-ecs: - -ECS Metadata -~~~~~~~~~~~~ - -If your application runs in an Elastic Container Service (ECS) container, -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 -example: - -.. tabs:: - - .. tab:: Shell Commands - :tabid: shell - - .. code-block:: sh - - export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= - - .. tab:: .env File - :tabid: dotenv - - .. code-block:: php - - 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 -``authMechanism`` option, see the :ref:`authMechanism example -` on this page. - -.. _php-mongodb-aws-ec2: - -EC2 Instance Metadata -~~~~~~~~~~~~~~~~~~~~~ - -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 -` on this page. - -.. note:: - - 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 ----------------------- - -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 library API documentation. - -To view a full list of URI options that you can pass to a ``MongoDB\Client``, see the -:php:`MongoDB\Driver\Manager::__construct parameters ` -in the extension API documentation. \ No newline at end of file +MongoDB Edition Compatibility +----------------------------- + +The following table lists the authentication mechanisms supported by MongoDB and +the {+mdb-server+} editions that each mechanism is compatible with. Click the name of +a mechanism to learn more about how to use it with your application. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - Authentication Mechanism + - Atlas + - Enterprise Advanced + - Community + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - No + - No \ No newline at end of file diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt new file mode 100644 index 00000000..494f4551 --- /dev/null +++ b/source/security/authentication/aws-iam.txt @@ -0,0 +1,269 @@ +.. _php-mongodb-aws: +.. _php-authentication-aws: + +================================ +AWS IAM Authentication Mechanism +================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: atlas, amazon web services, code example + +Overview +-------- + +The **MONGODB-AWS** authentication mechanism uses Amazon Web Services +Identity and Access Management (AWS IAM) credentials to authenticate a user to MongoDB. +You can use this mechanism only when authenticating to MongoDB Atlas. + +.. tip:: Configure Atlas for AWS IAM Authentication + + To learn more about configuring MongoDB Atlas for AWS IAM authentication, see + :atlas:`Set Up Authentication with AWS IAM ` in + the Atlas documentation. + +Specify MONGODB-AWS Authentication +---------------------------------- + +To use the MONGODB-AWS authentication mechanism, specify ``'MONGODB-AWS'`` as the value of +the ``authMechanism`` connection option. + +.. note:: + + The {+php-library+} uses libmongoc's implementation of the MONGODB-AWS + authentication mechanism. To learn more about using this authentication mechanism + with libmongoc, see `Authentication via AWS IAM + `__ + in the C driver documentation. + +When you use the MONGODB-AWS mechanism, the driver tries to retrieve AWS +credentials from the following sources, in the order listed: + +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 +#. EC2 instance metadata + +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 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. +- ``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 two ways: by passing an options array to the +``MongoDB\Client`` constructor or through parameters in your connection URI. +Select the :guilabel:`MongoDB\\Client` or :guilabel:`Connection URI` tab to +see the corresponding code: + +.. 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 + +.. _php-mongodb-aws-env-vars: + +Environment Variables +~~~~~~~~~~~~~~~~~~~~~ + +If you don't provide a username and password when you construct your ``MongoDB\Client`` +object, the driver tries to retrieve AWS credentials from the following +environment variables: + +- ``AWS_ACCESS_KEY_ID`` +- ``AWS_SECRET_ACCESS_KEY`` +- ``AWS_SESSION_TOKEN`` + +To use these environment variables to authenticate your application, first set them to the +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 + + 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:: + + Don't percent-encode the values in these environment variables. + +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 URI. + +.. 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 + +.. 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. + +.. _php-mongodb-aws-oidc: + +AssumeRoleWithWebIdentity Request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) +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 +``AssumeRoleWithWebIdentity`` request, ensure that the AWS config file exists in your +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`` connection option to ``'MONGODB-AWS'``. +To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example +` on this page. + +.. tip:: + + 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 + `__ + +.. _php-mongodb-aws-ecs: + +ECS Metadata +~~~~~~~~~~~~ + +If your application runs in an Elastic Container Service (ECS) container, +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 +example: + +.. tabs:: + + .. tab:: Shell Commands + :tabid: shell + + .. code-block:: sh + + export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI= + + .. tab:: .env File + :tabid: dotenv + + .. code-block:: php + + 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 +``authMechanism`` option, see the :ref:`authMechanism example +` on this page. + +.. _php-mongodb-aws-ec2: + +EC2 Instance Metadata +~~~~~~~~~~~~~~~~~~~~~ + +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 +` on this page. + +.. note:: + + 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 +---------------------- + +To learn more about creating a ``MongoDB\Client`` object in the {+php-library+}, +see the :ref:`php-client` guide. + +To learn more about connection options, see the :ref:`php-connection-options` guide. \ No newline at end of file diff --git a/source/security/authentication/scram.txt b/source/security/authentication/scram.txt new file mode 100644 index 00000000..6294f0b0 --- /dev/null +++ b/source/security/authentication/scram.txt @@ -0,0 +1,161 @@ +.. _php-scram-sha-256: +.. _php-authentication-scram: + +=============================== +SCRAM Authentication Mechanisms +=============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: salt, default, code example + +Overview +-------- + +**Salted Challenge Response Authentication Mechanism (SCRAM)** is a family of +authentication mechanisms that use a challenge-response mechanism to authenticate +the user. SCRAM-SHA-256, which uses the SHA-256 algorithm to hash your password, is the +default authentication mechanism in {+mdb-server+} version 4.0 +and later. SCRAM-SHA-1, which uses the SHA-1 algorithm instead, is the default +authentication mechanism in {+mdb-server+} versions earlier than 4.0. + +You can use SCRAM to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: SCRAM Mechanisms + + To learn more about the SCRAM family of authentication mechanisms, see + `RFC 5802 `__ and + :wikipedia:`Salted Challenge Response Authentication Mechanism ` + on Wikipedia. + + For more information about the MongoDB implementation of SCRAM, see + :manual:`SCRAM ` in the {+mdb-server+} manual. + +SCRAM-SHA-256 +------------- + +SCRAM-SHA-256, as defined by `RFC 7677 `__, +is the default authentication mechanism for MongoDB deployments. + +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 database in the connection + URI, if you include one. If you don't, it authenticates against the ``admin`` database. + +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. +Select the :guilabel:`MongoDB\\Client` or :guilabel:`Connection URI` tab to +see the corresponding code: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-default-client + :end-before: end-default-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-default-uri + :end-before: end-default-uri + +You can also explicitly specify the ``SCRAM-SHA-256`` authentication mechanism +by setting the ``authMechanism`` connection option to ``'SCRAM-SHA-256'``, as +shown in the following example: + +.. 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 + +.. _php-scram-sha-1: + +SCRAM-SHA-1 +----------- + +``SCRAM-SHA-1``, as defined by `RFC 5802 `__, +is a Salted Challenge Response Authentication Mechanism (SCRAM) that uses your +username and password, encrypted with the ``SHA-1`` algorithm, to authenticate +your user. + +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 database in the connection + URI, if you include one. If you don't, it 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. +Select the :guilabel:`MongoDB\\Client` or :guilabel:`Connection URI` tab to +see the corresponding code: + +.. 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 + +Additional Information +---------------------- + +To learn more about creating a ``MongoDB\Client`` object in the {+php-library+}, +see the :ref:`php-client` guide. + +To learn more about connection options, see the :ref:`php-connection-options` guide. \ No newline at end of file diff --git a/source/security/authentication/x509.txt b/source/security/authentication/x509.txt new file mode 100644 index 00000000..463ff2a0 --- /dev/null +++ b/source/security/authentication/x509.txt @@ -0,0 +1,79 @@ +.. _php-mongodb-x509: +.. _php-authentication-x509: + +============================== +X.509 Authentication Mechanism +============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: certificate, code example + +Overview +-------- + +In the **X.509** authentication mechanism, the server and client use the +:wikipedia:`TLS ` protocol to exchange X.509 public-key +certificates. You can use this mechanism to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: X.509 Mechanism + + To learn how to use TLS/SSL with the {+library-short+}, + see the :ref:`php-tls` guide. + + For more information about X.509 certificates, see + :manual:`Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments + ` in the {+mdb-server+} manual. + +Specify X.509 Authentication +---------------------------- + +To use the X.509 authentication 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 two ways: by passing an options array to the +``MongoDB\Client`` constructor or through parameters in your connection URI. +Select the :guilabel:`MongoDB\\Client` or :guilabel:`Connection URI` tab to +see the corresponding code: + +.. 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 + +Additional Information +---------------------- + +To learn more about creating a ``MongoDB\Client`` object in the {+php-library+}, +see the :ref:`php-client` guide. + +To learn more about connection options, see the :ref:`php-connection-options` guide. \ No newline at end of file