Docs Home → Develop Applications → MongoDB Manual
db.auth()![](/docs/v6.3/assets/link.svg)
On this page
Definition![](/docs/v6.3/assets/link.svg)
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 thepasswordPrompt()
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 themongo
shell.Starting in MongoDB 4.4, if you use the
db.auth(<username>, <password>)
syntax and omit the password, the user is prompted to enter a password.
Syntax![](/docs/v6.3/assets/link.svg)
The db.auth()
has the following syntax forms:
db.auth(<username>, <password>)
![](/docs/v6.3/assets/link.svg)
db.auth(<user document>)
![](/docs/v6.3/assets/link.svg)
db.auth( { user: <username>, pwd: passwordPrompt(), // Or "<cleartext password>" mechanism: <authentication mechanism>, digestPassword: <boolean> } )
Parameter | Type | Description |
---|---|---|
user | string | The name of the user with access privileges for this database. |
pwd | string | The user's password. The value can be either:
TipStarting in version 4.2 of the When using the user document syntax, you cannot omit the
|
mechanism | string | Optional. The authentication mechanism to use. For available mechanisms, see authentication mechanisms. If unspecified, uses the |
digestPassword | boolean | Optional. Determines whether or not the supplied password should be pre-hashed before being used with the specified authentication mechanism.
The default value is |
- Returns
db.auth()
returns0
when authentication is not successful, and1
when the operation is successful.
Behavior![](/docs/v6.3/assets/link.svg)
Client Disconnection![](/docs/v6.3/assets/link.svg)
Starting in MongoDB 4.2, if the client that issued db.auth()
disconnects before the operation completes, MongoDB marks db.auth()
for termination using killOp
.
Example![](/docs/v6.3/assets/link.svg)
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.
Starting in MongoDB 4.4, if you use the
db.auth(<username>, <password>)
syntax and omit the password,
the user is prompted to enter a password.
Authenticate after Connecting to the Shell![](/docs/v6.3/assets/link.svg)
To authenticate after connecting mongosh
, issue
db.auth()
in the user's authentication database:
use test db.auth( "myTestDBUser", passwordPrompt() )
Starting in MongoDB 4.4, you can omit the password
value entirely to
prompt the user to enter their password:
use test db.auth( "myTestDBUser" )
Starting in MongoDB 5.0, if your connection specifies the
--apiStrict
option, you may not use the db.auth()
method to:
Authenticate again as the same user on the same database.
Authenticate as a different user when previously authenticated on the same database.
Authenticate with a new database when previously authenticated on a different database.
Authenticate when Connecting to the Shell![](/docs/v6.3/assets/link.svg)
Alternatively, you can use mongosh
's
command-line options --username
,
--password
,
--authenticationDatabase
,
and --authenticationMechanism
to specify authentication credentials when
connecting mongosh
:
mongosh --username "myTestDBUser" --password --authenticationDatabase test --authenticationMechanism SCRAM-SHA-256