Documentation forWeb Help Desk
Important security updates are available for WHD. SolarWinds recommends you upgrade to version 12.8.3 Hotfix 3.

Configure an incoming email account for Microsoft 365

On this page

Introduction

If you use Microsoft 365 (previously called Office 365) for your incoming email, create a new incoming email account in WHD and link it to a Microsoft Azure account. This method uses Modern Authentication, which implements Multi-factor Authentication (MFA), Open Authentication (OAuth) 2.0, and conditional access policies (such as Azure Active Directory Conditional Access) to access Exchange email. This ensures that all email correspondence between your Microsoft 365 email account and WHD is safe and secure from unauthorized access.

OAuth is an open-standard authorization protocol used by websites and applications to enable Internet users to access resources without providing a password. MFA is an authentication method that grants user access to a resource after they present two or more pieces of evidence (or factors) to an authentication mechanism—for example, a password and a secret code.

Options for configuring a Microsoft 365 incoming email account in WHD

There are two options for configuring an Microsoft 365 incoming email account in WHD.

Option 1: Configure using Exchange Web Services (EWS)

To configure a new incoming email account for Microsoft 365:

  1. Verify your Exchange Online account settings.
  2. Obtain an Azure account.

  3. Register WHD as an application in Azure.

  4. Create a new incoming email account in WHD for your Microsoft 365 email.

If you are accessing an Microsoft 365 email account on a GCC High/Azure Government tenant, see JVM arguments for additional guidance.

Shared Microsoft 365 incoming email accounts are not supported.

Option 2: Configure using Microsoft Graph API

Microsoft deprecated the Exchange Web Services (EWS) API that was previously used to access and receive email from a Microsoft Exchange or Microsoft 365 mailbox.

To access your Microsoft 365 mailbox and receive your WHD email, do the following:

  1. Register WHD in Microsoft Azure as an application.

  2. Modify the WHD configuration file.

    1. Configure JVM argument for Non-Government Azure tenant - to access your mailbox for a normal (non-Government) tenant.

    2. Configure JVM Arguments for GCC High/Azure Government tenant - to access your mailbox on a Microsoft Government Community Cloud (GCC) High/Azure Government tenant.

  3. Configure your incoming email account for Microsoft 365.

The GCC High and Azure Government cloud platforms provide additional security to prevent unauthorized access to your WHD email. See the Microsoft Learn website for more information about these platforms.

Register WHD in Microsoft Azure as an application with Microsoft APIs

  1. Log in to WHD as an administrator.

  2. Click Setup > General > Options.

  3. In the General Options page, locate the Server DNS Name field.

  4. Update the field with your server DNS name.

    For example: helpdesk.mydomain.com

    Do not enter localhost, as this server DNS name does not resolve outside of the WHD server.

  5. Record the new server DNS name and SSL port number for a future step.

  6. Open a web browser and navigate to:

    https://portal.zaure.com/#home

    Do not close WHD.

  7. On the Home page under Azure services, click Azure Active Directory.

  8. In the navigation pane under Manage, click App registrations.

  9. Click the New registration tab.

  10. Under Name, enter a display name for WHD.

    For example, you can enter Web Help Desk, as shown below.

  11. Under Supported account types, select the Single tenant option.

  12. Under Redirect URI (optional), create a redirect URI in the following format using the WHD server DNS name and port number you retrieved in a previous step.

    https://<Server_DNS_Name>:<Port>/helpdesk/oauth-redirect

    For example:

    • If the WHD server DNS name is localhost and a port number is required, enter:

      https://localhost:8443/helpdesk/oauth-redirect

    • If the WHDserver DNS name is localhost and a port number is not required, enter:

      https://localhost/helpdesk/oauth-redirect

  13. Save the application.

  14. In the navigation pane, click App registrations.

  15. Under Display name, click the Web Help Desk application.

    The Web Help Desk application details display.

  16. Record the client and tenant ID values and save them to a text file.

  17. In the navigation menu, click API Permissions.

  18. Click Add a new permission > Microsoft APIs > Microsoft Graph > Delegated Permission to access the following screen:

  19. In the Request API permissions screen, locate and enable the required permissions.

    The following table lists the permissions to enable in this screen.

    Permission Access Description
    Mail.ReadWrite Read and write access to user mail Allows the app to create, read, update, and delete email in user mailboxes. Does not include permission to send mail.
    email View the user's email address Allows the app to read your users' primary email address.
    offline_access Access the user's data anytime Allows the app to read and update the user date, even when they are not currently using the application.
    User.Read Sign-in and read user profile Allows users to sign in to the app, and allows the app to read the profile of signed-in users. It also allows the app to read basic company information of signed-in users.

    When you are finished, the WHD API permissions screen displays, as shown below.

  20. Click Grant admin consent for {your tenant}, which allows an admin to grant admin consent to the permissions configured for the application. When you select the button, a dialog is shown requesting that you confirm the consent action.

    After you have granted consent, the permissions that required admin consent are shown as having consent granted:

    • If you aren't an admin or if no permissions have been configured for the application, the Grant admin consent button is disabled.

    • If permissions were granted but not yet configured, the admin consent button prompts you to handle these permissions. You can add them to configured permissions or remove them.

  21. Remove any other pre-existing permissions from the remaining permission drop-down menus.

  22. In the navigation pane, click Certificates & Secrets.

  23. In the WHDCertificates & secrets screen, click New client secret.

  24. Under Add a client secret, select an expiration date.

  25. (Optional) Enter a description.

  26. Click Add.

  27. At the bottom, locate the Client Secret with the new client secret code.

  28. Copy the client secret code Value ID to a text file.

    Store this text file in a safe location. This code is unique and cannot be retrieved when you close the window.

Update the WHD configuration file

Update the configuration file in your Windows Server, macOS, or Linux server deployment to access the GCC High/Azure Government tenant.

Update the WHD configuration file for WHD running on Windows Server

  1. Log in to your WHD server as an administrator.

  2. Navigate to:

    <WebHelpDesk>\bin\wrapper\conf

    where <WebHelpDesk> represents the WHD home folder.

  3. Open the wrapper_template.conf file in a text editor (for example, Notepad).

  4. Locate the Java Additional Parameters section.

  5. At the bottom of this section, add the following lines where 19 is the next proceeding number:

    1. Configure JVM argument for Non-Government Azure tenant.

      wrapper.java.additional.19=-DExchangeServiceURL="https://outlook.office365.com/"
wrapper.java.additional.20=-DAzureTokenURL="https://login.microsoftonline.com/"
wrapper.java.additional.21=-DAzureAuthorizationURL="https://login.microsoftonline.com/"
wrapper.java.additional.22=-DIsGcchAzureAccount=true
wrapper.java.additional.23=-DAzureAuthorizationScope="offline_access%20https://graph.microsoft.com/.default"

    2. Configure JVM Arguments for GCC High/Azure Government tenant.

      wrapper.java.additional.19=-DExchangeServiceURL="https://outlook.office365.us/"
wrapper.java.additional.20=-DAzureTokenURL="https://login.microsoftonline.us/"
wrapper.java.additional.21=-DAzureAuthorizationURL="https://login.microsoftonline.us/"
wrapper.java.additional.22=-DIsGcchAzureAccount=true
wrapper.java.additional.23=-DAzureAuthorizationScope="offline_access%20https://graph.microsoft.us/.default"

  6. Save and close the file.

  7. Restart WHD.

  8. Configure your incoming email account for Microsoft 365.

Update the WHD configuration file for WHD running on macOS or Linux server

  1. Log in to your WHD server as an administrator.

  2. Navigate to:

    <WebHelpDesk>/conf

    where <WebHelpDesk> represents the WHDhome folder.

  3. Open the whd.conf file in a text editor, (for example, Notepad).

  4. At the end of the file, add the following lines:

    • Configure JVM argument for Non-Government Azure tenant.

      JAVA_OPTS="-DExchangeServiceURL=https://outlook.office365.com/"
JAVA_OPTS="-DAzureTokenURL=https://login.microsoftonline.com/"
JAVA_OPTS="-DAzureAuthorizationURL=https://login.microsoftonline.com/"
JAVA_OPTS="-DIsGcchAzureAccount=true"
JAVA_OPTS="-DAzureAuthorizationScope=offline_access%20https://graph.microsoft.com/.default"

    • Configure JVM Arguments for GCC High/Azure Government tenant.

      wrapper.java.additional.19=-DExchangeServiceURL="https://outlook.office365.us/"
wrapper.java.additional.20=-DAzureTokenURL="https://login.microsoftonline.us/"
wrapper.java.additional.21=-DAzureAuthorizationURL="https://login.microsoftonline.us/"
wrapper.java.additional.22=-DIsGcchAzureAccount=true
wrapper.java.additional.23=-DAzureAuthorizationScope="offline_access%20https://graph.microsoft.us/.default"
wrapper.java.additional.24=-DMicrosoftGraphServiceRoot="https://graph.microsoft.us/v1.0"

  5. Save and close the file.

  6. Restart WHD.

  7. Configure your incoming email account for Microsoft 365.

Verify your Exchange Online account settings

Log in to your Exchange account and verify that Multi-factor Authentication for Microsoft 365 is enabled. See Set up multi-factor authentication located on the Microsoft Docs website for details.

Obtain an Azure account

See the Microsoft Azure website located at azure.microsoft.com for details.

An Azure administrator account is not required.

Register WHD in Azure as an application

  1. Log in to WHD as an administrator.
  2. Click Setup > General > Options.

  3. In the General Options page, locate the Server DNS Name field.

  4. Update the Server DNS name field with your server DNS name.

    Do not enter localhost, as this server DNS name does not resolve outside of the WHD server.

  5. Record the new server DNS name and SSL port number for a future step.

  6. Open a web browser and navigate to:

    https://portal.azure.com/#home

    Do not close WHD.

  7. On the Home page under Azure services, click Azure Active Directory.
  8. In the navigation pane under Manage, click App registrations.

  9. Click the New registration tab.

    (Screenshot property of ©2021 Microsoft Corporation)

  10. Under Name, enter a display name for WHD.

    For example, Web Help Desk.

  11. Under Supported account types, select the Single tenant option.

  12. Under Redirect URI (optional), create a redirect URI in the following format using the WHD server DNS name and port number you retrieved in a previous step:

    https://<Server_DNS_Name>:<Port>/helpdesk/oauth-redirect

    For example:

    https://localhost:8443/helpdesk/oauth-redirect

  13. Save the application.
  14. In the navigation pane, click App registrations.

  15. Under Display name, click the Web Help Desk application.

    The Web Help Desk application details display.

  16. Record the client and tenant ID values and save them to a text file.

  17. In the navigation menu, click API Permissions.
  18. Click Add a new permission.
  19. Click the "APIs my organization uses" tab.

  20. Search for and select the following permission:

    Office 365 Exchange Online

    When you are finished, EWS.AccessAsUser.All should be your only permission, as shown below.

  21. Select Delegated permissions, and then maximize EWS.

  22. Under EWS, select:

    EWS.AccessAsUser.All

  23. Remove any other pre-existing permissions from the remaining permission drop-down menus.

    When you are finished, you should have one permission.

  24. Click Grant admin consent for {your tenant}, which allows an admin to grant admin consent to the permissions configured for the application. When you select the button, a dialog is shown requesting that you confirm the consent action.

    After you have granted consent, the permissions that required admin consent are shown as having consent granted:

    • If you aren't an admin or if no permissions have been configured for the application, the Grant admin consent button is disabled.

    • If permissions were granted but not yet configured, the admin consent button prompts you to handle these permissions. You can add them to configured permissions or remove them.

  25. In the navigation menu, click Certificates & Secrets.

  26. Under Client secrets, click new client secret.

  27. Under Add a client secret, select an expiration date.
  28. (Optional) Enter a description.
  29. Click Add.
  30. At the bottom, locate the Client Secret with the new client secret code.

  31. Copy the client secret code Value ID to a text file.

    Store this text file in a safe location. This code is unique and cannot be retrieved when you close the window.

Create a new incoming email account for your Microsoft 365 email

If required, you can change the frequency that WHD checks for new email.

Shared Microsoft 365 incoming email accounts are not supported.

  1. In WHD, click Setup > email > Incoming Mail Accounts.

    Do not close Azure.

  2. Click New.
  3. Select the email Account tab.

  4. In the email Address field, enter the email address used by WHD to receive WHD requests.

    To prevent WHD from sending nonstop ticket updates, use a real email address. Do not use an alias.

  5. In the Account Type row, select Exchange/Office 365.

  6. For Authentication Mode, select OAuth.

    The Incoming Mail Server row displays the Microsoft Office 365 option with three additional fields.

    Field Description
    Tenant ID The ID number linked to your domain (such as solarwinds.com).
    Client ID The ID number that is unique for each registered Azure application (such as WHD).
    Client Secret

    The encrypted password generated by Azure.

  7. Locate the text files that include the client ID, tenant ID, and the client secret values you saved from Azure.

  8. Paste the values from your text files into the relevant fields in your new email account.

  9. Click Authorize.

    You are redirected to the Microsoft Login page.

    If authorization is required from your Azure administrator account, see this KB article located on the SolarWinds Support website for instructions.
  10. In the Pick an account dialog box, select the Web Help Desk incoming email credentials monitored by WHD.

  11. In the Permissions requested dialog box, review the permission requests from your WHD account. These requests may include:

    • Access your mailboxes
    • Sign you in and read your profile.

  12. Click Accept.

    If the authorization is successful, you are redirected back to the Incoming Mail Accounts page in WHD. Under Client Secret, Authorized displays with a green indicator. The new incoming mail account is linked with Azure.

    If the authorization is not successful and you receive an error, verify that the redirect URI you entered in Azure includes the correct server DNS and port listed in Setup > General > Options.

  13. Click the Outgoing Mail Account drop-down menu and select your outgoing email account.

    This account is used to send email for this account. This includes automated replies to email sent to this account, or tickets with a request type that matches what is linked to this account.

  14. Click the Tech Group drop-down menu and select the tech group used to filter the available request types below.

    New tickets created from this Microsoft 365 email account will be given the selected request type.

  15. Click the Request Type drop-down menu and select the request type that is assigned to tickets created from all incoming email.

    Ensure that the request type is supported by the selected tech group.

  16. Leave the Allow Auto-submitted email check box and Advanced email Properties field blank.

    If your email server fails incoming email tests, you can use these options for troubleshooting.

  17. Disable your current incoming email account (if applicable).

  18. Click Enable email Tickets.

  19. Click Save.

    The Mailer Daemon begins parsing your Microsoft 365 email to your new incoming email account.

Renew an expired Microsoft 365 token

The O365 OAuth refresh token lifespan is fixed at 90 days. After 90 days, the token expires, breaking the connection to the O365 mailbox. When this occurs, an error message similar to the following is recorded in the Incoming Mail Account history:

Error processing mailbox messages: OAuth token request failed (statusCode: 400): invalid_grant [700082] AADSTS700082: The refresh token has expired due to inactivity. The token was issued on 2020-05-11T17:20:18.9364763Z and was inactive for 90.00:00:00.

To avoid interruption with your incoming email account, re-authorize the O365 OAuth token periodically before it expires.

  1. Log in to Web Help Desk as an administrator.
  2. Click Setup > Email > Incoming Mail account.
  3. Click the incoming account for your Microsoft 365 email.

  4. In the Incoming Mail Server options, click Re-Authorize to refresh your token store with new tokens.

  5. Click Save.

Troubleshoot connection issues

If you receive an error when you save your Exchange incoming email account, do the following:

  1. Access your Exchange server and verify that Server Manager > Tools > Exchange Server IIS Manager > EWS > Basic Authentication is set to Enabled.
  2. If SSL is enabled, ensure that your security certificate (self-signed or CA-issued) to the local Java's trusted certificates.
  3. When you are finished, save the incoming mail email account again.