db.auth()

Definition

  • db.auth()
  • Allows a user to authenticate to the database from within theshell.

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

The db.auth() method can accept either:

  • the username and password.
  1. db.auth( <username>, passwordPrompt() )
  2.  
  3. // Or
  4.  
  5. db.auth( <username>, <password> )
  • a user document that contains the username and password, andoptionally, the authentication mechanism and a digest passwordflag.
  1. db.auth( {
  2.    user: <username>,
  3.    pwd: passwordPrompt(),   // Or "<cleartext password>"
  4.    mechanism: <authentication mechanism>,
  5.    digestPassword: <boolean>
  6. } )

ParameterTypeDescriptionusernamestringThe name of the user with access privileges for this database.passwordstringThe 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 canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

mechanismstringOptional. The authentication mechanism to use.

For available mechanisms, see authentication mechanisms.

If unspecified, uses the isMaster to determine the SASLmechanism or mechanisms for the specified user. SeesaslSupportedMechs.digestPasswordbooleanOptional. Determines whether or not the supplied password should be pre-hashedbefore being used with the specified authentication mechanism.

  • For SCRAM-SHA-1, although you mayspecify true, setting this value to true does not improvesecurity 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 authenticationfailure since those methods do not understand MongoDB pre-hashing.The default value is false.

Note

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

Returns:db.auth() returns 0 when authentication isnot 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 marksthe db.auth() for termination (i.e. killOp on theoperation).

Example

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

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

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

Alternatively, you can use the mongo shell’scommand-line options —username,—password,—authenticationDatabase,and —authenticationMechanism to specify authentication credentials whenconnecting the mongo shell:

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