Secure Your Data
On this page
Overview
MongoDB supports multiple mechanisms that you can use to authenticate your application. This page contains code examples that demonstrate each of these mechanisms.
Tip
To learn more about any of the mechanisms shown on this page, see the link provided in each section.
To use an authentication example from this page, copy the code example into the
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.
Sample Application
You can use the following sample application to test the code examples on this page. To use the sample application, perform the following steps:
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.
Copy the following code and paste it into a new
.php
file.Copy a code example from this page and paste it on the specified lines in the file.
1 2 3 require __DIR__ . '/../vendor/autoload.php'; 4 5 // Start example code here 6 7 // End example code here 8 9 try { 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 }
SCRAM-SHA-256
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.
SCRAM-SHA-1
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.
MONGODB X.509
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.
MONGODB-AWS
The following sections show how to connect to MongoDB by using the MONGODB-AWS
authentication mechanism. When you use the MONGODB-AWS
mechanism, the MongoDB PHP Library
attempts to retrieve your AWS credentials from the following sources, in the order listed:
Options passed to the
MongoDB\Client
constructor, either as part of the connection string or the$uriOptions
array parameterEnvironment variables
AWS EKS
AssumeRoleWithWebIdentity
requestECS container metadata
EC2 instance metadata
Each section shows how to authenticate with MONGODB-AWS
when retrieving your
AWS credentials from options passed to your client or the alternative external sources.
To learn more about authenticating with AWS, see MONGODB-AWS in the Authentication guide.
MongoDB\Client Credentials
The following code shows how to pass AWS credentials to the MongoDB\Client
constructor
to authenticate with MONGODB-AWS
:
$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.
External Credentials
The following code shows how to authenticate with MONGODB-AWS
when
obtaining credentials from environment variables, an AssumeRoleWithWebIdentity
request, ECS metadata, or EC2 instance metadata:
$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: