Docs Menu
Docs Home
/ / /
PHP Library Manual

Secure Your Data

On this page

  • Overview
  • Sample Application
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • MONGODB X.509
  • MONGODB-AWS
  • MongoDB\Client Credentials
  • External Credentials

MongoDB supports multiple mechanisms that you can use to authenticate your application. This page contains code examples that demonstrate each of these mechanisms.

Tip

To learn more about any of the mechanisms shown on this page, see the link provided in each section.

To use an authentication example from this page, copy the code example into the sample application or your own application. Make sure to replace all placeholders in the code examples, such as <hostname>, with the relevant values for your MongoDB deployment.

You can use the following sample application to test the code examples on this page. To use the sample application, perform the following steps:

  1. Ensure you have the MongoDB PHP Library installed in your project. To learn more about installing the MongoDB PHP Library, see the Download and Install guide.

  2. Copy the following code and paste it into a new .php file.

  3. Copy a code example from this page and paste it on the specified lines in the file.

1<?php
2
3require __DIR__ . '/../vendor/autoload.php';
4
5// Start example code here
6
7// End example code here
8
9try {
10 $client->test->command(['ping' => 1]);
11 echo 'Successfully pinged the MongoDB server.', PHP_EOL;
12} catch (MongoDB\Driver\Exception\RuntimeException $e) {
13 printf("Failed to ping the MongoDB server: %s\n", $e->getMessage());
14}

The following code shows how to authenticate by using the SCRAM-SHA-256 authentication mechanism:

$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);

To learn more about SCRAM-SHA-256 authentication, see SCRAM-SHA-256 in the Authentication guide.

The following code shows how to authenticate by using the SCRAM-SHA-1 authentication mechanism:

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

To learn more about SCRAM-SHA-1 authentication, see SCRAM-SHA-1 in the Authentication guide.

The following code shows how to create a connection URI to authenticate by using the X.509 authentication mechanism:

$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);

To learn more about X.509 authentication, see MONGODB-X509 in the Authentication guide.

The following sections show how to connect to MongoDB by using the MONGODB-AWS authentication mechanism. When you use the MONGODB-AWS mechanism, the MongoDB PHP Library attempts to retrieve your AWS credentials from the following sources, in the order listed:

  1. Options passed to the MongoDB\Client constructor, either as part of the connection string or the $uriOptions array parameter

  2. Environment variables

  3. AWS EKS AssumeRoleWithWebIdentity request

  4. ECS container metadata

  5. EC2 instance metadata

Each section shows how to authenticate with MONGODB-AWS when retrieving your AWS credentials from options passed to your client or the alternative external sources.

To learn more about authenticating with AWS, see MONGODB-AWS in the Authentication guide.

The following code shows how to pass AWS credentials to the MongoDB\Client constructor to authenticate with MONGODB-AWS:

$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);

To learn more about authenticating with AWS by retrieving MongoDB\Client credentials, see MongoDB\Client Credentials in the Authentication guide.

The following code shows how to authenticate with MONGODB-AWS when obtaining credentials from environment variables, an AssumeRoleWithWebIdentity request, ECS metadata, or EC2 instance metadata:

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

To learn more about authenticating with AWS by obtaining external credentials, see the following sections in the Authentication guide:

Back

Cluster Monitoring