Introduction MongoDB uses SCRAM-SHA-256 as the default authentication mechanism since version 4.0. Authentication failures occur when credentials are incorrect, the user does not exist in the correct authentication database, the client driver does not support SCRAM-SHA-256, or the mechanism negotiation fails between client and server.

Symptoms - `MongoServerError: Authentication failed` with no further details - `SASL SCRAM-SHA-256 authentication failed for user app_user on admin` - Application cannot connect after password rotation - Connection works with `mongosh` but fails with application driver - `bad auth: Authentication failed.` in MongoDB logs

Common Causes - User created in the wrong authentication database (e.g., `mydb` instead of `admin`) - Password contains special characters not properly escaped in connection string - Old driver version that only supports SCRAM-SHA-1 - `authenticationMechanisms` server configuration does not include SCRAM-SHA-256 - User was dropped or modified during a migration

Step-by-Step Fix 1. **Verify the user exists and check authentication source": ```javascript // Connect as admin user use admin db.getUser("app_user")

// Check which database the user was created in use mydb db.getUser("app_user")

// List all users across databases db.getSiblingDB("admin").getUsers() ```

  1. 1.**Recreate the user with correct credentials":
  2. 2.```javascript
  3. 3.use admin
  4. 4.db.dropUser("app_user")

db.createUser({ user: "app_user", pwd: "MyS3cur3P@ssw0rd!", roles: [ { role: "readWrite", db: "mydb" }, { role: "read", db: "config" } ], mechanisms: ["SCRAM-SHA-256", "SCRAM-SHA-1"] }) ```

  1. 1.**Test the connection with mongosh":
  2. 2.```bash
  3. 3.mongosh "mongodb://app_user:MyS3cur3P%40ssw0rd%21@localhost:27017/mydb?authSource=admin&authMechanism=SCRAM-SHA-256"
  4. 4.`
  5. 5.**Configure the application driver explicitly":
  6. 6.```python
  7. 7.# Python PyMongo
  8. 8.from pymongo import MongoClient

client = MongoClient( "mongodb://app_user:password@host:27017/mydb", authSource="admin", authMechanism="SCRAM-SHA-256" ) client.admin.command("ping") ```

  1. 1.**Check server authentication mechanism configuration":
  2. 2.```javascript
  3. 3.db.adminCommand({ getParameter: 1, authenticationMechanisms: 1 })
  4. 4.// Should return: { authenticationMechanisms: [ "SCRAM-SHA-1", "SCRAM-SHA-256" ] }
  5. 5.`
  6. 6.**Verify connection string URL encoding":
  7. 7.```bash
  8. 8.# Encode special characters in password
  9. 9.python3 -c "import urllib.parse; print(urllib.parse.quote('MyS3cur3P@ssw0rd!'))"
  10. 10.# Output: MyS3cur3P%40ssw0rd%21
  11. 11.`

Prevention - Always specify `authSource` explicitly in connection strings - Test authentication after any user creation or password change - Use a password manager to generate and store MongoDB credentials - Include both `SCRAM-SHA-256` and `SCRAM-SHA-1` mechanisms for driver compatibility - Monitor MongoDB authentication failures in logs with alerting - Rotate credentials using automation that verifies the new credentials before removing old ones - Document the authentication database for each application user