Signatur
Beschreibung
MongoDB\Driver\Exception\AuthenticationException ist eine spezialisierte Ausnahme, die der MongoDB-Treiber wirft, wenn während der Verbindungsherstellung oder bei einem Datenbankbefehl die Authentifizierung scheitert. Typische Ursachen sind falsche Zugangsdaten (Benutzername/Passwort), ein nicht unterstützter oder falsch konfigurierter Authentifizierungsmechanismus (z. B. SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509) oder fehlende Berechtigungen für den angegebenen Authentifizierungs-Datenbankbereich (authSource).
Die Klasse erbt von MongoDB\Driver\Exception\ConnectionException und letztlich von MongoDB\Driver\Exception\RuntimeException, die ihrerseits \RuntimeException erweitert und das Interface MongoDB\Driver\Exception\Exception implementiert. In der Ausnahme-Hierarchie lässt sie sich also sowohl als ConnectionException als auch als generische \Exception abfangen.
Diese Ausnahme sollte gezielt in catch-Blöcken behandelt werden, um dem Anwender oder dem Logging-System eine aussagekräftige Fehlermeldung zu liefern, ohne interne Zugangsdaten preiszugeben. Sensible Verbindungsparameter wie Passwörter sollten niemals im Klartext in Fehlermeldungen oder Logs ausgegeben werden.
Da sie eine Unterklasse von ConnectionException ist, tritt sie typischerweise beim Aufbau eines MongoDB\Driver\Manager-Objekts oder beim erstmaligen Ausführen eines Befehls auf, wenn der Treiber die Verbindung zum Server herstellt und dabei die Authentifizierung durchführt.
Beispiele
Authentifizierungsfehler abfangen und behandeln
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Command;
use MongoDB\Driver\Exception\AuthenticationException;
use MongoDB\Driver\Exception\ConnectionException;
$uri = 'mongodb://falscherBenutzer:falschesPasswort@127.0.0.1:27017/?authSource=admin';
try {
$manager = new Manager($uri);
// Befehl auslösen, damit die Verbindung tatsächlich hergestellt wird
$command = new Command(['ping' => 1]);
$manager->executeCommand('admin', $command);
echo "Verbindung erfolgreich." . PHP_EOL;
} catch (AuthenticationException $e) {
// Spezifisch: Authentifizierung fehlgeschlagen
echo "Authentifizierung fehlgeschlagen: " . $e->getMessage() . PHP_EOL;
// Fehlercode des Treibers ausgeben
echo "Fehlercode: " . $e->getCode() . PHP_EOL;
} catch (ConnectionException $e) {
// Allgemeiner Verbindungsfehler
echo "Verbindungsfehler: " . $e->getMessage() . PHP_EOL;
} catch (\Exception $e) {
echo "Unbekannter Fehler: " . $e->getMessage() . PHP_EOL;
}Fehler-Hierarchie nutzen und sicher loggen
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Command;
use MongoDB\Driver\Exception\AuthenticationException;
function createMongoManager(string $host, string $user, string $password, string $authDb = 'admin'): Manager
{
// Passwort wird URL-kodiert, nie im Klartext geloggt
$encodedUser = urlencode($user);
$encodedPass = urlencode($password);
$uri = "mongodb://{$encodedUser}:{$encodedPass}@{$host}/?authSource={$authDb}";
try {
$manager = new Manager($uri);
// Verbindung testen
$manager->executeCommand($authDb, new Command(['ping' => 1]));
return $manager;
} catch (AuthenticationException $e) {
// Kein Passwort im Log!
error_log(sprintf(
'[MongoDB] Authentifizierung für Benutzer "%s" auf "%s" fehlgeschlagen. Code: %d',
$user,
$host,
$e->getCode()
));
throw new \RuntimeException('Datenbankverbindung konnte nicht hergestellt werden.', 0, $e);
}
}
try {
$manager = createMongoManager('127.0.0.1:27017', 'admin', 'geheim123');
echo "Verbunden!" . PHP_EOL;
} catch (\RuntimeException $e) {
echo "Fehler: " . $e->getMessage() . PHP_EOL;
// Ursprüngliche Ausnahme erreichbar:
$previous = $e->getPrevious();
if ($previous instanceof AuthenticationException) {
echo "Ursprung: " . get_class($previous) . PHP_EOL;
}
}// Wichtig · Fallstricke
Sicherheitshinweis: Niemals den vollständigen Verbindungs-URI (inklusive Passwort) in Fehlermeldungen, Logs oder Stacktraces ausgeben. Die Ausnahme selbst enthält keine Zugangsdaten, aber ein unbedacht geloggter URI schon.
Lazy Connection: Der MongoDB\Driver\Manager-Konstruktor stellt die Verbindung nicht sofort her. Die AuthenticationException wird häufig erst beim ersten tatsächlichen Befehl geworfen. Daher empfiehlt sich ein früher ping-Befehl, um Authentifizierungsfehler beim Anwendungsstart sofort zu erkennen.
Mechanismus-Probleme: Bei X.509- oder Kerberos-Authentifizierung kann diese Ausnahme auch auf Zertifikats- oder Ticket-Probleme hinweisen, nicht nur auf falsche Passwörter. Die getMessage()-Ausgabe enthält in der Regel einen Hinweis des MongoDB-Servers.