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

Configure an outgoing email account for Microsoft 365

On this page

Introduction

If you use Microsoft 365 (previously called Office 365) for your outgoing email, create a new outgoing 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 send 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.

Currently an outgoing email account for Microsoft 365 email is not supported for GCC High/Azure Government tenants.

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

  1. Register WHD in Microsoft Azure as an application with Microsoft APIs.

  2. Update the WHD configuration file.

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

  3. Create a new outgoing email account for your Microsoft 365 email.

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.

Step 1: 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 WHD server 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.Send Send mail as a user Allows the app to send mail as you.
    Mail.Send.Shared Send mail on behalf of others Allows the app to send mail as you or on behalf of someone else.

    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 are not the tenant 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 WHD Certificates & 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.

Step 2: Update the WHD configuration file

To update the WHD configuration file for WHD running on a 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 lines below 19 is the next proceeding number. 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"

  6. Save and close the file.

  7. Restart WHD.

To 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 WHD home folder.

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

  4. At the end of the file, add the lines below. 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"

  5. Save and close the file.

  6. Restart WHD.

Step 3: Create a new outgoing email account for your Microsoft 365 email

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

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

    Do not close Azure.

  2. Click New.

  3. Click the SMTP Authentication drop-down menu and select Exchange/Office 365.

  4. Click Make Default to configure this account for sending all non-ticket email messages and any ticket messages for incoming mail accounts linked to the default. Otherwise, leave this field as is.

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

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

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

  7. 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.
  8. In the Pick an account dialog box, select the Web Help Desk outgoing email credentials monitored by WHD.

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

  10. Click Accept.

    If the authorization is successful, you are redirected back to the Outgoing Mail Accounts page in WHD. Under Client Secret, Authorized displays with a green indicator. The new outgoing 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.

  11. Enter a name that displays in the From address field for email sent by this SMTP server.

  12. Enter the email address your customers use to send requests to your Technical Support team. When received, this request is converted into a ticket.

    For example:

    The field only displays if you did not select the following option at Setup > email > Options:

  13. Enter a list of approved domains used by this account for all outgoing emails. If the field remains blank, the email account will send email to all domains.

  14. Enter all email accounts that are linked to this account.

    See Setup > email > Incoming Mail Accounts > [email Account] > Outgoing Mail Account for email account details.

  15. Enter any additional properties sent to the mail engine to change the behavior of mail servers with special needs.

    The following table lists properties you can enter in this field. Enter each property separated by a semicolon and space. For example:

    mail.smtp.ehlo=false; mail.smtp.noop.strict=false; mail.smtp.userset=true

    WHD Technical Support may provide you with additional properties, if required.

    Property Description
    mail.smtp.ehlo=false Used for mail servers that require the legacy HELO command instead of the common EHLO command.
    mail.smtp.noop.strict=false

    Addresses some Microsoft Exchange Server versions that return an incorrect response code to the SMTP NOOP command when a timeout occurs.

    Setting this property to false flags the email engine to expect the incorrect response.

    mail.smtp.userset=true

    Forces the mail engine to send the RSET command in place of the NOOP command.

    Some mail servers respond slowly to the NOOP command.

    mail.smtp.starttls.required=false

    Addresses the following error:

    STARTTLS is required but host does not support STARTTLS

    If disabling SSL is not an option, set this property to false to remove the starttls requirement.

    mail.from.override=yourAddr@yourDomain.com

    Replaces the From address in all mail sent using this account with the address you provide in the property syntax.

    This property overrides the email Address property in the incoming mail account if the Use Incoming Account Mail as "From" address described in step 9 is enabled at Setup > email > Options.

    This property also overrides the Web Help Desk email Address property described in step 9.

  16. Click Save.

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 Outgoing 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 outgoing 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 > Outgoing Mail account.
  3. Click the outgoing account for your Microsoft 365 email.

  4. In the Outgoing 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.