db.auth()¶

On this page

Definition
Behavior
Example

Definition¶

db.auth()¶

Allows a user to authenticate to the database from within the shell.

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

The db.auth() method can accept either:

the username and password.

copy

db.auth( <username>, passwordPrompt() )

// Or

db.auth( <username>, <password> )

a user document that contains the username and password, and optionally, the authentication mechanism and a digest password flag.

copy

db.auth( {
   user: <username>,
   pwd: passwordPrompt(),   // Or "<cleartext password>"
   mechanism: <authentication mechanism>,
   digestPassword: <boolean>
} )

Parameter	Type	Description
`username`	string	The name of the user with access privileges for this database.
`password`	string	The user’s password. The value can be either: the user’s password in cleartext string, or `passwordPrompt()` to prompt for the user’s password. Tip Starting in version 4.2 of the `mongo` shell, you can use the `passwordPrompt()` method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the `mongo` shell.
`mechanism`	string	Optional. The authentication mechanism to use. For available mechanisms, see authentication mechanisms. If unspecified, uses the `isMaster` to determine the SASL mechanism or mechanisms for the specified user. See `saslSupportedMechs`.
`digestPassword`	boolean	Optional. Determines whether or not the supplied password should be pre-hashed before being used with the specified authentication mechanism. For SCRAM-SHA-1, although you may specify `true`, setting this value to `true` does not improve security and may interfere with credentials using other mechanisms. For all other methods, this value must be set to `false` (default value). Any other value will result in authentication failure since those methods do not understand MongoDB pre-hashing. The default value is `false`.

Note

The mongo shell excludes all db.auth() operations from the saved history.

Returns:	`db.auth()` returns `0` when authentication is not successful, and `1` when the operation is successful.

Behavior¶

Client Disconnection¶

Starting in MongoDB 4.2, if the client that issued the db.auth() disconnects before the operation completes, MongoDB marks the db.auth() for termination (i.e. killOp on the operation).

Example¶

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

To authenticate after connecting the mongo shell, issue db.auth() in the user’s authentication database:

copy

use test
db.auth( "myTestDBUser", passwordPrompt() )

Alternatively, you can use the mongo shell’s command-line options --username, --password, --authenticationDatabase, and --authenticationMechanism to specify authentication credentials when connecting the mongo shell:

copy

mongo --username "myTestDBUser" --password --authenticationDatabase test --authenticationMechanism SCRAM-SHA-256

← User Management Methods db.changeUserPassword() →