Dépannage des erreurs d'authentification SCRAM courantes dans MongoDB

La configuration de la sécurité dans MongoDB est cruciale pour protéger les données sensibles. Les déploiements MongoDB modernes reposent fortement sur SCRAM (Salted Challenge Response Authentication Mechanism) pour une authentification sécurisée basée sur un mot de passe. Cependant, la mise en œuvre et la gestion de SCRAM peuvent parfois entraîner des erreurs de connexion frustrantes et des refus d'accès.

Ce guide sert de manuel pratique de dépannage pour identifier et résoudre les problèmes les plus fréquents rencontrés lors de la configuration ou de l'utilisation de l'authentification SCRAM dans MongoDB. En comprenant les pièges courants liés à la création d'utilisateurs, à l'attribution de rôles et à la configuration du client, vous pouvez rapidement rétablir un accès sécurisé à la base de données.

Comprendre SCRAM dans MongoDB

SCRAM est le mécanisme d'authentification par défi-réponse basé sur un mot de passe de MongoDB. MongoDB prend en charge SCRAM-SHA-1 depuis longtemps, et les déploiements modernes utilisent couramment SCRAM-SHA-256 lorsque le serveur et le client le prennent en charge. Le point de dépannage utile est simple : le client prouve qu'il connaît le mot de passe sans envoyer le mot de passe en clair directement au serveur.

Lors du dépannage, rappelez-vous que les échecs d'authentification proviennent généralement de l'un des trois domaines suivants : Configuration du serveur, Définition de l'utilisateur ou Syntaxe de connexion du client.

Catégorie d'erreur courante 1 : Connexion refusée ou échec d'authentification (côté client)

C'est le symptôme le plus courant : les clients ne peuvent pas se connecter, ce qui entraîne souvent des messages comme Authentication failed. ou Connection refused lorsque l'authentification est strictement appliquée.

1. Mécanisme d'authentification incorrect spécifié

Si votre déploiement MongoDB nécessite SCRAM, mais que le client essaie d'utiliser un mécanisme plus ancien ou non pris en charge (comme MONGODB-CR), la connexion échouera immédiatement.

Solution : Assurez-vous que votre chaîne de connexion ou la configuration de votre pilote demande explicitement SCRAM.

Pour les clients prenant en charge les pilotes modernes, la chaîne de connexion spécifie souvent le mécanisme d'authentification (authMechanism). Pour les déploiements modernes utilisant SCRAM-SHA-256 (recommandé) :

mongodb://user:password@host:27017/dbname?authSource=admin&authMechanism=SCRAM-SHA-256

Astuce : Si vous omettez authMechanism sur un serveur configuré uniquement pour SCRAM, le pilote devrait utiliser la valeur par défaut correcte, mais le définir explicitement élimine toute ambiguïté.

2. Utilisation du mauvais `authSource`

Dans MongoDB, le paramètre authSource spécifie la base de données où le compte utilisateur est défini. Si votre utilisateur existe dans la base de données admin, mais que vous vous connectez en spécifiant authSource=myappdb, le serveur ne peut pas trouver les informations d'identification.

Exemple de scénario : L'utilisateur app_user a été créé dans la base de données admin.

Connexion incorrecte :

mongodb://app_user:password@localhost:27017/myappdb?authSource=myappdb

Connexion correcte :

mongodb://app_user:password@localhost:27017/myappdb?authSource=admin

3. Problèmes de réseau ou de liaison masquant les échecs d'authentification

Parfois, un problème de connexion ressemble à un échec d'authentification alors qu'il s'agit en réalité d'un problème de liaison réseau. Si l'instance mongod est uniquement liée à 127.0.0.1 (localhost), les clients distants recevront un refus de connexion avant même de tenter l'authentification.

Action : Vérifiez que net.bindIp dans votre mongod.conf autorise les connexions depuis l'adresse IP du client (par exemple, 0.0.0.0 pour toutes les interfaces, ou des IP spécifiques).

Catégorie d'erreur courante 2 : Erreurs de création d'utilisateur et d'attribution de rôles

Les échecs d'authentification sont souvent enracinés dans la façon dont l'utilisateur a été créé ou les privilèges qui lui ont été attribués.

1. Utilisateur créé sans mot de passe (ou format incorrect)

Si vous tentez de créer un utilisateur à l'aide du shell mongosh ou mongo sans fournir un mot de passe valide, le processus de création peut échouer silencieusement ou aboutir à un utilisateur qui ne peut pas s'authentifier avec succès via SCRAM.

Meilleure pratique pour la création : Spécifiez toujours un mot de passe fort et assurez-vous d'utiliser le mécanisme SCRAM recommandé lors de la création de l'utilisateur.

// Se connecter d'abord en tant qu'utilisateur admin
use admin

// Créer un utilisateur avec SCRAM-SHA-256 (recommandé)
db.createUser(
  {
    user: "reader_role",
    pwd: passwordPrompt(), // Demander le mot de passe de manière sécurisée
    roles: [ { role: "read", db: "mydatabase" } ]
  }
)

2. Rôles manquants ou incorrects

Une source courante de confusion est de se connecter avec succès mais de constater que l'utilisateur ne peut pas effectuer l'opération souhaitée (par exemple, ne peut pas lire les données, ne peut pas écrire). Ce n'est pas un échec d'authentification, mais un échec d'autorisation, qui se présente souvent de la même manière pour l'utilisateur final.

Dépannage de l'autorisation :

Vérifier l'attribution des rôles : Utilisez show users dans la base de données correcte (authSource) pour confirmer que l'utilisateur existe et possède les rôles attendus.
Vérifier les rôles hérités : Si vous utilisez des rôles personnalisés, assurez-vous qu'ils héritent correctement des rôles intégrés nécessaires (comme read ou readWrite).
Contexte de connexion : N'oubliez pas que les rôles ne sont valides que sur la base de données spécifiée lors de la création (ou la base de données admin pour les rôles au niveau du cluster).

Si un utilisateur essaie de lire depuis dbA mais n'a que des rôles sur dbB, l'opération échouera.

3. Incompatibilité de version SCRAM lors de la mise à niveau

Lors de la mise à niveau de MongoDB, les anciens utilisateurs peuvent encore être mappés à l'aide du mécanisme hérité MONGODB-CR. Si le serveur est configuré pour n'accepter que SCRAM-SHA-256, ces anciens utilisateurs ne pourront pas se connecter.

Résolution : Vous devez explicitement mettre à jour la méthode d'authentification pour l'utilisateur existant après avoir mis à niveau la configuration du serveur.

Utilisez la commande changePassword, qui force un nouveau hachage en utilisant les valeurs par défaut actuelles du serveur :

// Mettre à jour le mot de passe de l'utilisateur, en mettant implicitement à jour le mécanisme si nécessaire
db.changePassword(
  "old_user",
  "new_secure_password",
  { authenticationDatabase: "admin" }
)

Catégorie d'erreur courante 3 : Problèmes de configuration du serveur

Si plusieurs clients ne parviennent pas à se connecter, le problème réside probablement dans le fichier de configuration mongod.conf.

1. Authentification non activée

Si l'authentification est complètement désactivée, les clients se connectant sans informations d'identification peuvent réussir, ou ils peuvent être bloqués de manière inattendue si le client tente de s'authentifier quand même. Inversement, si l'authentification est requise, mais que la configuration est incorrecte, les connexions échouent.

Assurez-vous que la section de sécurité dans mongod.conf est correctement définie :

security:
  authorization: enabled

2. Liaison à une interface incorrecte

Comme mentionné précédemment, si net.bindIp est trop restrictif, les clients externes ne peuvent pas atteindre le service d'authentification.

Exemple dans mongod.conf :

Accès local uniquement : bindIp: 127.0.0.1 (Échoue les connexions distantes)
Recommandé pour le cloud/réseau interne : bindIp: 0.0.0.0 (Autorise les connexions depuis n'importe quelle interface, mais nécessite des règles de pare-feu strictes)

3. Spécification excessive des paramètres d'authentification

Certaines pannes d'authentification proviennent d'une tentative d'être trop explicite. Un URI qui force SCRAM-SHA-256 peut casser un ancien pilote ou un utilisateur dont les informations d'identification ont été créées avant que ce mécanisme ne soit disponible. Un fichier de déploiement copié d'un autre environnement peut également inclure des paramètres qui ne correspondent pas à ce cluster.

Commencez par la chaîne de connexion la plus simple qui fonctionne, puis ajoutez des options uniquement lorsque vous savez pourquoi elles sont nécessaires. Si une session mongosh actuelle fonctionne mais que l'application échoue, comparez les versions des pilotes et les options URI avant de modifier les utilisateurs côté serveur.

Un chemin de débogage pratique que j'utilise en premier

Lorsqu'une erreur SCRAM vous tombe dessus, résistez à l'envie de changer trois choses à la fois. Commencez par le plus petit test de connexion que vous pouvez exécuter depuis le même réseau que l'application. Si l'application s'exécute dans Kubernetes, exécutez-vous dans un pod de débogage temporaire ou le pod de l'application lui-même. Si elle s'exécute sur une instance EC2, testez depuis cette instance, pas depuis votre ordinateur portable.

mongosh "mongodb://[email protected]:27017/myappdb?authSource=admin" --password

Si cela échoue avec une erreur réseau, le mot de passe n'est probablement pas encore pertinent. Vérifiez le DNS, les règles de pare-feu, les noms de service, les mappages de ports, les groupes de sécurité et net.bindIp. Si cela atteint le serveur et échoue avec Authentication failed, passez ensuite à l'emplacement de l'utilisateur et aux informations d'identification.

La prochaine chose que je vérifie est l'endroit où l'utilisateur existe réellement. Cela permet de détecter un nombre surprenant d'incidents :

use admin
db.getUser("app_user")

use myappdb
db.getUser("app_user")

Un utilisateur créé dans admin doit s'authentifier avec authSource=admin. Un utilisateur créé dans myappdb doit s'authentifier avec authSource=myappdb. Le chemin de la base de données dans l'URI, comme /myappdb, est la base de données par défaut que le client souhaite utiliser. Ce n'est pas automatiquement la base de données qui stocke les informations d'identification de connexion.

Après cela, séparez l'authentification de l'autorisation. Une connexion réussie prouve seulement que le nom d'utilisateur et le mot de passe sont acceptés. Cela ne prouve pas que l'utilisateur peut lire, écrire, créer des index ou exécuter des commandes administratives. Effectuez d'abord une vérification inoffensive :

db.runCommand({ connectionStatus: 1 })

Ensuite, essayez l'opération exacte dont le service a besoin :

use myappdb
db.orders.findOne()

Si la deuxième commande échoue avec une erreur de permissions, ne faites pas pivoter le mot de passe. Accordez le rôle restreint dont l'application a besoin. Un service de reporting a généralement besoin de read, une application normale a souvent besoin de readWrite sur une base de données, et un outil de migration peut avoir besoin de privilèges temporaires plus larges. Évitez d'accorder root ou des rôles à l'échelle du cluster simplement pour faire disparaître une erreur.

use myappdb
db.grantRolesToUser("app_user", [
  { role: "readWrite", db: "myappdb" }
])

Vérifiez également les aspects ennuyeux de la gestion des secrets. Les mots de passe avec @, /, ?, # ou : peuvent casser un URI MongoDB s'ils ne sont pas encodés en pourcentage. Les variables d'environnement copiées à partir de fichiers peuvent contenir des sauts de ligne de fin. Les secrets Kubernetes peuvent être mis à jour tandis que les anciens pods fonctionnent encore avec d'anciennes valeurs. Dans ces cas, la configuration MongoDB est correcte ; l'application n'envoie tout simplement pas le mot de passe que vous pensez qu'elle envoie.

Le comportement du pilote compte aussi. La plupart des pilotes MongoDB actuels négocient SCRAM automatiquement. Si vous forcez explicitement authMechanism=SCRAM-SHA-256, assurez-vous que le pilote et les informations d'identification stockées de l'utilisateur le prennent en charge. Lors des mises à niveau, testez avec mongosh et avec le pilote réel de l'application. Si le shell fonctionne et que l'application échoue, comparez les versions des pilotes et les options URI avant de modifier les utilisateurs côté serveur.

MongoDB géré ajoute un piège supplémentaire : les règles d'accès réseau du fournisseur. Dans MongoDB Atlas, par exemple, un utilisateur de base de données valide ne peut toujours pas se connecter depuis une adresse IP qui n'est pas autorisée par les paramètres réseau du projet. Dans les journaux de l'application, cela peut ressembler à un problème de connexion ou d'authentification, mais la correction se trouve dans la liste d'accès du fournisseur ou la configuration de la mise en réseau privée.

Le rythme de dépannage le plus sûr est : prouvez la joignabilité du réseau, prouvez que l'utilisateur existe dans le authSource, prouvez que le mot de passe fonctionne dans un shell, prouvez que le rôle permet l'opération, puis comparez la chaîne de connexion finale du pilote de l'application. Cet ordre vous évite de transformer une correction d'URI en une seule ligne en une rotation complète des informations d'identification.

Lire le message d'erreur sans lui faire trop confiance

Les erreurs du client MongoDB sont utiles, mais elles ne sont pas toujours formulées au niveau dont vous avez besoin. Authentication failed est suffisamment spécifique pour vous dire que le serveur a rejeté les informations d'identification, mais pas toujours suffisamment spécifique pour vous dire si le nom d'utilisateur est erroné, le mot de passe est erroné, le authSource est erroné ou la négociation du mécanisme a échoué. MongoServerSelectionError peut pointer vers l'authentification dans un journal d'application même lorsque le pilote n'a jamais trouvé de serveur approprié.

Une bonne ligne de journal de l'application doit inclure l'hôte nettoyé, le nom de la base de données, la source d'authentification, le nom du jeu de réplicas s'il est utilisé, et le délai d'attente du pilote. Elle ne doit pas inclure le mot de passe. Si vos journaux disent seulement "Mongo connection failed", améliorez cela avant le prochain incident. La différence entre authSource=admin et authSource=app est trop importante pour être cachée.

Pour les jeux de réplicas, confirmez également que les noms d'hôte que MongoDB annonce sont joignables depuis le client. Une surprise courante lors du passage du local à la production est que l'hôte de départ est joignable, mais que le jeu de réplicas renvoie des noms internes que le client ne peut pas résoudre. Le pilote échoue alors à la sélection du serveur, et l'équipe recherche les informations d'identification parce que la première commande shell manuelle a fonctionné contre un nœud. Utilisez rs.status() et comparez les noms des membres avec ce que le réseau de l'application peut résoudre.

rs.status().members.map(m => m.name)

Si ces noms sont des noms DNS privés, l'application doit s'exécuter à l'intérieur de ce réseau privé ou utiliser une méthode de connexion qui les résout correctement. Ne masquez pas cela en vous connectant directement à un secondaire ou à un seul nœud, sauf si vous comprenez les conséquences du basculement.

Corrections sûres lors d'un incident

Si vous devez rétablir rapidement le service, choisissez des correctifs qui n'élargissent pas l'accès plus que nécessaire. Recréer l'utilisateur de l'application avec les mêmes rôles peut être plus sûr que de modifier plusieurs paramètres non liés. Faire pivoter le mot de passe est raisonnable si vous soupçonnez une dérive des secrets, mais coordonnez-le avec le déploiement de l'application afin que les anciens pods ne continuent pas à réessayer avec des informations d'identification obsolètes et ne remplissent pas les journaux.

Évitez de désactiver l'authentification comme raccourci de dépannage. Cela modifie la posture de sécurité de l'ensemble du déploiement et peut cacher la cause originale. Si vous avez besoin d'un chemin d'accès d'urgence, créez un utilisateur administrateur temporaire via l'exception localhost uniquement lorsque vous êtes dans l'état de configuration initiale et que MongoDB le permet, ou utilisez le processus de récupération documenté de votre fournisseur géré. Dans les déploiements établis, utilisez un accès administratif audité.

Après le correctif, notez la cause exacte en langage clair : "l'utilisateur existait dans admin, l'application utilisait authSource=orders" est bien mieux que "problème d'authentification Mongo." Cette note empêche la même panne de revenir lors de la prochaine reconstruction de l'environnement.

Liste de contrôle récapitulative pour les échecs d'authentification SCRAM

Lors du dépannage, parcourez cette séquence :

État du serveur : security.authorization est-il activé dans mongod.conf ?
Vérification réseau : Le client peut-il atteindre l'IP et le port du serveur (utilisez netstat ou telnet) ?
URI du client : authMechanism=SCRAM-SHA-256 est-il spécifié (si nécessaire) ?
authSource : Le authSource correspond-il à la base de données où l'utilisateur a été créé ?
Existence de l'utilisateur : L'utilisateur existe-t-il dans la base de données authSource spécifiée ?
Mot de passe/Rôles : Le mot de passe est-il correct, et l'utilisateur possède-t-il les rôles minimum requis pour l'action prévue ?

En vérifiant méthodiquement ces points de configuration, la plupart des erreurs d'authentification SCRAM dans MongoDB peuvent être rapidement isolées et résolues.