Allow Code42 access to Microsoft Office 365 email

Last updated
Save as PDF

Overview

To help protect you from data loss, you can use Code42 to investigate attachments sent through users' Microsoft Office 365 Outlook email accounts or mailboxes.

When you add Microsoft Office 365 as a data connection, you must authorize Code42 as a registered client API using your administrator account. Once connected, Code42 monitors your organization's email environment from that point forward to collect information about all attachments emailed by monitored users. That attachment file information then becomes available in Forensic Search for investigation.

This article explains how to add Microsoft Office 365 email as a data connection.

Considerations

The following considerations apply to the Microsoft Office 365 connection. See also the considerations applicable to all email services.

Microsoft Office 365 users must have a subscription that includes Audit (Premium) in order for Code42 to monitor the email attachments they send.
Audit must be turned on in your Microsoft Office 365 environment in order for Code42 to monitor email attachments.
Administrators do not need to have a subscription that includes Audit (Premium) to authorize the Code42 connection. However, if you also want to monitor any email attachments that these administrators send in that environment, then the same subscription requirements apply.

Monitoring and alerting tools may report download activity
When ongoing file activity is detected, Code42 temporarily streams files from your cloud storage or email service to the Code42 cloud to calculate the file hash. (Code42 does not calculate hash value during the initial inventory process.) This may be reported as users downloading files. The requesting service's IP address may point to Microsoft Azure hosts.

Code42 never stores file contents or writes them to disk during this process.

Licensing and subscription requirements

Microsoft license requirements

To connect to your Microsoft Office 365 email environment, Code42 requires a Microsoft license or subscription that includes Audit (Premium). See the Microsoft documentation for more information on Audit (Premium).

User subscription requirements

Due to permissions, Code42 can only monitor the mailboxes in your environment that are assigned to users with a subscription that includes Audit (Premium). After you authorize the connection to your email environment, Code42 scans all users to identify who has a subscription that includes Audit (Premium). Only the emails sent by those users are monitored for attached files.

You can use tools in the Microsoft 365 admin center to view an individual user's licensing or export a list of users who have a specific license.

See the Microsoft documentation for more information on Audit (Premium) and how to assign users the appropriate license or add-on license.

Connect to Microsoft Office 365 email

Connecting Code42 to your Microsoft Office 365 email environment is a two-step process:

Verify that auditing is turned on in your Microsoft environment.
Code42 monitoring requires that audit is turned on
Audit must be turned on in your Microsoft environment in order for Code42 to be able to monitor email attachments sent from your corporate Microsoft Office mailboxes. If auditing is off, Code42 cannot collect data and no file events are displayed in Forensic Search.
If you have one of the Microsoft business licenses, you may need to turn on auditing in your environment before connecting with Code42. Unless it has previously been disabled, customers with a Microsoft enterprise license may already have auditing turned on by default.
Authorize Code42's connection to Microsoft Office 365 email.

Step 1: Verify auditing is turned on for Microsoft Office 365 email

Sign in to the Microsoft Purview compliance portal using your Microsoft global administrator username and password.
Under Solutions in the left navigation pane, click Audit. You may need to click Show all to view Audit in the navigation list.
If auditing is turned off in your environment, the banner at the top of the Search tab prompts you to start recording user and admin activity. This banner does not appear if audit is already turned on.
If prompted, click the banner at the top of the Search tab to turn on audit.
The banner updates to indicate that audit is enabled and you can search for user and admin activity within 24 hours.

Step 2: Authorize the Code42 connection

Connect Code42 to Microsoft Office 365

Sign in to the Code42 console.
Select Administration > Integrations > Data Connections.
Click Add data connection.
The Add data connection panel opens.
From Data connection, select Microsoft Office 365 under Email services.
Enter a display name. This name must be unique.
Code42 prompts you to verify that Audit (Premium) is set up for the users you want to monitor and that auditing is turned on in your Microsoft environment. After you complete those steps, select the I've completed these steps check box and then click Continue.

Add users

Select the scope of email users in your Microsoft Office 365 environment to monitor:
- All: Monitors all Office 365 mailboxes for users with the Audit (Premium) subscription in your environment.
- Specific users: Monitors only the Office 365 mailboxes for the email users you designate.
  1. Click Upload .CSV file.
  2. Select a .csv file containing a list of only those Office 365 email user accounts that you want to monitor. For details, see Upload a .csv file listing Microsoft 365 users below.
- Specific groups: Monitors only the mailboxes of the email users in the Office 365 groups you designate.
  1. Click Upload .CSV file.
  2. Select a .csv file containing a list of Office 365 groups whose user mailboxes you want to monitor. For details, see Upload a .csv file listing Microsoft 365 groups below.
Click Authorize.
The Microsoft Office 365 sign in screen appears.
Enter your Microsoft Office 365 administrator credentials.
Review the terms and agreements, including the requested Office 365 email permissions, and click Accept.
Microsoft Office 365 is added to the Data Connections list as an email data connection.

Permissions can be delayed in Microsoft Azure
The permissions you accept during the authorization process can take up to 1 hour to flow through your Microsoft Azure environment. During this time, Code42 may report an error with the new connection in the Data Connections list. This error clears automatically as soon as Code42 is able to access the Microsoft audit log.

The next time that an attachment is emailed by a user with the required license, information about that file is recorded as an event by Code42. For details, see Attachment metadata below.

Next Steps

Now that you have added Microsoft Office 365 as a data connection, learn more about:

Upload a .csv file

If you select Specific users or Specific groups and click Upload .CSV file, you must upload a .csv file that lists the Microsoft 365 users or groups you want to monitor. Remember that even when you select specific users or specific groups, only the mailboxes for email accounts with subscriptions that include Audit (Premium) in those user or group lists can be monitored by Code42.

General considerations for uploading a .csv file:

The .csv file is limited to 1,000 entries.
Uploading a new .csv replaces the existing list of people or groups being monitored.

Upload a .csv file listing Microsoft 365 users

To export a list of all Microsoft 365 users to a .csv file, see the Microsoft documentation. You can also use PowerShell or Active Directory to obtain a user list and place it in a .csv file.

Create a .csv file from this list that contains only the users whose mailboxes you want to monitor in your Office 365 email environment. List these email addresses under a column header labeled either Email or Email Address.

If no valid entries are found for a user in the .csv file or an invalid column header label is present, the upload produces an error.

Upload a .csv file listing Microsoft 365 groups

To create a Microsoft 365 group, see the Microsoft documentation. The group list supports all Office 365 group types:

Office 365 Group
Security Group
Mail-Enabled Security Group
Distribution Groups

To monitor the mailboxes for users in Microsoft 365 groups, create a .csv file that contains only the groups you want to monitor. In this file, use column headers to identify either the name or the email addresses of those groups.

Code42 reads the display name of groups from the column header labeled Display Name orGroups. In the .csv file, specify this name exactly as it appears in Microsoft 365 or Azure Active Directory.
Alternately, Code42 reads the email addresses of a group from the column header labeled Email or Email Address. In the .csv file, specify the email address associated with each group.

If the .csv file does not contain at least one of these column headers, the upload produces an error.

Code42 looks for the mailboxes of users associated with Microsoft 365 groups as follows:

When a group's name or email address is provided, Code42 attempts to look up users associated with that group name or group email address.
If neither the the group name nor the email address can be found in Microsoft 365, Code42 proceeds to the next entry in the .csv file. Code42 looks for that group or email address again every 8 hours.

As users are added and removed from the monitored groups, Code42 detects these changes within 24 hours and adjusts monitoring of mailboxes accordingly.

Users that are removed from monitored groups have their event history preserved so that it remains searchable in Forensic Search. When an unmonitored user in your Code42 organization emails an attachment to a monitored user, the events associated with that file are not captured because the monitored user is the recipient of the email and not the sender.

Groups that are nested in a monitored group are also monitored.

Attachment metadata

Once you complete authorization, information about email attachments becomes available in Code42 Forensic Search. When an attachment is emailed by a user with the required license, information about that attachment is sent to Code42. This attachment information includes the following:

Filename
Hash, when available
Email address of the sender and recipients

Forensic Search timing
Email attachment information typically becomes available in Forensic Search results within 30 minutes, but may take longer in some cases.

The Date Observed for the event indicates the date and time the attachment was emailed through Microsoft Office 365, not when the file event appeared in Code42.

Required Code42 connection permissions

When a user with the required subscription emails an attachment, Code42 collects information about the attached file along with the sender and recipients for the email.

To see this file activity, Code42 requires access to your Office 365 email environment. The Office 365 email permissions we request are:

ActivityFeed.Read
Files.Read.All
Group.Read.All
Mail.Read
Mail.ReadBasic
User.Read
User.Read.All

Troubleshooting

Microsoft Audit Log is inaccessible

If audit is not enabled (or has been disabled) in your Microsoft environment, the Code42 connection enters an Error status and this error message appears in the details for that data connection:

The Microsoft Audit Log is inaccessable. Re-enable the audit log in Microsoft 365 Compliance Center to return this data connection to monitoring.

To resolve the error, turn auditing on in your Microsoft environment. After you turn on audit, Code42 detects the change and returns the connection to the Monitoring status within 24 hours.

Code42 monitoring requires that audit is turned on
Audit must be turned on in your Microsoft environment in order for Code42 to be able to monitor files shared in your corporate OneDrive cloud storage or email attachments sent from your corporate Microsoft Office email accounts. If audit is off, Code42 cannot collect data and no file events appear in Forensic Search.

If you have one of the Microsoft business licenses, you may need to turn on audit in your environment before connecting with Code42. Unless it has previously been turned off, customers with a Microsoft enterprise license may already have audit turned on by default.

The Code42 application does not have the right permissions

If the connection has been deauthorized in Code42, or if the Code42 application has been removed from your Microsoft Azure environment, the Code42 connection enters an Error status and this error message appears in the details for that data connection:

The Code42 enterprise application in your Microsoft Azure account does not have the right permissions or has been deleted. Deauthorize this data connection and set up a new data connection.

To troubleshoot this error, verify whether the Code42 application exists in Microsoft Azure.

If the Code42 application still exists, grant admin consent to reset its permissions.
If the Code42 application no longer exists, deauthorize the connection in Code42 and set up a new data connection.

Verify the Code42 application exists in Microsoft Azure

Log in to portal.azure.com.
Click Azure Active Directory.
Click Enterprise Applications.
In the Enterprise applications list, look for an application with a name starting with "Code42."
- For OneDrive, look for the "Code42 Cloud Services" enterprise application.
- For Microsoft Office 365 email, look for the "Code42 Email Data Connector" enterprise application.
If the Code42 application is listed, continue to the next section to grant admin consent to reset its permissions. If it is not listed, deauthorize the connection in the Code42 console and set up a new data connection.

If the Code42 application exists, grant admin consent to it in Microsoft Azure

If the Code42 application exists in Microsoft Azure, follow these steps to grant admin consent to reset its permissions:

Click the application name in the Enterprise applications list to open its details.
Under Security in the left navigation pane, click Permissions.
Click Grant admin consent for Code42 to reset the application's permissions to those required for monitoring.
After you grant the application permissions, Code42 detects the change and returns the connection to the Monitoring status within 24 hours. You have resolved the error and are finished with troubleshooting.

If the app doesn't exist, deauthorize the connection in Code42 and set up a new one

If the Code42 application does not exist in Microsoft Azure, set up a new Code42 connection to your Microsoft environment.

Sign in to the Code42 console.
Select Administration > Integrations > Data Connections.
Locate the service to deauthorize in the table, then click View details .
Click Deauthorize.
Set up a new Code42 OneDrive cloud storage or Microsoft Office 365 email service connection using your Microsoft 365 administrator credentials.

There is an issue with the connection

Other issues—such as a change in your administrator credentials—can cause the Code42 connection to enter an Error status. When such unknown errors occur, the following error message appears in the Code42 details for that data connection:

There was an issue with the connection to <data connection>. Deauthorize <data connection> and set up a new data connection to resolve the issue, or contact Code42 for support.

To resolve this error:

Deauthorize the data connection.
Remove Code42's access in the email service environment:
- For Gmail: Delete the Code42 API client from your Google environment.
- For Microsoft Office 365 email or OneDrive: Delete the Code42 application from your Microsoft Azure environment.
Set up a new Code42 data connection using your Google or Microsoft 365 administrator credentials.

If these steps don't resolve your error, contact our Customer Champions for support.

Data connection is already registered or the email address is not valid

You can authorize a Microsoft 365 account in Code42 only once as a cloud storage data connection (to monitor file movement in OneDrive Drive locations) and once as an email service (to monitor file attachments sent outside your company).

When you attempt to register the same Microsoft 365 account for multiple cloud storage or email services, the following message appears: “This data connection has already been registered or the email address is not valid for this domain.” This message appears when you attempt to register the same account:

For more than one cloud storage or email service in the same Code42 environment.
In a second Code42 environment after first registering that account in a different Code42 environment.

To resolve the issue:

Verify the Code42 environment with which the Microsoft 365 account has been registered. To register the Microsoft 365 account with a different Code42 environment, first deauthorize it in the Code42 environment where it is currently registered.
Verify that the account has been added only once as a cloud storage data connection or only once as an email service.
Consider creating another Microsoft 365 account for the data you want to monitor using a new email address under a different domain. You can add multiple unique Microsoft 365 accounts as Code42 data connections as long as the accounts are not associated in any way.

No file events in Forensic Search

If file events aren't appearing for email attachments in Forensic Search, verify that:

Users have the required Microsoft or Office 365 subscription.
Code42 can only monitor email attachments that are sent by users who have specific Office 365 subscriptions. After you authorize the connection, Code42 identifies the users in your Microsoft environment that have both:
- An email account
- The required subscription to be monitored
If file events aren't appearing in Forensic Search as expected, verify that the email users in your Microsoft environment:
- Have an email account or mailbox
- Are active users
- Have been assigned the correct Microsoft or Office O365 subscriptions.
You can use tools in the Microsoft 365 admin center to view an individual user's licensing or export a list of users who have a specific license.
The Microsoft Office 365 email service has not been deauthorized in Code42.

Deauthorizing an email service in Code42 prevents Forensic Search from accessing or displaying that data. If the connection no longer exists in either your Code42 or Microsoft Office 365 environment, you need to re-add Microsoft Office 365 as an email data connection for Code42.

Reconfigure scoping for user and group monitoring

If needed, you can reconfigure the connection's scoping to add new users or groups or switch from monitoring specific users to monitoring specific groups.

Deauthorize the connection.
Code42 removes the connection's configuration and authorization information immediately after you deauthorize it.
Set up a new connection to the environment by clicking Add Data Connection on the Data Connections screen.
In the Add Users step of the authorization process, select the appropriate monitoring option, and then upload a new .csv file containing the updated users or groups you want to monitor.

External resources

Microsoft documentation: