Tool to Help Validate Microsoft Entra ID Configuration for Mail Integration (MailIntegration)

Synopsis

This page is dedicated to using scripts produced by Octopus that allow you to diagnose configuration problems with the Microsoft Entra ID enterprise application used by Octopus Mail Integration (MailIntegration). 

If your mailbox is unable to create incidents or events in Octopus from received emails and you are experiencing difficulties, this page describes step by step what to do to obtain a complete diagnostic of your enterprise application's configuration as well as an actual mailbox connection test. The report produced can help you identify the source of the problem.

This article assumes that you have already completed all the steps in the following wiki for setting up your enterprise application : 

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

Prerequisites

1. Download the PowerShell script package
   • https://updates.octopus-itsm.com/tools/EntraID-ConfigurationCheck_v1.0.zip
   • Keep all the .ps1 files from the package together, in the same folder : Test-OctopusEntraMailIntegration.ps1, Test-OctopusEntraMailPop.ps1, and Common.ps1 load each other and must remain in the same location. The folder from which you run them does not matter.
2. Have an Entra ID account with the following permissions : 
   • Application.Read.All
   • Directory.Read.All
3. ​The Microsoft.Graph.Authentication PowerShell module must be installed
   • ​​​​If it is not, the script will attempt to install it automatically. It will then need authorization for NuGet
   • Make sure these modules comply with your organization's internal policies
4. The script uses Microsoft Graph Command Line endpoints to perform the configuration checks
5. For the functional mailbox connection test (optional) :
   • The mailbox account password (masked entry, never saved or logged)
   • Outbound network access to outlook.office365.com:995

How It Works

The package contains two complementary scripts :

Script	Role
Test-OctopusEntraMailIntegration.ps1	Validates the configuration of the enterprise application in Entra ID (delegated permissions, admin consent, public client flows, mailbox assignment). Read-only via Microsoft Graph : this script never modifies the tenant.
Test-OctopusEntraMailPop.ps1	Performs an actual (functional) connection test to the mailbox : network connection, obtaining an OAuth2 token, POP3 authentication. Can be run on its own or offered automatically at the end of the first script.

Both scripts are designed to prompt for the necessary information at the appropriate time. A log file is created in a Logs subfolder, next to the scripts.

Execution

Obtaining the Identifiers (GUIDs) and Connection Information

The scripts need the following information : the directory (tenant) ID, the application (client) ID, and the mailbox email address used by MailIntegration (and, for the functional test, its password).

This information can be found in the XML configuration file that you provided to the MailIntegration tool (the file you already have on hand to configure your mail integration — its location depends on your installation). Open this file with a text editor (e.g. : Notepad) and locate the following elements, inside the <server> section:

Locating Each Value

Element in the XML file	Value to copy	Script parameter
<tenantId>	Entra ID tenant GUID	-TenantId
<clientId>	MailIntegration application (client) GUID	-AppId
<userName>	Mailbox email address	-Mailbox
<password>	Mailbox account password (only required for the functional POP3 test ; never passed as a parameter, always entered as masked input at the prompt)	(interactive entry)

Note : in a sample or template XML file, the password may appear masked (*****). Always use the configuration file actually used by your MailIntegration deployment, which contains the real values.

Running the Configuration Diagnostic

Option A — Interactive Mode (recommended)

No parameters : the script prompts for each value and checks that the GUIDs and the email address are well-formed.

If script execution is blocked by Windows :

Option B — With Values as Parameters

Handy for quickly rerunning a test. Replace the GUIDs and the email address with those collected from the XML file :

The password is never provided as a parameter : it is only requested if you agree to run the POP3 functional test described below.

Functional Mailbox Connection Test (POP3)

Once the Entra ID configuration summary is displayed, the script offers to test the actual connection to the mailbox :

Answer y to launch Test-OctopusEntraMailPop.ps1 automatically (you will be prompted for the password at that point). This test :

• Checks the network connection to outlook.office365.com:995
• Obtains an OAuth2 token (same scopes as those used by MailIntegration in production)
• Authenticates to the POP3 server with this token
• Reports, for informational purposes only, the number of messages present in the mailbox

You can also run this test on its own, without going through the configuration diagnostic :

Note : the authentication flow used (username + password) fails if the tenant enforces MFA or a conditional access policy on this application — this is not a script bug, see the error guide below.

Reviewing the Report and Fixing Identified Issues

The scripts each produce a PASS / FAIL / WARN / INFO report and save a log file in the Logs subfolder : OctopusEntra-MailIntegration-YYYYMMDD-HHMMSS.log and, if the functional test was run separately, OctopusEntra-MailPop-YYYYMMDD-HHMMSS.log. 

The information collected by the script may help your Entra ID administrator fix the problem.

Opening a Ticket with Our Service Desk

 If you are unable to resolve the problem, you can contact our Service Desk for additional assistance

• Log in to our web portal and open a new request (or ask an authorized administrator in your organization to do so)
• Provide the following information: 
  • Contact details of the person who administers Entra ID
    • First and last name
    • Email address
    • Job title
• Include the log files produced by the script
  • Send us the complete .log files, not just a screenshot
  • They do not contain any passwords, secrets, or authentication tokens

Guide to Diagnosing Entra ID Errors During the POP3 Functional Test

AADSTS50076 / AADSTS50079

• Multi-factor authentication (MFA) is required for this account or application.

Probable Cause

• An MFA or conditional access policy requires MFA registration/use on this account.
• The username/password flow (ROPC) used by the test cannot satisfy an MFA requirement — this is not a script bug, it is the expected behavior of Entra ID.

AADSTS50034

• This username does not exist in this tenant.

Probable Cause

• The email address entered does not match any account in this tenant (typo, wrong domain).

AADSTS50126

• Credential validation error : invalid username or password.

Probable Cause

• Incorrect or recently changed password.

AADSTS700016

• The application (AppId) was not found or is not authorized in this tenant.

Probable Cause

• The clientId found in the XML file does not match this tenant, or the application registration has been deleted.

AADSTS7000218

• The request body must contain the "client_assertion" or "client_secret" parameter.

Probable Cause

• The Allow public client flows option is not enabled on the application registration (Authentication tab > Advanced settings).

AADSTS65001

• Admin consent has not been granted for POP.AccessAsUser.All.

Probable Cause

• The delegated permissions POP.AccessAsUser.All / SMTP.Send have not received tenant-wide admin consent (API permissions > Grant admin consent).

AADSTS53003

• A conditional access policy is blocking this connection.

Probable Cause

• A conditional access policy (location, device, application) is preventing this authentication.

AADSTS500011

• The service principal for the requested resource cannot be found in this tenant.

Probable Cause

• Exchange Online is not provisioned in this tenant, or the requested resource URI/scope is incorrect.

consent_required / AADSTS65004

• Consent (admin or user) is required for this application/scope combination and has not yet been granted.

Probable Cause

• The permissions are present on the application registration, but consent has never been given, either by an administrator or by the user.