Configure an incoming e-mail account for Office 365

Beginning in October 2020, Microsoft will disable Basic Authentication for Exchange Web Services (EWS). This API allows you to access your Office 365 email, as well as other Exchange-related items. This authentication method requires a username and password to access your Exchange email.

If you use Office 365 for your incoming e-mail, create a new incoming e-mail account in WHD and link this account 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 e-mail. This ensures that all e-mail correspondence between your Office 365 e-mail 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.

To configure a new incoming e-mail account for Office 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 e-mail account in WHD for your Office 365 e-mail.

Verify your Exchange Online account settings

Log in to your Exchange account and verify that Multi-factor Authentication for Office 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, record the server DNS name and assigned port.

    For example, record localhost and 8443.

  4. Open a web browser and navigate to:

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

    Do not close WHD.

  5. On the Home page under Azure services, click Azure Active Directory.
  6. In the navigation pane under Manage, click App registrations.
  7. Click the New registration tab.

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

    For example, Web Help Desk.

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

  10. 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/oath-redirect

    For example:

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

  11. Save the application.
  12. In the navigation pane, click App registrations.
  13. Under Display name, click the Web Help Desk application.

    The Web Help Desk application details display.

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

  15. In the navigation menu, click API Permissions.
  16. Click Add a new permission.
  17. Scroll down and click Exchange.
  18. Select Delegated permissions, and then maximize EWS.
  19. Under EWS, select:

    EWS.AccessAsUser.All

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

    When you are finished, you should have one permission.

  21. In the navigation menu, click Certificates & Secrets.
  22. Under Client secrets, click new client secret.

  23. Under Add a client secret, select an expiration date.
  24. (Optional) Enter a description.
  25. Click Add.
  26. At the bottom of the screen, locate the Password with the new client secret code.
  27. Copy the client secret code 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 e-mail account for your Office 365 e-mail

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

  1. In WHD, click Setup > E-Mail > Incoming Mail Accounts.

    Do not close Azure.

  2. Click New.
  3. Select the E-Mail Account tab.
  4. In the E-Mail Address field, enter the email address used by WHD to create new tickets.

    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 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.

  10. In the Pick an account dialog box, select your Azure account.
  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 e-mail for this account. This includes automated replies to e-mail 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 Office 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 E-Mail check box and Advanced E-Mail Properties field blank.

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

  17. Disable your current incoming e-mail account (if applicable).
  18. Click Enable E-Mail Tickets.

  19. Click Save.

    The Mailer Daemon begins parsing your Office 365 e-mail to your new incoming e-mail account.

Renew an expired Office 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 Office 365 e-mail.
  4. In the Incoming Mail Server options, click Re-Authorize to refresh your token store with new tokens.

  5. Click Save.

Troubleshooting 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.