Office365

If your organization uses Outlook via Microsoft Office365 to manage email, you can use the Office365 plugin to access Outlook mailboxes. Use this plugin to monitor incoming messages to find suspicious email, trigger other actions, forward email for further analysis, and many other email actions. Find the full list of available triggers or actions in the plugin documentation.

When setting up an Office 365 connection for the first time, you must register a new application in Microsoft Azure Active Directory.

Collect Configuration Information

Before you configure an Office365 connection, you will need to collect these parameters from the Microsoft Azure Active Directory:

• Directory ID
• Application ID
• Secret Key

We recommend copying and pasting these values into a temporary document while you collect them, as you will need to enter them into InsightConnect later.

To find parameter information in the Azure Portal:

1. Log into your Azure Portal at https://portal.azure.com.
2. In the side navigation of the Azure Portal, click Azure Active Directory, then Properties in the secondary navigation menu.
3. Copy and save the Directory ID on the Properties page.
4. In the secondary navigation menu, click App Registrations, then + New Application Registration. If you are using Microsoft Azure's new App Registrations experience, this button may be called + New Registration.
5. Complete the form with InsightConnect for the name, "Web app/API" for the application type, and https://login.microsoftonline.com for the sign-on URL. Then click Create.
6. Save the application registration to Azure, then copy and save the Application ID.
7. Click Settings for the newly registered application, then click Keys in the menu that appears. If you are using Microsoft Azure's new App Registrations experience, this tab may be called Certificates & Secrets instead.
8. Create a new key using the steps below.

Create a New Key

Azure uses asymmetric keys to authenticate and secure communications with other applications. You will need to create a new key in Azure to use for configuring InsightConnect connections.

To create a new key in the legacy Azure experience:

1. Navigate to the "Keys" page in the Azure Portal using the steps in the Collect Configuration Information section.
2. In the "Passwords" section, enter a key description or name for the key you will create. You can name the key "InsightConnect" or follow any naming schemes you use.
3. Choose a duration for the life of the key. It will expire when the duration you set ends. Then click Save at the top of the page.
4. Azure will generate a value for your new key. Copy and save this string now, as you will not be able to retrieve it after you leave this page in the Azure Portal.

To create a new key in the new Azure experience (11/2018-onward):

1. Navigate to the "Certificates & Secrets" page in the Azure Portal using the steps in (doc:office365#collect-configuration-information-in-azure).
2. In the "Client Secrets" section, click + New Client Secret to create a new key.
3. Give the key a description -- this also serves as your key's name.
4. Choose a duration for the life of the key. It will expire when the duration you set ends. Then click Add.
5. Azure will generate a value for your new key. Copy and save this string now, as you will not be able to retrieve it after you leave this page in the Azure Portal.

Configure Application Permissions

After registering InsightConnect in Azure, you will need to configure every permission needed for Office365 to successfully provide data to InsightConnect. You won’t need all the permissions available in Azure for accessing Outlook.

The permissions needed to monitor and send email are:

• Read and write user mailbox settings
• Read User mailbox settings
• Read user mail
• Read and write access to user mail
• Send Mail as a user
• Read and write mail in all mailboxes
• Read all user mailbox settings
• Read Mail in all mailboxes
• Read and Write all user You may also see these settings in a format like Mail.Read or Mail.ReadWrite. Make sure to select all permissions matching the list above.

To configure application permissions in the legacy Azure experience:

1. Click on Required Permissions in the Settings panel for your app registration.
2. Click + Add at the top of the page.
3. Click Select an API, then Microsoft Graph. Click Select to continue.
4. Select any and all permissions that you need to provision to InsightConnect in order to use the Office365 plugin actions. You should have the permissions above selected.
5. Click Select and then Done once you are satisfied with your permissions.
6. You should now be back on the "Required Permissions" page. Click Grant Permissions at the top of the page, then Yes.
7. When the success notification appears in the top right, Office365 is ready for use with InsightConnect.

To configure application permissions in the new Azure experience (11/2018-onward):

1. Click on the API Permissions tab for your app registration.
2. Click + Add a Permission.
3. Choose Microsoft Graph. It will most likely be the first and largest button on the "Select an API" page.
4. Click Application Permissions.
5. Select any and all permissions that you need to provision to InsightConnect in order to use the Office365 plugin actions. You will most likely need to select permissions from the "Directory," "MailboxSettings," "Mail," and "User" categories, so thoroughly check that the permissions you grant to InsightConnect correspond to the plugin actions listed in the Overview of Office365 plugin documentation. You should have the permissions above selected.
6. When the "Admin Consent Required" column for Microsoft Graph says "Granted for test," Office365 is ready for use with InsightConnect. Contact Microsoft support if you have issues with admin consent.

Configure a New Office365 Connection in InsightConnect

After you collect the information above in your Azure Portal, you can configure connections to Office365 in InsightConnect. Configure the connection name, where it should run, and credentials as you normally would.

To configure the parameters for an Office365 connection:

1. Collect all parameter information you obtained from the Azure Portal.
2. Choose a credential to use with Office365. The first time you create a credential for Office365, you will be prompted to name the credential and add a Secret Key. Paste the Azure Private Key Value here. Otherwise, if you choose an existing credential, the Secret Key field will automatically populate with the information from that credential.
3. Paste your Directory ID into the "Tenant ID" field.
4. Paste your App ID into the "App ID" field.
5. Click Continue to configure the rest of the workflow trigger or step.
6. InsightConnect will automatically run a test for the connection. Learn more here.

Troubleshoot the Office365 Plugin

If you are having problems configuring your Office365 plugin, find solutions to common problems here.

Office365 will not authorize

If your Office365 plugin fails to authorize, check the plugin’s error logs. If you see anything like the following, you did not receive an authorization token after configuring an Office365 connection.

 
1
Updating auth token…
2
Auth request: <Response [400]>
3
{"error":"invalid_request","error_description":" …

It is likely that the connection settings are invalid. Verify that the App ID, Tenant ID, and Secret Key are correct in your Office365 connections.

Office365 trigger does not work

If a correctly configured Office365 trigger fails to run a workflow when you know it should, it is likely that the permissions in Office365 are incorrect. Verify that your application has the Mail.Read and Mail.ReadWrite permissions selected in Azure Active Directory. Also, verify that the administrator of your tenant consented to the correct application permissions. More information can be found at these Microsoft resources: https://docs.microsoft.com/en-us/graph/auth-v2-servicehttps://docs.microsoft.com/en-us/graph/permissions-reference

Known Limitations

A maximum of 10 items per mailbox can be removed at one time. Because the capability to search for and remove messages is intended to be an incident-response tool, this limit helps ensure that messages are quickly removed from mailboxes.

The maximum number of mailboxes in a Content Search that you can delete items in by doing a search and purge action is 50,000. If the Content Search has more than 50,000 source mailboxes, the delete action will fail. Visit https://docs.microsoft.com/en-us/office365/securitycompliance/search-for-and-delete-messages-in-your-organization for more information.