Docs Menu
Docs Home
/
Languages
/
PHP
/
PHP Library Manual
/
Secure Your Data

Authentication Mechanisms

On this page

  • Overview
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • MONGODB-X509
  • MONGODB-AWS
  • MongoDB\Client Credentials
  • Environment Variables
  • AssumeRoleWithWebIdentity Request
  • ECS Metadata
  • EC2 Instance Metadata
  • Additional Information
  • API Documentation

Overview

This guide describes the mechanisms you can use in the PHP library to authenticate users.

Important

Percent-Encoding

You must percent-encode a username and password before you include them in a MongoDB URI. You can use the rawurlencode() method to encode 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.

To learn more, see the following resources:

  • RFC 3986

  • rawurlencode in the PHP manual

SCRAM-SHA-256

SCRAM-SHA-256, as defined by RFC 7677, is the default authentication mechanism on MongoDB deployments running MongoDB 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 MongoDB 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 MongoDB 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.

$uriOptions = [
    'username' => '<username>',
    'password' => '<password>',
    'authSource' => '<authentication database>',
    'authMechanism' => 'SCRAM-SHA-256',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-256';
$client = new MongoDB\Client($uri);

SCRAM-SHA-1

SCRAM-SHA-1, as defined by RFC 5802, is the default authentication mechanism on MongoDB deployments running MongoDB Server v3.6.

Note

MongoDB PHP Library v1.20 drops support for MongoDB 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 SCRAM-SHA-256, but change the value of the authMechanism option to 'SCRAM-SHA-1'.

MONGODB-X509

If you enable TLS, during the TLS handshake, the MongoDB 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.

$uriOptions = [
    'tls' => true,
    'tlsCertificateKeyFile' => '<file path>',
    'authMechanism' => 'MONGODB-X509',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=<file path>&authMechanism=MONGODB-X509';
$client = new MongoDB\Client($uri);

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 use this method to authenticate, you must specify 'MONGODB-AWS' as the value of the authMechanism connection option.

Note

The MongoDB 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

  2. Environment variables

  3. AWS EKS AssumeRoleWithWebIdentity request

  4. ECS container metadata

  5. EC2 instance metadata

The following sections describe how to retrieve credentials from these sources and use them to authenticate your PHP application.

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.

$uriOptions = [
    'username' => '<AWS IAM access key ID>',
    'password' => '<AWS IAM secret access key>',
    'authMechanism' => 'MONGODB-AWS',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);
$uri = 'mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?authMechanism=MONGODB-AWS';
$client = new MongoDB\Client($uri);

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:

export AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
export AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
export AWS_SESSION_TOKEN=<AWS session token>
AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
AWS_SESSION_TOKEN=<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'.

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.

$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    ['authMechanism' => 'MONGODB-AWS']
);
$uri = 'mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS';
$client = new MongoDB\Client($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.

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 authMechanism example on this page.

Tip

For more information about using an AssumeRoleWithWebIdentity request to authenticate your application, see the following AWS documentation:

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:

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

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 authMechanism example on this page.

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 authMechanism example on this page.

Note

The MongoDB PHP Library retrieves credentials from an EC2 instance only if the environment variables described in the Environment Variables section are not set.

Additional Information

To learn more about creating a MongoDB\Client object in the MongoDB PHP Library, see the Create a MongoDB Client guide.

API Documentation

To learn more about the MongoDB\Client class, see 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 in the extension API documentation.

Back

Secure Your Data

Next

In-Use Encryption