Email configuration

What is email configuration?

Email configuration allows administrators to set up and manage email notifications for various events within the BeyondTrust system, such as session invitations, alerts, and updates.

How is email configuration useful?

Email configuration enables the automation of communication within the BeyondTrust system, ensuring users are promptly notified about important events. It helps streamline support processes and improves communication between administrators, support staff, and customers.

Email events

Email notifications are triggered via the following events:

• During any failover operation, the product version on the primary node does not match the product version on the backup node.
• During a failover status check, any of the following problems are detected.
  • The current B Series Appliance is the primary node and a shared IP address is configured in /login, but its network interface is not enabled.
  • A shared IP address is configured in /login but is not listed as an IP address in /appliance.
  • The backup node could not contact the primary node, and it also could not contact any of the test IP addresses configured on the Management > Failover page.
  • The backup node could not contact any of the test IP addresses configured on the Management > Failover page.
  • The backup node's backup operations are disabled on the Management > Failover page.
  • The backup node unexpectedly failed to perform a probe of itself, indicating that it is malfunctioning.
  • The backup node failed to contact the primary node using the primary node's hostname.
  • Automatic failover is disabled, and the backup node failed to probe the primary node.
  • Automatic failover is enabled, and the backup node failed to probe the primary node. The backup node will automatically become the primary node if the primary node remains unresponsive.
  • Automatic failover is enabled, and the backup node is automatically becoming the primary node because the primary node was down for too long.
  • The primary node failed to perform a data sync with the backup node sometime in the past 24 hours.

How do I access the Email Configuration page?

1. Use a browser to sign in to your Remote Support URL.
   This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
2. From the left menu, click Management.
   The Software page opens and displays by default.
3. At the top of the page, click Email Configuration.
   The Email Configuration page displays.

Set the From address

Your appliance uses this email address to send notifications to your admin contacts.

1. From the left menu, click Management.
   The Software page opens and displays by default.
2. At the top of the page, click Email Configuration.
   The Email Configuration page displays.
3. In the Email Address section, enter the address you want to use to send system notifications.
4. Click Save.
   The email address is set, and emails generate from that address.

ℹ️

If an appliance is designated as a backup appliance or a traffic node, the email configuration for that appliance is overwritten with the email configuration defined on the primary appliance.

Configure your SMTP relay server

Configure your appliance to work with your SMTP relay server to send automatic email notifications of certain events.

1. From the left menu, click Management.
   The Software page opens and displays by default.
2. At the top of the page, click Email Configuration.
   The Email Configuration page displays.
3. In the SMTP Relay Server section, enter the following:
   • SMTP Relay Server: The hostname or IP address of your SMTP relay server.
   • SMTP port: The SMTP port used to contact the SMTP relay server.
   • SMTP encryption: If your SMTP relay server does not support encryption, select None.
     If your relay server does support encryption, select your encryption setting (TLS or STARTTLS) and set the following:
     • Choose a certificate: You can use the appliance's built-in default certificate store, or, if you have a TLS certificate, click Choose a certificate to upload it.
       • Certificates must be in PEM format.
       • Optionally, select Ignore SSL certificate errors. We do not recommend this option.
   • SMTP authentication type: Select one of the following options:
     • None: Select this if you do not use authentication with your relay server.
     • Username and Password: Enter the SMTP username and SMTP Password.
     • OAuth2: Configure this as detailed in the Configure your SMTP Relay Server with OAuth2 for Entra ID or Configure your SMTP Relay Server with OAuth2 for Google sections below.
4. Click Save.
   Your SMTP relay server settings save.

Configure your SMTP Relay Server with OAuth2 for Entra ID

Configuration requires changing specific settings on your appliance and in your Microsoft 365 subscription with Entra ID.

❗️

Important information about Microsoft's deprecation of basic authentication in Exchange Online

What do I have to do?

If you have username and password basic authentication configured as your Authenticated SMTP method in your Microsoft Exchange Online account(s), you must update this to OAuth 2.0 prior to September 2025 to ensure your BeyondTrust email server settings continue to work as expected.

Why do I have to do this?

Microsoft is deprecating their username and password basic authentication in September 2025.
For more information, see Microsoft's Deprecation of basic authentication in Exchange Online notice, or contact Microsoft Support.

ℹ️

Prerequisites

Azure uses "apps" for creating OAuth 2.0 providers. In order to create an OAuth 2.0 app in Azure, you need the following:

• An Azure instance configured for Exchange and Entra ID.
• A user account in Azure with access to create apps in Entra ID.
• Authenticated SMTP enabled in your Exchange Online accounts. See Microsoft's Configure each Microsoft Exchange Online account to enable OAuth2 for procedures.
  • The Authenticated SMTP setting can be overridden by the CAPs in Entra ID. That procedure is out-of-scope for this document.

1. In your Entra ID console, register your appliance:

   ⚠️

   The following is third-party documentation from Microsoft. We recommend you verify these steps via their official documentation: Register your appliance as a new app in Entra ID.

   1. Sign in to portal.azure.com.

   2. Navigate to Microsoft Entra ID.

   3. Click App registrations > New registration.

   4. Enter and select the following:

      • Name: Use a name to identify the appliance/platform.
      • Supported Account Types: Select Accounts in this organizational directory only.
      • Redirect URI (optional): Select Web, and enter https://{URL OF APPLIANCE}/login/smtp-verification.

        ℹ️

        If you plan to use the app for both the appliance and Pathfinder, register both Authorization Redirect URIs with the app:

        1. In the activity pane, click the link under Redirect URIs.
        2. Click Add URI.
        3. Enter the second Authorization Redirect URI.
        4. Click Save.

   5. From the left menu, navigate to the Overview page, and in the activity pane in the center of the page, copy the Application (client) ID value to a text file.

   6. On the same Overview page, click Endpoints.
      An Endpoints dialog box displays.

   7. Copy the OAuth 2.0 authorization endpoint (v2) and OAuth token endpoint (v2) URI URI values from the Endpoints dialog box to a text file.

      📘

      Each Azure app has unique endpoint URIs.

   8. From the left menu, click Manage > Certificates & secrets, and in the activity pane in the center of the page, click the Client Secrets tab.

   9. Click New client secret.

   10. Enter a text value in the Description field.

   11. Select a value from the Expires drop-down.

   12. Click Add.

   13. In the activity pane in the center of the page, copy the Value to a text file.

2. In Remote Support, from the left menu, click Management.
   The Software page opens and displays by default.

3. At the top of the page, click Email Configuration.
   The Email Configuration page displays.

4. In the Email Address section, in the From Address field, enter the address you want to use to send system notifications.

5. In the SMTP Relay Server section, enter the following information:

   • SMTP Relay Server: The hostname or IP address of your SMTP relay server.
     • The default value is smtp.office365.com, but your installation may require a different host name.
   • SMTP port: The SMTP port used to contact the SMTP relay server.
     • The default value for STARTTLS is 587. Other methods may require a different port.

6. For your SMTP Authentication Type, select OAuth2 and enter the following information:

   • Email: Enter the same email used in your Entra ID account. This email must:
     • have permission in Entra ID to send emails, and
     • have permission to send emails as the address you entered in the From Address field in step 4, above.

       ℹ️

       In Entra ID, if you have enabled and configured an Alternate Login ID, you may use any address in this Email field in Remote Support. To enable and configure an Alternate Login ID, see Microsoft's Configuring Alternate Login ID.

   • SMTP OAuth Provider ID: Enter the Application (client) ID you obtained in step 1.v, above.
   • SMTP OAuth Client Secret: Enter the client secret you obtained in step 1.xiii, above.
   • SMTP OAuth Scopes: Enter https://outlook.office.com/SMTP.Send offline_access.
   • SMTP OAuth Authentication Endpoint: Enter the OAuth 2.0 Authorization Endpoint (v2) you obtained in step 1.vii, above.
   • SMTP OAuth Token Endpoint: The OAuth token endpoint (v2) URI Endpoint you obtained in step 1.vii, above.

7. Click Save.
   The settings save.

8. Click Verify OAuth2 Provider.
   A sign-in page displays in a new tab.

9. Accept the permissions request.
   In Remote Support, the Email Configuration page reloads, and the SMTP settings show as Authorized.

OAuth for Microsoft Entra ID and Exchange Online is now configured.

Configure your SMTP Relay Server with OAuth2 for Google

Configure Google Cloud

1. Log in to your Google Cloud Platform console (Google Dev Console) (console.cloud.google.com). Use the correct Gmail account, as only the owner of the project is able to work with the project. If you do not already have a paid account, you may choose to purchase an account by clicking Activate in the top banner. BeyondTrust cannot provide assistance with purchasing an account. Click Learn More in the top banner for information regarding the limitations of free accounts.
2. Click CREATE PROJECT. You can also use an existing project.
3. Accept the default Project Name, or enter a new name.
4. Accept the default Location, or select a folder from those available for your organization.
5. Click CREATE.
6. The APIs and services page appears. Click Library in the left menu.
7. Search or browse for the Gmail API in the library, and click it.
8. The Gmail API appears on its own page. Click ENABLE.
9. The Gmail API Overview page appears. Click APIs & services in the upper left.
10. The APIs and services page appears again. Click OAuth consent screen in the left menu.
11. Select the User Type. Internal allows only users from within the organization, but requires a Google Workspace account.
12. Click CREATE.
13. Enter the App name.
14. Enter a User support email address. This may default to the address you are using to create the project.
15. Enter a logo for the app, if desired. The App domain section is also optional.
16. Add the Authorized domains. For BeyondTrust test appliances, these are:
    • qabeyondtrustcloud.com
    • bomgar.com
17. Enter the Developer contact information. This is the email address you are using to create the project.
18. Click SAVE AND CONTINUE.
19. Under the Scopes tab, click ADD OR REMOVE SCOPES. This opens the Update selected scopes window.
20. Locate and check the scope https://mail.google.com/ for the Gmail API.

ℹ️

Note

The API does not appear if it has not been enabled.

21. Click UPDATE. The Update selected scopes window closes.
22. Click SAVE AND CONTINUE.
23. Under the Test users tab, click ADD USERS. This opens the Add Users window. Add the users that have access to the application and click ADD. Note the limits on test user access and related restrictions.
24. Click SAVE AND CONTINUE.
25. Review the Summary, and make any necessary changes or corrections.
26. Click BACK TO DASHBOARD.
27. Click Credentials in the left menu.
28. Click CREATE CREDENTIALS in the top banner and select OAuth client ID.
29. On the create credentials page, select Web application for the Application type. Additional fields appear when this is selected.
30. Enter a name for the application.
31. Scroll down to Authorized redirect URIs and click ADD URI.
32. Enter the Authorization Redirect URI in the form of https://{URL OF YOUR APPLIANCE}/login/smtp-verification.
33. Click CREATE.
34. A window confirms creation of the OAuth client, and shows the Client ID and Client Secret. Click to download a JSON file. The file contains information that is needed in the next steps.
35. Click OK to return to the APIs and services page.

Provide credentials to the SMTP relay server

1. Within the Remote Support admin interface, navigate to Management > Email Configuration.
2. Under SMTP Authentication Type, select OAuth2, and enter the following information:
   • Email: The email address for the SMTP relay.
   • SMTP OAuth Provider ID: The client_id from the JSON file generated during the Google configuration.
   • SMTP OAuth Client Secret: The client_secret from the JSON file generated during the Google configuration.
   • SMTP OAuth Scopes: Enter https://mail.google.com/.
   • SMTP OAuth Authentication Endpoint: The auth_uri from the JSON file generated during the Google configuration.
   • SMTP OAuth Token Endpoint: The token_uri from the JSON file generated during the Google configuration.
3. Click Save.
4. Now you can verify and connect the provider account. Click Verify Oauth2 Provider.

Set your admin contacts

These contacts are those who will receive notifications from your appliance.

1. From the left menu, click Management.
   The Software page opens and displays by default.
2. At the top of the page, click Email Configuration.
   The Email Configuration page displays.
3. In the Admin Contact section, enter the email address of each contact you want to receive appliance notifications. Separate emails with a comma.
4. Optionally, select the following:
   • Send Daily Communication Notice: This sends a daily notice to ensure communications are working as expected.
   • Send a test email when the settings are saved: This tests the email settings once you click Save in the next step.
5. Click Save.
   Your settings save, and if you selected the Send a test email when the settings are saved option above, a test email sends from the email address at the top of the Email Configuration page.