Onboarding Microsoft 365 [API]

This page includes:

About onboarding Microsoft 365 using the Microsoft API

You can connect your Microsoft 365-based email services to "Acronis Email Security" – using the Microsoft Graph API. This is called the Microsoft API connection method.

This page describes how to integrate "Acronis Email Security" with Microsoft 365 using the Microsoft API connection method. For details on how to integrate "Acronis Email Security" with Microsoft 365 using the inline connection method, see Step 1 - Onboarding Microsoft 365 [Inline].

Note: With Microsoft 365 API integrations, "Acronis Email Security" scans email messages up to a maximum size of 500 MB [including attachments].

By default, the Microsoft 365 integrations monitor incoming emails only - not outgoing emails, nor internal emails. [Internal emails are emails that are sent between protected domains in the same organization.]

Note:

  • After onboarding a Microsoft 365 - API integration, you can change the set of assets that are protected by "Acronis Email Security". Changing the set of assets includes:

    • deleting any of the specified domains, groups, or users

    • specifying additional domains, groups, or users

    For details, see Editing the protected assets.

  • You can specify a maximum of 300 assets [domains, groups, and users] to protect.

A bit more about the Microsoft 365 API integration

Onboarding process

  • API scanning initiates by creating a Webhook for each user within the Microsoft 365 environment.

Protection mechanism

  • When a user is protected by "Acronis Email Security" Microsoft 365 API integration, the scan activates upon the arrival of an inbound email.

  • Microsoft 365 triggers a notification to the scanning system about a new email in the user's Inbox.

  • The system retrieves the email's metadata and EML file copy for analysis.

Scan and response

  • Clean: If an email is assigned a clean verdict, the email remains in the user's Inbox - without any intervention.

  • Spam: By default, spam emails are moved to the Junk Email folder via Microsoft Graph API's REST API calls.

  • Malicious: By default, malicious inbound emails are moved to a hidden [not visible] folder [called pp-quarantine] inside the user's mailbox. The hidden folder is created the first time that a scan is assigned a malicious verdict for that user.

    Note that the hidden folder may be revealed:

    • During the first 24 hours after the Microsoft 365 API integration is performed.

    • When you search for an email inside Outlook.

    • When using archived mailboxes.

    When an email is moved to the quarantine folder, the subject of the quarantined email is changed to "Quarantined Email" and the content [body] of the quarantined email is changed to "This Email has been quarantined." If the quarantined email is subsequently found to be clean or spam [junk], the original subject and contents are restored to the email when it is released.

    Note: A hidden pp-quarantine folder is created only when the Microsoft 365 API integration is configured - not when any of the other email integrations are configured.

  • Limitation: If the recipient has already deleted the email before the scan is completed, then the email will remain in the Deleted Items folder or the Trash folder - and will therefore not be quarantined.

How to onboard Microsoft 365 using the Microsoft API

This onboarding procedure for a Microsoft 365 API integration includes:

  • Specifying the connection method.

  • Enabling the "Acronis Email Security" app - that enables the required access to your Microsoft 365 account.

  • Specifying who to protect [the plan].

  • Initiating the connection process.

To onboard Microsoft 365 using the Microsoft API:

  1. Select Settings > Bundles and Channels.

  2. Under Enabled Channels, locate Email Service, and then click Email service configuration [] on the right.

    Note: Depending on your version of "Acronis Email Security", you may need to click on the Add Services icon [] on the right side of the "Acronis Email Security" banner.

  3. Click Add A New Email Service - if this option appears.

  4. Select the Organization - if necessary.

  5. Specify the Escalation contacts. For details, see Escalation contacts.

  6. In Email Service, select Microsoft 365.

  7. In Connection Method, select Microsoft API.

    1. Inbound: Will be automatically selected. This configures "Acronis Email Security" to scan emails that are received from outside the organization.

    2. Outbound: [Optional] This configures "Acronis Email Security" to scan emails that are sent from inside the organization. This option appears only if outbound scanning is enabled. For details, see Onboarding Microsoft 365 - Outbound.

      Note: By default, internal email is not monitored. To add monitoring for internal email, contact "Acronis Email Security" Support [support@perception-point.io]. There may be additional licensing requirements for enabling internal scanning.

  8. Click ENABLE M365 APP - in the bottom right corner. [This is the remediation app.]

    Important: If the ENABLE M365 APP button is not enabled, make sure that you have specified an escalation contact above.

    1. A pop-up window will open - allowing you to sign-in to your Microsoft account.

      Note: If the pop-up does not appear, make sure that pop-ups are not blocked on your computer.

    2. Sign-in to your Microsoft account as a global admin.

      Important: The account must have admin permissions in the Microsoft 365 tenant.

      • If your Microsoft 365 account doesn't have global admin permissions in the Microsoft 365 tenant, then to perform the onboarding process, you can use another account that does have global admin permissions.

      • The Microsoft 365 global admin that you use to perform the onboarding process doesn't need to be an admin user in "Acronis Email Security".

      • The Microsoft 365 global admin that you use to perform the onboarding process must be a "permanent" account - and can't be deleted after performing the onboarding process.

      • If you use another Microsoft 365 account [that has global admin permissions in the Microsoft 365 tenant] to perform the onboarding process, then you will still have full permissions within "Acronis Email Security" [according to your user-roll].

      You'll see a list of the permissions that are required by the "Acronis Email Security" app.

    3. Click Accept.

      The next step in the onboarding wizard appears.

  9. Specifying who to protect [Microsoft 365 - API]

    [This is also known as the plan.]

    1. Protect the organization's entire Microsoft 365 account: Protects all email addresses in all the domains that are included in your organization's Microsoft 365 account.

      Note: Domains and email addresses that are added in the future to the organization's Microsoft 365 account will be automatically protected - it is not necessary to make any changes in "Acronis Email Security".

    2. Protect the following entities only: Allows you to specify which domains, groups, and users [email addresses] to protect.

      Note:

      • After onboarding a Microsoft 365 - API integration, you can change the set of assets that are protected by "Acronis Email Security". Changing the set of assets includes:

        • deleting any of the specified domains, groups, or users

        • specifying additional domains, groups, or users

        For details, see Editing the protected assets.

      • You can specify a maximum of 300 assets [domains, groups, and users] to protect.

      Specific domains

      Protects only the domains that you specify. All users inside the specified domains will be protected.

      Note:

      • Email addresses that are added [in Microsoft 365] in the future to any of the specified domains will also be protected.

      • Domains that are added to the organization's Microsoft 365 account won't be automatically protected. For details, see Adding a domain to an existing integration.

      [It may take up to 24 hours for a new or modified entity to be added or updated in "Acronis Email Security".]

      Specific groups and users

      Protects only the groups and users that you specify.

      Note:

      • Groups can be any of the following group types: Microsoft 365; Distribution; Mail-enabled security

      • Dynamic distribution lists are not supported.

      • Nested groups are not supported [only direct members are included]

      • Where required, specify the group email ID.

      • Email addresses that you specify must be included in your Microsoft 365 account.

      • Email addresses that are added in the future [in Microsoft 365] to any of the specified groups will also be protected.

        [It may take up to 24 hours for a new or modified entity to be added or updated in "Acronis Email Security".]

      Specific domains, groups and users

      Protects all the domains, groups, and users that you specify.

      Note:

      • Groups can be any of the following group types: Microsoft 365; Distribution; Mail-enabled security

      • Dynamic distribution lists are not supported.

      • Nested groups are not supported [only direct members are included]

      • Where required, specify the group email ID.

      • Email addresses that you specify must be included in your Microsoft 365 account.

      • Email addresses that are added in the future [in Microsoft 365] to any of the specified groups will also be protected.

        [It may take up to 24 hours for a new or modified entity to be added or updated in "Acronis Email Security".]

      Note about future changes:

      • Domains that are added to your Microsoft 365 account in the future will not be protected.

      • Email addresses that are added in the future [in Microsoft 365] to any of the specified domains or groups will also be protected.

        [It may take up to 24 hours for a new or modified entity to be added or updated in "Acronis Email Security".]

      • Email addresses that are added to your Microsoft 365 account [outside of the specified domains and groups] in the future will not be protected.

  10. [This step may not appear] Select to where spam emails will be moved - to the user's Inbox or the Junk folder - if spam emails are not configured to be quarantined.

    • Inbox: The email is sent to the user's Inbox. This setting is typically used for PoC installations - not for production installations.

    • Junk: The email is sent to the user's Junk folder. This setting is typically used in production installations - not in PoC installations.

      This setting can be changed after on-boarding. For details, see Configuring spam remediation below.

  11. Click Next. A summary of your selected configurations will be displayed.

  12. Review the configurations, and then click Done. This will begin the connection process to protect the users that you specified above. This connection process may take a while to complete.

  13. Click the blue Microsoft 365 link [see graphic above] to open the Settings > Bundles and Channels page - where you can monitor the API connection status:

    Active

    All the users in the domain are either connected or are on-premise [and therefore not connected].

    Partially connected

    Some users in the domain are connected, but there are some users that couldn’t be connected.

    This may be because the mailboxes are non-operative.

    Error

    No users in the domain could be connected.

    This may be because the mailboxes are inactive, soft-deleted, or hosted on-premise.

    Empty

    No users were found in the domain.

    Details

    Connected email addresses

    The number of users that are protected by "Acronis Email Security".

    Non-supported email addresses (on-prem)

    The number of Microsoft Exchange users that are included in the plan that you specified. These users will not be protected by "Acronis Email Security".

    This value is applicable in "Microsoft 365 - Exchange" hybrid environments.

    Non-operative email addresses

    The number of users that are included in the plan that you specified, but for whom "Acronis Email Security" was not able to add protection during the connection process.

    Total email addresses

    The number of users included in the plan: connected, non-supported, and non-operative.

    [This excludes invalid users in the plan.]

    This information will be displayed for 30 days after the connection process is completed.

    When the In Progress indicator changes to Completed, the users included in the plan will be protected.

  14. If you want to configure this Microsoft 365 integration to operate in monitoring mode, continue with Configuring monitoring mode below.

Configuring monitoring mode

Important: Perform this procedure only if you want your Microsoft 365 API integration to operate in monitoring mode.

Monitoring mode is typically used for PoC implementations.

In monitoring mode [also known as passive, silent, or detection mode], "Acronis Email Security" will not:

  • quarantine malicious emails

  • route spam to the Junk folder

To configure the API integration to operate in monitoring mode:

  1. Open the Settings > Bundles and Channels page.

  2. On the right, click Default Channel Settings.

  3. Click Edit [].

  4. Under Detection, clear the Malicious, Restricted, and Spam check boxes.

  5. Click Save.

  6. Open the Settings > Bundles and Channels page.

  7. Under Enabled Channels, on the right of Email Service > Microsoft 365, click Channel Settings. The "Email Service Settings" sidebar opens.

  8. Click Edit [].

  9. Under Microsoft Settings Options > "Move spam emails that are not quarantined to", select Inbox.

  10. Click Save.

    Your Microsoft 365 API Integration is now configured to operate in monitoring mode.

    "Acronis Email Security" will not quarantine any malicious emails or route spam to Junk folders.

Configuring feedback emails [Optional]

By default, the "Acronis Email Security" IR Team won't send feedback to end-users that report email messages using the Report Message button. However, you can configure "Acronis Email Security" so that the "Acronis Email Security" IR Team will send feedback to end-users that report email messages. For details, see Alerts.

Adding protected Assets [domains, groups, and users]

After you have configured a Microsoft 365 API integration, you can add domains, groups, and users to the list of assets that are protected.

Note: You can add domains, groups, and users only if your are protecting just a specified set of assets [partial protection] - and not the entire Microsoft 365 account. For details, see Full protection vs Partial protection.

To add domains, groups, and users to the list of assets that are protected:

  1. In "Acronis Email Security", go to Settings > Protected Email Assets.

  2. Click "Configure Email Protection" in the top-right corner. This will open the configuration wizard.

  3. In the wizard, use the available controls to add the required domains, groups, and users.

  4. Click Next to continue with the required configuration changes.

Note: You can also click "Add Domains", "Add Groups", or "Add Users" on the right of the relevant section. A pane will open on the right - enabling you to add the required assets.

Configuring protected assets [domains, groups, and users]

After you have configured a Microsoft 365 API integration, you can configure [edit] the protected assets, as shown below.

Note: You can configure protected assets only if your are protecting just a specified set of assets [partial protection] - and not the entire Microsoft 365 account. For details, see Full protection vs Partial protection.

  • Adding assets

To add a domain, group, or user:

  • Click "Add Domains", "Add Groups", or "Add Users" on the right of the relevant section. A pane will open on the right - enabling you to add the required assets.

    or

  1. In "Acronis Email Security", go to Settings > Protected Email Assets.

  2. Click "Configure Email Protection" in the top-right corner. This will open the configuration wizard.

  3. In the wizard, use the available controls to add the required domains, groups, and users.

  4. Click Next to continue with the required configuration changes.

  • Enabling assets

  • Disabling assets

  • Deleting assets

You can use the functionality on the Protected Email Assets page to enable, disable, or delete any of the protected assets [domains, groups, and users].

The required controls are found on the right of each protected asset.

Configuring spam remediation

Configuring a Microsoft 365 API integration includes specifying what happens to emails that are assigned a spam verdict [if spam emails are not configured to be quarantined]. The options are:

  • Inbox: The email is sent to the user's Inbox. This setting is typically used for PoC installations - not for production installations.

  • Junk: The email is sent to the user's Junk folder. This setting is typically used in production installations - not in PoC installations.

With the Microsoft 365 API integration, "Acronis Email Security" may move an email from the Inbox to the Junk folder after the email has initially arrived in the Inbox. The procedure is therefore referred to as "spam remediation".

When a Microsoft 365 API inbound integration is initially configured, the spam remediation is set to Junk.

Note: The "spam remediation" functionality will apply only if:

  • You don't have any contradicting rules in your Microsoft email account. For details, contact "Acronis Email Security" Support [support@perception-point.io].

  • Spam emails are not configured to be quarantined. If Spam emails are configured to be quarantined, then Spam emails will be sent to quarantine, and not sent to the Junk folder. For details, see Which verdicts cause quarantine.

The spam remediation controls appear only if a Microsoft 365 API inbound integration is configured. The controls don't appear if a Microsoft 365 Inline integration is configured.

To change the spam remediation location:

  1. Open the Settings > Bundles and Channels page.

  2. Under Enabled Channels, on the right of Email Service > Microsoft 365, click Channel Settings. The "Email Service Settings" sidebar opens.

  3. Click Edit [].

  4. Under Microsoft Account Options > "Move spam emails that are not quarantined to", select Junk or Inbox.

  5. Click Save.

Calendar invites

Scenario

  • You are using the Microsoft 365 API integration.

  • An email is determined to be malicious - after the email has already reached the recipient’s Inbox.

  • The email includes a calendar invite - typically as a .ics attachment.

Results

  • The email is quarantined [if this is configured].

  • The invite may be automatically added to the user's calendar.

  • "Acronis Email Security" is unable to delete the invite from the calendar.

  • Only a Microsoft tenant global admin can delete the invite.

Note: If you are using the Microsoft 365 Inline configuration and a malicious calendar invite is detected during the initial scan, the email and all attachments (including the invite) will be quarantined and will not reach the recipient’s Inbox.

For additional details, see Comparing the Microsoft 365 Inline and API integration methods.

See also: