This version of the documentation is archived and no longer supported.


On this page



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

The db.auth() method can accept either:

  • the username and password.

    db.auth( <username>, <password> )
  • a user document that contains the username and password, and optionally, the authentication mechanism and a digest password flag.

    db.auth( {
       user: <username>,
       pwd: <password>,
       mechanism: <authentication mechanism>,
       digestPassword: <boolean>
    } )
Parameter Type Description
username string Specifies an existing username with access privileges for this database.
password string Specifies the corresponding password.
mechanism string

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

Alternatively, you can use mongo --username, --password, --authenticationDatabase, and --authenticationMechanism to specify authentication credentials.


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.