> For the complete documentation index, see [llms.txt](https://docs.enginsight.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enginsight.com/docs/knowledge-base/english/configuration/how-do-i-set-up-an-enginsight-email-server-for-microsoft-365-using-oauth2.md). # How do I set up an Enginsight email server for Microsoft 365 using OAuth2? Setting up an email server in Enginsight is required so that you can, for example, receive password reset emails or alert notifications. The email server is configured in the Enginsight platform under **Settings** → [Email Server](https://docs.enginsight.com/docs/manual/english/administration/settings/email-server). If you want to configure an email server for Microsoft 365 using OAuth2, you first need to register a new application in Microsoft Entra ID, assign the required permissions, and register it in Exchange Online for the sending mailbox. This article shows you how to do this. *** ## Requirements * A sending Exchange Online mailbox, for example **, that has been provisioned and licensed according to Microsoft's requirements. * The Enginsight platform must be able to reach `login.microsoftonline.com` and `smtp.office365.com` via HTTPS. For on-pPremises installations, this outbound traffic must be allowed through the firewall or proxy. Working DNS resolution and TLS are also required. * Administrator permissions to register the application in Microsoft Entra ID, grant tenant-wide administrator consent, and manage service principals and mailbox permissions in Exchange Online. *** ## Configurations in the Microsoft Entra ID portal {% stepper %} {% step %} ### Open the Microsoft Entra Admin Center 1. Open `https://entra.microsoft.com` in a browser. Alternatively, you can open `https://portal.azure.com` and search for **Microsoft Entra ID**. The pages are identical. 2. Sign in with the administrator account. 3. If you have access to multiple tenants, use the **Settings** icon (:gear:) in the top menu to switch to the tenant you want to connect. The tenant name is shown in the upper-right corner. {% endstep %} {% step %} ### Register a new application Register Enginsight as a new application in Microsoft Entra ID. For more information, see the [official vendor documentation](https://learn.microsoft.com/de-de/entra/identity-platform/quickstart-register-app). {% hint style="warning" %} **Please note**: The views and configuration steps described below may change. Enginsight assumes no liability for changes to third-party user interfaces. {% endhint %} Enter the following values: * **Name**: You can choose any name. It is only shown in the Microsoft Entra ID portal. We recommend that you use a meaningful name such as *Enginsight Email*. * **Supported account types**: Select **Single tenant only – \**. In older views, this option is called **Accounts in this organizational directory only**. * **Redirect URIs**: Leave this field empty. {% endstep %} {% step %} ### Get the client ID and tenant ID After registration, you are taken to the overview page of the new application. Here you can find both the **client ID** (also called **application ID**) and the **tenant ID** (also called **directory ID**). You will need this information later when [configuring the email server](#configure-the-email-server-in-enginsight) in the Enginsight platform. You also need the client ID when [registering the application in Exchange Online](#register-the-application-in-exchange-online). {% endstep %} {% step %} ### Create a client secret 1. Create a **client secret** (also called an **application secret**) for the new application. For more information, see the [official vendor documentation](https://learn.microsoft.com/de-de/entra/identity-platform/how-to-add-credentials?tabs=client-secret). {% hint style="warning" %} **Please note**: The views and configuration steps described below may change. Enginsight assumes no liability for changes to third-party user interfaces. {% endhint %} Enter the following values: * **Description**: You can choose any description. * **Expires**: Set a lifetime for the client secret. Microsoft Entra ID allows a maximum of 24 months. Choose the longest period allowed by your security policy and make a note of the expiration date. {% hint style="danger" %} **Please note**: When the client secret expires, synchronization between the Enginsight SIEM and Entra ID stops with the error `AADSTS7000222` / `invalid_client`. In this case, you need to [replace the client secret](#replace-an-expired-client-secret). {% endhint %} 2. Copy the client secret and store it in a secure location. {% hint style="warning" %} **Please note**: Use the **value** of the Client Secret. The **secret ID** does not work here. {% endhint %} {% hint style="danger" %} **Please note**: When you add a client secret in Microsoft Entra ID, it is shown **only once immediately after it is created and never again**. Make sure that you save the client secret as soon as you create it. {% endhint %} {% endstep %} {% step %} ### Grant API permissions You now need to grant the new application permission to access the **Office 365 Exchange Online API**. For more information, see the [official vendor documentation](https://learn.microsoft.com/de-de/entra/identity-platform/quickstart-configure-app-access-web-apis). {% hint style="warning" %} **Please note**: The views and configuration steps described below may change. Enginsight assumes no liability for changes to third-party user interfaces. {% endhint %} Follow these steps: 1. Navigate to **API permissions**. 2. Click **Add a permission**. 3. Select **Office 365 Exchange Online**. 4. Select **Application permissions**. Application permissions allow Enginsight to act as a service without a signed-in user. 5. Use the search field and select the `SMTP.SendAsApp` permission. 6. Click **Add permissions**. 7. Click **Grant admin consent for \** and confirm with **Yes**. 8. Click **Refresh** and check the **Status** column. Each row must show a green check mark and **Granted for \**. #### The `SMTP.SendAsApp` permission is not shown If the `SMTP.SendAsApp` permission is not shown, check the following: * Make sure that you are under **APIs my organization uses** → **Office 365 Exchange Online**. Searching in **Microsoft Graph** shows different email permissions. * Make sure that you selected **Application permissions**. The **delegated permission** `SMTP.Send` belongs to a different user-delegated flow. * If **Office 365 Exchange Online** is not shown, check the selected tenant and whether you have permission to add API permissions. An administrator may need to complete this step. {% endstep %} {% endstepper %} *** ## Configurations in Exchange Online {% stepper %} {% step %} ### Get the required IDs from Microsoft Entra ID You need the following values for the next steps: * The **client ID** (also called **application ID**) from [step 3](#get-the-client-id-and-tenant-id) above. In PowerShell, this corresponds to `$appID`. * The **object ID of the enterprise application**. You can find it in Microsoft Entra ID under **Entra ID** → **Enterprise applications** → **\** → **Overview** → **Object ID**. In PowerShell, this corresponds to `$enterpriseObjectId`. {% hint style="danger" %} **Please note**: The **object ID of the enterprise application** is ***not*** the object ID of the registered application that you can find under **App registrations** → **\** → **Overview** → **Object ID**. If you use the object ID from **App registrations**, `New-ServicePrincipal` can fail with the error `AADServicePrincipalNotFound`. {% endhint %} {% endstep %} {% step %} ### Register the application in Exchange Online Run the following commands in an Exchange Online PowerShell as an Exchange administrator. {% hint style="info" %} Remember to replace the following placeholders: * ``; for example ** * `` * `` * ``; for example ** {% endhint %} 
Install-Module ExchangeOnlineManagement -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName "<AdminUsername>"

$appId = "<ClientID>"
$enterpriseObjectId = "<EnterpriseApplicationObjectID>"
$mailbox = "<SendingEmailMailbox>"

$exoSp = Get-ServicePrincipal | Where-Object { $_.AppId -eq $appId }

if (-not $exoSp) {
  New-ServicePrincipal `
    -AppId $appId `
    -ObjectId $enterpriseObjectId `
    -DisplayName "Enginsight Email"

  $exoSp = Get-ServicePrincipal | Where-Object { $_.AppId -eq $appId }
}

if (@($exoSp).Count -ne 1) {
  throw "Expected exactly one Exchange service principal."
}

$exoSp | Format-List DisplayName,AppId,ObjectId,Identity
A successful registration should return the following: ``` DisplayName : Enginsight Email AppId : ObjectId : Identity : ``` {% endstep %} {% step %} ### Grant and verify access to the sending mailbox {% hint style="warning" %} **Please note**: From this point on, use `$exoSp.Identity` for the mailbox permission commands. You can only use the enterprise application object ID as the trustee for the mailbox if it matches the returned Exchange identity. {% endhint %} 1. Grant the Exchange Service Principal the `FullAccess` and `SendAs` permissions for the sending mailbox using the following commands: ``` Add-MailboxPermission -Identity $mailbox ` -User $exoSp.Identity -AccessRights FullAccess Add-RecipientPermission -Identity $mailbox ` -Trustee $exoSp.Identity -AccessRights SendAs ``` 2. Use the following commands to check whether the permissions were granted correctly: ``` Get-MailboxPermission -Identity $mailbox -User $exoSp.Identity Get-RecipientPermission -Identity $mailbox -Trustee $exoSp.Identity ``` The output should contain the following values: ``` Get-MailboxPermission ... AccessRights : {FullAccess} IsInherited : False Deny : False Get-RecipientPermission ... AccessRights : {SendAs} Inherited : False ``` {% endstep %} {% step %} ### Check SMTP AUTH 1. Use the following commands to check whether SMTP AUTH is enabled for the organization and the sending mailbox: ``` Get-TransportConfig | Format-List SmtpClientAuthenticationDisabled Get-CASMailbox -Identity $mailbox | Format-List SmtpClientAuthenticationDisabled ``` The following values can be returned: | Value | Meaning | | ------------------------------- | ------------------------------------------ | | `False` | SMTP AUTH is enabled. | | `True` | SMTP AUTH is disabled. | | Empty / `$null` for the mailbox | The mailbox uses the organization setting. | 2. If required, use the following commands to enable SMTP AUTH specifically for the sending mailbox, then check the setting again: ``` Set-CASMailbox -Identity $mailbox ` -SmtpClientAuthenticationDisabled $false Get-CASMailbox -Identity $mailbox | Format-List SmtpClientAuthenticationDisabled ``` Alternatively, you can enable SMTP AUTH in the Microsoft 365 Admin Center under **Users** → **Active users** → **\** → **Mail** → **Manage email apps** → **Authenticated SMTP**. {% hint style="warning" %} **Please note**: Security defaults and other tenant security policies can also affect SMTP AUTH. Do ***not*** enable basic authentication as a workaround. {% endhint %} {% endstep %} {% endstepper %} *** ## Configuring the Email Server in Enginsight After you completed all settings in Microsoft Entra ID and Exchange Online, you can configure the email server in the Enginsight platform. Follow these steps: {% stepper %} {% step %} In the Enginsight platform, navigate to **Settings** → **Email Server** and click **Add Configuration**. Follow the setup wizard. {% endstep %} {% step %} Select **Microsoft 365** as the **Provider** and click **Next**. {% endstep %} {% step %} In the **Connection** view, enter the following values:
Field in EnginsightValue
HostKeep the default value smtp.office365.com.
PortKeep the default port 587.
EncryptionKeep the default encryption setting STARTTLS.
Skip Certificate ValidationLeave the checkbox disabled.
Authentication MethodKeep the default authentication method OAuth2.
Tenant IDEnter the tenant ID (directory ID (tenant)) of the Microsoft 365 tenant.
Client IDEnter the client ID of the application registered in Microsoft Entra ID.
Client SecretEnter the client secret that you created for the new application in Microsoft Entra ID.
MailboxEnter the sending mailbox from Microsoft Exchange Online, for example notifications@contoso.com.
Sender

Enter the sender of the emails sent through the email server in the format "Enginsight" <no-reply@example.com>.

Please note: For the first connection test in Enginsight, use the same address for both Mailbox and Sender. A different sender address requires its own SendAs permission in Microsoft Exchange Online.

{% endstep %} {% step %} Click **Test Connection**. A window opens with the following additional information: {% hint style="info" %} The connection test uses the connection and authentication details you entered previously, even if you have not saved them yet. If you have recently created new credentials with your provider, it can take a few minutes for them to become active. If the connection test fails, try again a little later. {% endhint %} {% endstep %} {% step %} Click **Test Connection** to start the connection test and send a test email to the email address that you entered in your user account. {% hint style="danger" %} **Please note**: A successful test does not save the configuration. If you leave this view without saving, all settings you entered will be lost. {% endhint %} {% endstep %} {% step %} If the test is successful, you can optionally configure **advanced settings**, for example to define a **connection limit** and a **sending limit**. {% hint style="warning" %} **Please note**: Microsoft allows a maximum of 3 simultaneous connections. {% endhint %} {% endstep %} {% step %} Click **Next** to review a summary of all settings in the overview. {% endstep %} {% step %} Click **Save Changes** to apply your settings. {% endstep %} {% endstepper %} *** ## Replacing an Expired Client Secret {% hint style="info" %} We recommend that you set a calendar reminder a few weeks before the client secret expires. The Microsoft Entra ID portal shows the expiration date in the client secrets list and highlights expired secrets in red. {% endhint %} If the client secret has expired, follow these steps: {% stepper %} {% step %} Create a new client secret for the affected application in the Microsoft Entra ID portal. {% endstep %} {% step %} In the Enginsight platform, navigate to **Settings** → **Email Server** and click **Edit**. {% endstep %} {% step %} Enter the new **client secret**. {% endstep %} {% step %} Click **Test Connection**. {% endstep %} {% step %} If the test is successful, click **Save Changes**. Wait until synchronization between Microsoft Entra ID and Enginsight has completed successfully. {% endstep %} {% step %} Return to the Microsoft Entra ID portal and delete the old client secret. {% endstep %} {% endstepper %} *** ## Troubleshooting | Error | Cause | Solution | | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SMTP.SendAsApp` cannot be found | The permission was searched for in the wrong API. | Navigate to **Add a permission** → **APIs my organization uses** → **Office 365 Exchange Online** → **Application permissions**. Do not search in Microsoft Graph. | | `AADServicePrincipalNotFound` when using `New-ServicePrincipal` | The wrong object ID was often used. | Use the object ID from **Enterprise applications** → **Enginsight Email** → **Overview**. The object ID from **App registrations** belongs to a different object. | | `AADSTS7000215` / `invalid client secret` | The client secret is incorrect. This can happen, for example, if the **secret ID** was copied instead of the **value**. | Create a new client secret and copy the correct value. | | `AADSTS7000222` / expired Client Secret | The client secret has expired. | Replace the client secret [as described above](#replacing-an-expired-client-secret). | | `AADSTS700016` / application not found | The client ID does not belong to this tenant or the tenant ID is incorrect. | Check the tenant ID and client ID again in the Microsoft Entra ID portal. | | `535` / `authentication unsuccessful` | SMTP authentication failed. | Check administrator consent for `SMTP.SendAsApp`, the token claims, the Exchange Service Principal, mailbox permissions, and SMTP AUTH. | | `5.7.60` / `SendAs denied` | The sender address does not have the `SendAs` permission. | Check the `SendAs` permission for the exact sender address. Use the same address for **Mailbox** and **Sender** in Enginsight. | | [430 4.2.0 STOREDRV](broken://pages/0941d40ad0d5c437a4073b5fc26353475ab3b62f#error-430-420-storedrv) / `Cannot open mailbox` | Exchange Online cannot open the mailbox in the context of the application. | Check the `FullAccess` permission, the mailbox GUID, SMTP AUTH, and permission propagation. | | Timeout / `ENOTFOUND` / TLS error | The network connection to Microsoft Entra ID or Exchange Online is interrupted. | Check DNS, HTTPS access to `login.microsoftonline.com`, TCP port **587** to `smtp.office365.com`, and certificate validation. | ### Error `430 4.2.0 STOREDRV` Typical error messages are: `STOREDRV; mailbox logon failure; Cannot open mailbox; AuthenticationContext has no rights on this session`. | Finding | Action | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | OAuth authentication might already have been successful. | Check whether `AUTH XOAUTH2` returned code `235`. If so, the token was accepted and the error occurs only when the message is passed to the mailbox. | | The mailbox store cannot open the mailbox in the context of the application. | Check `FullAccess`, the exact mailbox, and `SendAs`, and wait for the permissions to propagate. | ### Check the mailbox GUID Use the following command to check whether Exchange Online opens the expected mailbox: ``` Get-Mailbox -Identity $mailbox | Format-List PrimarySmtpAddress,RecipientTypeDetails,ExchangeGuid ``` If an SMTP error message contains a `mailboxGuid`, compare it with the `ExchangeGuid`. If both GUIDs match, the expected mailbox is being opened. ### Check the number of Exchange Service Principals Exactly one Exchange Service Principal may exist for the Client ID. Check this using the following commands: ``` $allSp = @(Get-ServicePrincipal | Where-Object { $_.AppId -eq $appId }) $allSp | Format-List DisplayName,AppId,ObjectId,Identity "Count: $($allSp.Count)" ``` The expected count is `1`. ***