Outil d'aide à la validation de la configuration Microsoft Entra ID pour l'intégration courriel (MailIntegration)

Synopsis

Cette page est dédiée à l'utilisation de scripts produits par Octopus qui permettent de diagnostiquer des problèmes de configuration de l'application d'entreprise Microsoft Entra ID utilisée par l'intégration courriel Octopus (MailIntegration). 

Si votre boîte aux lettres n'arrive pas à créer des incidents ou des événements dans Octopus à partir des courriels reçus et que vous éprouvez des difficultés, cette page décrit étape par étape ce qu'il faut faire pour obtenir un diagnostique complet de la configuration de votre application d'entreprise ainsi qu'un test de connexion réel à la boîte aux lettres. Le rapport produit peut vous aider à identifier la source du problème.

Cet article assume que vous avez déjà passé toutes les étapes de ce wiki pour la mise en place de votre application d'entreprise : 

• https://wiki.octopus-itsm.com/en/articles/mailintegration-create-incidents-or-events-emails

Prérequis

1. Télécharger la trousse de scripts Powershell
   • https://updates.octopus-itsm.com/tools/EntraID-ConfigurationCheck_v1.0.zip
   • Conservez tous les fichiers .ps1 de la trousse ensemble, dans le même dossier : Test-OctopusEntraMailIntegration.ps1, Test-OctopusEntraMailPop.ps1 et Common.ps1 se chargent mutuellement et doivent rester au même endroit. Le dossier depuis lequel vous les exécutez n'a pas d'importance.
2. Avoir un compte EntraID avec les permissions suivantes : 
   • Application.Read.All
   • Directory.Read.All
3. ​Le module Powershell Microsoft.Graph.Authentication doit être installé
   • ​​​​S'il ne l'est pas, le script tentera de l'installer automatiquement. Il aura alors besoin d'une autorisation pour NuGet
   • Assurez-vous que ces modules sont conformes aux politiques internes de votre organisation
4. Le script utilise les points de terminaisons Microsoft Graph Command Line pour exécuter les vérifications de configuration
5. Pour le test fonctionnel de connexion à la boîte aux lettres (optionnel) :
   • Le mot de passe du compte de la boîte aux lettres (saisie masquée, jamais enregistré ni journalisé)
   • Un accès réseau sortant vers outlook.office365.com:995

Fonctionnement

La trousse contient deux scripts complémentaires :

Script	Rôle
Test-OctopusEntraMailIntegration.ps1	Valide la configuration de l'application d'entreprise dans Entra ID (permissions déléguées, consentement administrateur, flux clients publics, attribution de la boîte aux lettres). Lecture seule via Microsoft Graph : ce script ne modifie jamais le locataire.
Test-OctopusEntraMailPop.ps1	Effectue un test de connexion réel (fonctionnel) à la boîte aux lettres : connexion réseau, obtention d'un jeton OAuth2, authentification POP3. Peut être lancé seul ou proposé automatiquement à la fin du premier script.

Les deux scripts sont programmés de façon à demander les informations nécessaires au moment opportun. Un fichier de journal (log) est créé dans un sous-dossier Logs, à côté des scripts.

Exécution

Obtention des identifiants (GUID) et des informations de connexion

Les scripts ont besoin des informations suivantes : l'ID de l'annuaire (locataire), l'ID de l'application (client) et l'adresse courriel de la boîte aux lettres utilisée par MailIntegration (et, pour le test fonctionnel, son mot de passe).

Ces informations se trouvent dans le fichier de configuration XML que vous avez fourni à l'outil MailIntegration (le fichier que vous avez déjà en main pour configurer votre intégration courriel — son emplacement dépend de votre installation). Ouvrez ce fichier avec un éditeur de texte (ex. : Bloc-notes) et repérez les éléments suivants, à l'intérieur de la section <server> :

Repérer chaque valeur

Élément dans le fichier XML	Valeur à copier	Paramètre du script
<tenantId>	GUID du locataire Entra ID	-TenantId
<clientId>	GUID de l'application (client) MailIntegration	-AppId
<userName>	Adresse courriel de la boîte aux lettres	-Mailbox
<password>	Mot de passe du compte de la boîte aux lettres (uniquement requis par le test fonctionnel POP3 ; jamais passé en paramètre, toujours saisi de façon masquée à l'invite)	(saisie interactive)

Note : dans un fichier XML modèle ou d'exemple, le mot de passe peut apparaître masqué (*****). Utilisez toujours le fichier de configuration réellement utilisé par votre déploiement MailIntegration, qui contient les vraies valeurs.

Lancer le diagnostic de configuration

Option A — mode interactif (recommandé)

Aucun paramètre : le script demande chaque valeur et vérifie que les GUID et l'adresse courriel sont bien formés.

Si l'exécution des scripts est bloquée par Windows :

Option B — avec les valeurs en paramètres

Pratique pour rejouer un test rapidement. Remplacez les GUID et l'adresse courriel par ceux relevés dans le fichier XML :

Le mot de passe n'est jamais fourni en paramètre : il n'est demandé que si vous acceptez de lancer le test fonctionnel POP3 décrit ci-dessous.

Test fonctionnel de connexion à la boîte aux lettres (POP3)

Une fois le résumé de la configuration Entra ID affiché, le script propose de tester la connexion réelle à la boîte aux lettres :

Répondez o pour lancer Test-OctopusEntraMailPop.ps1 automatiquement (le mot de passe vous sera demandé à ce moment). Ce test :

• Vérifie la connexion réseau vers outlook.office365.com:995
• Obtient un jeton OAuth2 (mêmes portées que celles utilisées par MailIntegration en production)
• S'authentifie au serveur POP3 avec ce jeton
• Rapporte, à titre informatif seulement, le nombre de messages présents dans la boîte

Vous pouvez aussi exécuter ce test seul, sans passer par le diagnostic de configuration :

Note : le flux d'authentification utilisé (nom d'utilisateur + mot de passe) échoue si le locataire impose le MFA ou une stratégie d'accès conditionnel sur cette application — ce n'est pas un bogue du script, voir le guide d'erreurs ci-dessous.

Analyse du rapport et correction des anomalies identifiées

Les scripts produisent un rapport PASS / FAIL / WARN / INFO et enregistrent chacun un journal dans le sous-dossier Logs : OctopusEntra-MailIntegration-AAAAMMJJ-HHMMSS.log et, si le test fonctionnel a été lancé séparément, OctopusEntra-MailPop-AAAAMMJJ-HHMMSS.log. 

Les informations relevées par le script pourraient aider votre administrateur Entra ID à corriger le problème.

Ouverture de requête à notre Centre de Services.

 Si vous n'arrivez pas à corriger le problème, vous pouvez contacter notre Centre de Services pour obtenir de l'assistance supplémentaire

• Connectez-vous sur notre portail Web et ouvrez une nouvelle demande (ou demandez à un administrateur autorisé de votre organisation de le faire)
• Fournir les informations suivantes : 
  • Contact de la personne qui administre EntraID
    • Nom et Prénom
    • Adresse courriel
    • Titre
• Inclure les fichiers journaux produits par le script
  • Nous envoyer les fichiers .log au complet, pas seulement une capture d'écran
  • Ils ne contienent aucun mot de passe, secret, ni jeton d'authentification

Guide de diagnostic des erreurs Entra ID lors du test fonctionnel POP3

AADSTS50076 / AADSTS50079

• Le MFA (authentification multifacteur) est requis pour ce compte ou cette application.

Cause probable

• Une politique MFA ou d'accès conditionnel exige l'enregistrement/l'utilisation du MFA sur ce compte.
• Le flux nom d'utilisateur/mot de passe (ROPC) utilisé par le test ne peut pas satisfaire une exigence MFA — ce n'est pas un bogue du script, c'est le comportement attendu d'Entra ID.

AADSTS50034

• Ce nom d'utilisateur n'existe pas dans ce locataire.

Cause probable

• L'adresse courriel saisie ne correspond à aucun compte de ce locataire (faute de frappe, mauvais domaine).

AADSTS50126

• Erreur de validation des informations d'identification : nom d'utilisateur ou mot de passe invalide.

Cause probable

• Mot de passe incorrect ou récemment modifié.

AADSTS700016

• L'application (AppId) est introuvable ou non autorisée dans ce locataire.

Cause probable

• Le clientId relevé dans le fichier XML ne correspond pas à ce locataire, ou l'inscription de l'application a été supprimée.

AADSTS7000218

• Le corps de la requête doit contenir le paramètre « client_assertion » ou « client_secret ».

Cause probable

• L'option Autoriser les flux clients publics n'est pas activée sur l'inscription de l'application (onglet Authentification > Paramètres avancés).

AADSTS65001

• Le consentement administrateur n'a pas été accordé pour POP.AccessAsUser.All.

Cause probable

• Les permissions déléguées POP.AccessAsUser.All / SMTP.Send n'ont pas reçu le consentement administrateur à l'échelle du locataire (Autorisations d'API > Accorder le consentement administrateur).

AADSTS53003

• Une stratégie d'accès conditionnel bloque cette connexion.

Cause probable

• Une politique d'accès conditionnel (emplacement, appareil, application) empêche cette authentification.

AADSTS500011

• Le principal de service de la ressource demandée est introuvable dans ce locataire.

Cause probable

• Le service Exchange Online n'est pas provisionné dans ce locataire, ou l'URI de ressource/portée demandée est incorrecte.

consent_required / AADSTS65004

• Un consentement (administrateur ou utilisateur) est requis pour cette combinaison application/portée et n'a pas encore été accordé.

Cause probable

• Les permissions sont présentes sur l'inscription de l'application mais le consentement n'a jamais été donné, ni par un administrateur, ni par l'utilisateur.