SCRAM Authentication Mechanisms

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 MongoDB Server version 4.0 and later. SCRAM-SHA-1, which uses the SHA-1 algorithm instead, is the default authentication mechanism in MongoDB Server versions earlier than 4.0.

You can use SCRAM to authenticate to MongoDB Atlas, MongoDB Enterprise Advanced, and MongoDB Community Edition.

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 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.

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 MongoDB\Client or Connection URI tab to see the corresponding code:

$uriOptions = [
    'username' => '<username>',
    'password' => '<password>',
    'authSource' => '<authentication database>',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);

$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin';
$client = new MongoDB\Client($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:

$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 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 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-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 MongoDB\Client or Connection URI tab to see the corresponding code:

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

Additional Information

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

To learn more about connection options, see the Specify Connection Options guide.