Skip to main content

Diagnostiquer et corriger une authentification OIDC dans Medulla

S'applique à : Medulla Server
Environnement : On-Premise / Authentification SSO OpenID Connect (OIDC)
Annuaires : Active Directory, OpenLDAP, FreeIPA, 389 Directory Server et autres annuaires LDAP compatibles avec le fournisseur d'identité
Fournisseurs OIDC : LemonLDAP::NG, Keycloak, Microsoft Entra ID, Authentik, Okta et autres fournisseurs OIDC compatibles
Outil : test_oidc_medulla.sh
Catégorie : Authentification / SSO / Diagnostic
Mise à jour : Novembre 2026

1. Présentation

Medulla peut utiliser un fournisseur d'identité externe (Identity Provider ou IdP) pour authentifier les utilisateurs avec le protocole OpenID Connect (OIDC).

Cette configuration permet de centraliser l'authentification des utilisateurs et d'utiliser un système SSO existant.

Le fournisseur d'identité peut lui-même s'appuyer sur différents systèmes d'annuaire :

  • Microsoft Active Directory.
  • OpenLDAP.
  • FreeIPA.
  • 389 Directory Server.
  • Un annuaire LDAP ou LDAPS compatible.
  • Un service d'identité fédéré ou un annuaire cloud.

Medulla n'a pas besoin de connaître directement la structure de l'annuaire lorsque l'authentification passe par OIDC. Le fournisseur d'identité est chargé d'authentifier l'utilisateur et de transmettre à Medulla les informations nécessaires.

Important : LDAP et OIDC sont deux protocoles distincts. Le script présenté ici diagnostique une connexion OIDC. Il ne remplace pas un outil de diagnostic LDAP ou LDAPS direct. Pour un annuaire LDAP, un fournisseur d'identité assurant la passerelle vers OIDC est nécessaire.

2. Comprendre le fonctionnement de l'authentification

2.1. Architecture générale

Utilisateur
    |
    v
Interface Web Medulla
    |
    | Redirection OIDC
    v
Fournisseur d'identité (IdP)
    |
    | Authentification
    v
Annuaire ou service d'identité
    |
    | Validation de l'utilisateur
    v
Fournisseur d'identité
    |
    | Authorization Code
    v
Medulla
    |
    | Token Endpoint
    | UserInfo Endpoint
    v
Provisionnement du compte
    |
    v
Application des droits Medulla

Le fournisseur d'identité peut authentifier l'utilisateur avec un mot de passe, une session SSO existante, une authentification multifacteur ou tout autre mécanisme qu'il prend en charge.

Une fois l'authentification acceptée, Medulla récupère les informations de l'utilisateur au moyen du protocole OIDC.

2.2. Répartition des responsabilités

Composant Responsabilité
Annuaire LDAP / Active Directory Stockage et gestion des comptes, attributs et groupes selon l'architecture retenue.
Fournisseur d'identité Authentification, règles d'accès, MFA et émission des informations OIDC.
Medulla Réception du retour OIDC, récupération des attributs, provisionnement du compte et application des ACL.

3. Présentation de l'outil de diagnostic

Le script test_oidc_medulla.sh analyse la configuration OIDC de Medulla et vérifie les principaux éléments nécessaires à son fonctionnement.

Il permet notamment de contrôler :

  • La configuration du fournisseur OIDC.
  • La résolution DNS et les communications HTTPS.
  • Les certificats TLS.
  • Le document de découverte OIDC.
  • Les endpoints d'autorisation, de jetons et d'informations utilisateur.
  • Le Client ID et le Client Secret.
  • La Redirect URI.
  • Les claims nécessaires à Medulla.
  • La configuration du provisionnement et des ACL.
  • Les erreurs présentes dans les journaux Medulla.

Un test optionnel avec un compte utilisateur permet également de reproduire une partie du parcours d'authentification complet.

Fonctionnement : le script lit la configuration Medulla et effectue des requêtes de diagnostic. Il ne modifie pas les paramètres de Medulla et ne crée aucun compte utilisateur.

4. Prérequis

Le script doit être exécuté directement sur le serveur Medulla avec des privilèges suffisants pour consulter sa configuration et sa base de données.

Les outils nécessaires sont :

  • bash
  • curl
  • jq
  • openssl
  • python3
  • mysql

Sur Debian :

apt update
apt install -y curl jq openssl python3 default-mysql-client

Le serveur doit pouvoir joindre le fournisseur d'identité par HTTPS, directement ou au travers du proxy déclaré dans la configuration OIDC de Medulla.

5. Télécharger et installer le script

Le script est disponible sur le serveur officiel de téléchargement Medulla :

Télécharger test_oidc_medulla.sh

Se connecter au serveur Medulla en SSH, puis exécuter :

cd /root
wget https://dl.medulla-tech.io/ma/test_oidc_medulla.sh
chmod +x test_oidc_medulla.sh
bash -n test_oidc_medulla.sh

La commande bash -n vérifie la syntaxe Bash du script sans l'exécuter.

6. Identifier les fournisseurs OIDC configurés

Pour afficher les fournisseurs enregistrés dans Medulla :

sudo ./test_oidc_medulla.sh

Le script interroge la table admin.providers et affiche :

  • Le nom du client Medulla (client_name).
  • Le nom du fournisseur OIDC.
  • L'Issuer URL.
  • Le Client ID.

Le nom exact du fournisseur doit être utilisé dans les commandes suivantes.

7. Exécuter un diagnostic

7.1. Diagnostic sans compte utilisateur

sudo ./test_oidc_medulla.sh "OIDC"

Au démarrage, le script propose de saisir un identifiant utilisateur.

Appuyer sur Entrée sans saisir d'identifiant pour effectuer uniquement les contrôles techniques.

Ce mode permet de vérifier la configuration OIDC, les certificats, le réseau, les endpoints et les paramètres Medulla.

7.2. Diagnostic avec un compte utilisateur

sudo ./test_oidc_medulla.sh -u utilisateur.test "OIDC"

Le script demande le mot de passe du compte sans l'afficher à l'écran.

Il tente ensuite de reproduire les étapes suivantes :

  1. Accès au fournisseur d'identité.
  2. Chargement du formulaire de connexion.
  3. Envoi des identifiants.
  4. Application des règles d'accès du fournisseur.
  5. Retour vers la Redirect URI de Medulla.
  6. Échange du code d'autorisation contre un jeton.
  7. Interrogation du endpoint userinfo.
  8. Contrôle des attributs reçus.
  9. Simulation du provisionnement et des ACL Medulla.

Limite : le script ne prend pas en charge tous les mécanismes d'authentification interactifs. Une authentification MFA, un consentement utilisateur, un portail JavaScript complexe ou une authentification intégrée Kerberos peuvent nécessiter un test complémentaire dans un navigateur.

7.3. Sélectionner un client Medulla

sudo ./test_oidc_medulla.sh -c MMC "OIDC"

Le paramètre -c permet de sélectionner le client_name. La valeur par défaut est MMC.

7.4. Paramètres disponibles

Paramètre Description
-c Nom du client Medulla, par défaut MMC.
-u Login du compte utilisé pour le test réel.
-h Affiche les informations d'utilisation du script.
OIDC_TEST_PASSWORD Variable d'environnement permettant de fournir le mot de passe sans saisie interactive.

Sécurité : privilégier la saisie interactive du mot de passe. Éviter de placer des mots de passe en clair dans des commandes, scripts ou historiques de shell.

8. Comprendre les résultats

Statut Signification Action recommandée
OK Contrôle réussi. Aucune correction nécessaire pour le point vérifié.
WARN Avertissement ou vérification complémentaire nécessaire. Examiner la recommandation.
KO Erreur détectée. Appliquer la correction indiquée.

En fin d'exécution, le script affiche une synthèse des contrôles et une liste des corrections recommandées.

Important : un résultat sans KO ne garantit pas que tous les utilisateurs peuvent se connecter. Les règles d'accès du fournisseur et les attributs réellement transmis doivent être vérifiés avec un compte autorisé.

9. Vérifications réalisées par le script

9.1. Configuration Medulla

Le script consulte la table admin.providers et les fichiers :

/etc/mmc/mmc.ini
/etc/mmc/mmc.ini.local
/etc/mmc/plugins/base.ini
/etc/mmc/plugins/base.ini.local

Il vérifie notamment :

  • L'Issuer URL.
  • Le Client ID et le Client Secret.
  • Le proxy éventuel.
  • Les correspondances des claims OIDC.
  • Les ACL par défaut.
  • Les correspondances entre rôles et ACL.
  • La Redirect URI.
  • La méthode de provisionnement OIDC.

9.2. Réseau et certificats

Le script contrôle :

  • La résolution DNS du fournisseur d'identité.
  • La connectivité HTTPS.
  • La chaîne de confiance TLS.
  • La validité du certificat.
  • La correspondance du certificat avec le nom DNS.
  • La connectivité depuis PHP/cURL.
  • La synchronisation de l'horloge.

9.3. Découverte OIDC

Le document de découverte OIDC est généralement accessible à l'adresse suivante :

https://idp.exemple.fr/.well-known/openid-configuration

Le script vérifie :

  • La cohérence de l'issuer.
  • La disponibilité des endpoints.
  • La prise en charge du flux Authorization Code.
  • Les scopes annoncés.
  • Les claims annoncés.
  • La disponibilité du document JWKS.

9.4. Client ID et Client Secret

Le script teste les méthodes d'authentification du client :

  • client_secret_basic
  • client_secret_post

Il envoie un code d'autorisation volontairement invalide au token endpoint.

Une réponse invalid_grant peut indiquer que l'authentification du client a été acceptée et que seul le code d'autorisation a été refusé, conformément au comportement attendu.

Une réponse invalid_client ou unauthorized_client nécessite une vérification du client OIDC et de sa méthode d'authentification.

10. Compatibilité avec les annuaires LDAP

La compatibilité avec un annuaire dépend principalement du fournisseur d'identité utilisé et de sa capacité à transmettre les attributs nécessaires au protocole OIDC.

Annuaire ou système d'identité Utilisation avec Medulla OIDC Point d'attention
Microsoft Active Directory Via un fournisseur OIDC connecté à Active Directory. Correspondance entre sAMAccountName, UPN et identifiant OIDC.
OpenLDAP Via un fournisseur OIDC connecté à OpenLDAP. Mapping des attributs uid, cn, givenName, sn et mail.
FreeIPA Via un fournisseur OIDC compatible avec l'annuaire FreeIPA. Identifiant stable, groupes et attributs exportés.
389 Directory Server Via un fournisseur OIDC connecté à l'annuaire. Correspondance des attributs LDAP avec les claims OIDC.
Microsoft Entra ID Via le protocole OIDC. Disponibilité des claims dans userinfo et configuration du client.
Autres annuaires LDAP Via un fournisseur d'identité assurant la fédération OIDC. Compatibilité du fournisseur et mapping des attributs.

Principe : Medulla consomme les claims OIDC transmis par le fournisseur d'identité. Les noms des attributs LDAP peuvent varier selon l'annuaire sans nécessiter de modification du protocole OIDC utilisé par Medulla.

11. Correspondance des attributs LDAP et OIDC

Le fournisseur d'identité doit transmettre les informations nécessaires à l'identification et au provisionnement des comptes Medulla.

Attribut Medulla Claim OIDC par défaut Exemples de sources LDAP
uid preferred_username uid, sAMAccountName, userPrincipalName ou identifiant stable.
givenName given_name givenName.
sn family_name sn.
mail email mail ou adresse électronique définie dans l'annuaire.

Les correspondances peuvent être personnalisées dans :

Administration → Authentication Configuration → OIDC → Edit

11.1. Exemple avec Active Directory

Un fournisseur d'identité connecté à Active Directory peut utiliser les correspondances suivantes :

Attribut Active Directory Claim OIDC
sAMAccountName preferred_username
givenName given_name
sn family_name
mail email

Ces correspondances sont des exemples. Leur disponibilité dépend de la configuration du fournisseur OIDC.

11.2. Exemple avec OpenLDAP

Attribut OpenLDAP Claim OIDC
uid preferred_username
givenName given_name
sn family_name
mail email

11.3. Choisir un identifiant stable

Il est recommandé d'utiliser un identifiant qui ne change pas pendant la durée de vie du compte.

Une adresse électronique peut être utilisée, mais un changement d'adresse risque de provoquer la création d'un second compte Medulla si elle sert d'identifiant.

Attention : le claim sub est un identifiant OIDC stable au niveau du fournisseur, mais il ne doit pas être substitué automatiquement à uid. Vérifier sa valeur et sa compatibilité avec le mécanisme de provisionnement Medulla avant de modifier le mapping.

12. Corriger les erreurs les plus fréquentes

12.1. Le fournisseur refuse l'utilisateur

Symptômes :

  • Le formulaire d'authentification apparaît.
  • L'utilisateur saisit ses identifiants.
  • Le fournisseur affiche un refus d'accès.
  • Aucune redirection vers Medulla n'est effectuée.

Causes possibles :

  • Compte non autorisé à accéder au client OIDC.
  • Règle d'accès basée sur un attribut LDAP.
  • Appartenance à un groupe non conforme.
  • Compte désactivé ou non reconnu par le fournisseur.
  • Politique d'authentification du fournisseur non satisfaite.

Correction : vérifier les règles d'autorisation du fournisseur d'identité et les attributs du compte dans l'annuaire.

12.2. Redirect URI refusée

La Redirect URI de Medulla est construite selon le format :

https://medulla.exemple.fr/mmc/providers.php

Elle dépend notamment du FQDN déclaré dans la section [server_01] de la configuration MMC.

[server_01]
description = medulla.exemple.fr

Le fournisseur d'identité doit autoriser exactement la même adresse de redirection.

Attention : certains fournisseurs ne vérifient la Redirect URI qu'après l'authentification. Un diagnostic sans compte peut alors ne pas suffire.

12.3. Attribut utilisateur manquant

Si un attribut attendu n'est pas présent dans la réponse userinfo, Medulla peut ne pas disposer des informations nécessaires pour provisionner le compte.

Vérifier :

  • Que l'attribut existe dans l'annuaire.
  • Qu'il est accessible au fournisseur d'identité.
  • Qu'il est exporté dans les claims OIDC.
  • Que son nom correspond au mapping configuré dans Medulla.

12.4. L'utilisateur n'a pas les droits attendus

Le fournisseur OIDC peut appliquer une ACL par défaut.

Exemple :

base#main#default/

Cette ACL donne uniquement accès à la page d'accueil.

Un administrateur doit attribuer les droits nécessaires ou configurer une correspondance entre les rôles OIDC et les ACL Medulla.

Attention : les ACL peuvent être réappliquées à chaque connexion OIDC. Vérifier les droits après une nouvelle authentification.

12.5. Provisionnement OIDC refusé

Si une restriction authonly est présente dans la configuration d'authentification, vérifier que oidc figure dans les méthodes de provisionnement.

Fichier :

/etc/mmc/plugins/base.ini.local

Exemple :

[provisioning]
method = oidc glpi

Après modification :

systemctl restart mmc-agent

Remarque : conserver les autres méthodes de provisionnement déjà présentes dans la configuration.

12.6. Certificat TLS non reconnu

Lorsque le certificat du fournisseur est signé par une autorité interne, installer les certificats nécessaires dans le magasin de confiance du serveur Medulla.

cp autorite-interne.crt /usr/local/share/ca-certificates/
update-ca-certificates

Ne pas désactiver la validation TLS pour contourner un problème de certificat.

12.7. Authentification multifacteur ou consentement

Le script peut identifier une page MFA ou une demande de consentement sans pouvoir terminer automatiquement le parcours.

Dans ce cas, effectuer la validation dans un navigateur avec un compte autorisé.

13. Exemple de diagnostic anonymisé

Un diagnostic a été réalisé sur un serveur Medulla utilisant un fournisseur OIDC connecté à un annuaire d'entreprise.

Le résultat des contrôles techniques était :

OK : 17
KO : 0

Les éléments suivants ont été validés :

Élément Résultat
Issuer URL https://idp.exemple.fr, conforme à l'issuer annoncé.
Découverte OIDC Accessible depuis le shell et PHP.
Certificat IdP Certificat reconnu et en cours de validité.
Client ID / Secret Acceptés par le token endpoint.
Redirect URI https://medulla.exemple.fr/mmc/providers.php
Certificat Medulla Nom DNS couvert par le certificat.
Page de connexion Bouton OIDC présent.
Provisionnement Méthode oidc présente.
Horloge Synchronisation NTP correcte.
Librairie OIDC Librairie PHP OIDC installée.

Blocage identifié

Après la saisie des identifiants, le fournisseur d'identité affiche un refus d'autorisation.

Accès non autorisé pour cet utilisateur

L'utilisateur n'est pas redirigé vers Medulla.

Le blocage intervient donc avant le retour vers l'application.

Actions recommandées :

  1. Vérifier les règles d'accès du client OIDC et les attributs ou groupes de l'utilisateur.
  2. Confirmer l'autorisation de la Redirect URI https://medulla.exemple.fr/mmc/providers.php.
  3. Contrôler les attributs exportés dans userinfo.
  4. Relancer un test complet avec un compte autorisé.

Conclusion : l'absence d'erreur dans les contrôles techniques ne signifie pas que le parcours utilisateur est fonctionnel. Lorsque le fournisseur refuse l'utilisateur avant la redirection, les règles d'accès du fournisseur doivent être examinées en priorité.

14. Consulter les journaux Medulla

Les principaux journaux sont :

/var/log/apache2/error.log
/var/log/mmc/mmc-agent.log

Pour suivre les événements liés à OIDC :

tail -F /var/log/apache2/error.log /var/log/mmc/mmc-agent.log | grep -iE --line-buffered "oidc|oauth|openid|exception"

Interprétation :

  • Erreur affichée avant le retour vers Medulla : examiner le fournisseur d'identité.
  • Erreur après le retour vers Medulla : examiner Apache, MMC et les attributs OIDC.
  • Connexion réussie mais droits insuffisants : examiner le provisionnement et les ACL.

15. Rapport de diagnostic

Le script enregistre un rapport texte dans /tmp.

Exemple :

/tmp/oidc_report_OIDC_20261112-120000.txt

Le rapport contient :

  • Les informations d'environnement.
  • Les paramètres OIDC utiles au diagnostic.
  • Les contrôles OK, WARN et KO.
  • Les problèmes et corrections recommandées.
  • Les vérifications manuelles restantes.
  • Les claims reçus lorsqu'un test utilisateur est réalisé.

Le script est conçu pour ne pas afficher le Client Secret, le mot de passe ni les jetons d'authentification dans le rapport.

Confidentialité : le rapport peut contenir des données personnelles et des informations sur l'infrastructure. Il doit être vérifié avant transmission et partagé uniquement avec les personnes autorisées. Les permissions du fichier doivent également être contrôlées.

16. Questions fréquentes

Le script fonctionne-t-il avec Active Directory ?

Oui, si Active Directory est utilisé derrière un fournisseur d'identité OIDC compatible. Le script teste la chaîne OIDC entre Medulla et ce fournisseur, mais ne teste pas directement la liaison LDAP avec Active Directory.

Le script fonctionne-t-il avec OpenLDAP ?

Oui, selon le même principe : un fournisseur d'identité doit exposer les comptes OpenLDAP par OIDC. Le script ne réalise pas de connexion LDAP directe.

Faut-il utiliser les mêmes attributs LDAP avec tous les annuaires ?

Non. Les attributs LDAP peuvent différer. Le fournisseur d'identité doit les convertir en claims OIDC correspondant au mapping attendu par Medulla.

Pourquoi n'y a-t-il aucune trace OIDC dans Medulla ?

Si le fournisseur bloque l'utilisateur avant la redirection, Medulla ne reçoit pas le retour OIDC. Il faut alors examiner les règles d'accès et les journaux du fournisseur.

Le diagnostic affiche 0 KO, mais la connexion échoue. Pourquoi ?

Les contrôles techniques peuvent réussir alors qu'une règle d'accès refuse un utilisateur. Effectuer un test avec un compte autorisé.

Peut-on utiliser une adresse électronique comme identifiant ?

Oui, si le mapping OIDC est configuré pour cela. Toutefois, un changement d'adresse peut entraîner la création d'un second compte.

Pourquoi un utilisateur n'a-t-il accès qu'à la page d'accueil ?

L'ACL par défaut peut être limitée à base#main#default/. Il faut attribuer des droits supplémentaires ou configurer un mapping de rôles.

Les groupes LDAP donnent-ils automatiquement des droits dans Medulla ?

Non. Les groupes doivent être exploités par le fournisseur d'identité et transmis sous une forme compatible avec la configuration des rôles et ACL de Medulla.

Le mécanisme de correspondance des rôles doit être configuré et vérifié. Le script contrôle notamment les paramètres profiles_order et acls_json, et simule les rôles reçus via realm_access.roles lors du test utilisateur.

La déconnexion Medulla ferme-t-elle la session SSO ?

Pas nécessairement. La session du fournisseur d'identité peut rester active après une déconnexion de Medulla.

Le script modifie-t-il les comptes LDAP ?

Non. Il ne modifie pas les comptes LDAP ni les comptes Medulla. Il réalise des contrôles et simule le provisionnement.

Le script permet-il de diagnostiquer LDAPS sur le port 636 ?

Non, pas directement. Le script teste les communications OIDC en HTTPS. Pour diagnostiquer LDAP ou LDAPS entre le fournisseur d'identité et l'annuaire, utiliser les outils adaptés à cet annuaire et à son environnement.

Le script est-il compatible avec tous les fournisseurs OIDC ?

Il peut contrôler les principaux éléments standardisés d'OIDC. Cependant, certains fournisseurs utilisent des mécanismes de connexion, des formats de claims ou des politiques spécifiques nécessitant des vérifications complémentaires.

17. Procédure de diagnostic recommandée

  1. Identifier le fournisseur OIDC configuré dans Medulla.
  2. Vérifier la connectivité réseau et les certificats.
  3. Exécuter le diagnostic standard.
  4. Corriger les éventuelles erreurs de configuration.
  5. Contrôler la configuration du client OIDC chez le fournisseur d'identité.
  6. Vérifier le mapping entre les attributs de l'annuaire et les claims OIDC.
  7. Relancer le diagnostic avec un compte autorisé.
  8. Vérifier la Redirect URI et les attributs retournés par userinfo.
  9. Effectuer une connexion réelle à Medulla.
  10. Contrôler les droits attribués après connexion et reconnexion.
  11. Conserver le rapport de diagnostic pour le suivi du support.

Commande recommandée :

sudo ./test_oidc_medulla.sh -u utilisateur.test "OIDC"

18. Résumé

Le script test_oidc_medulla.sh permet de diagnostiquer la chaîne d'authentification OpenID Connect entre Medulla et un fournisseur d'identité externe.

Il peut être utilisé dans des environnements reposant sur Active Directory, OpenLDAP, FreeIPA ou d'autres annuaires LDAP, dès lors qu'un fournisseur OIDC compatible assure l'authentification et la transmission des attributs nécessaires.

Il permet de distinguer les problèmes de configuration Medulla, les anomalies réseau ou TLS, les erreurs du fournisseur d'identité et les difficultés de provisionnement des comptes.

À retenir : pour diagnostiquer une authentification SSO, il faut distinguer trois niveaux : l'annuaire qui contient les comptes, le fournisseur d'identité qui authentifie les utilisateurs et Medulla qui reçoit les informations OIDC et applique les droits. Le script diagnostique principalement la communication entre Medulla et le fournisseur OIDC.