Microsoft Office 365 Audit Source

Office 365 Audit Log Workload types

note

Office 365 Germany is a new, differentiated option to the Office 365 services currently available in Europe, and is not supported by Sumo Logic as an audit source for collection at this time.

You can configure Sumo Logic to collect logs for the following Audit Log content types to track and monitor usage of Microsoft Office 365.

• Office 365 Exchange Logs. User activity and admin logs; This requires you enable Exchange Audit Logging
• Office 365 SharePoint Logs. All audit data for file-based activity, including those for “OneDrive.”  SharePoint is the underlying service for multiple Office 365 services; User activity and admin logs.
• Office 365 Azure AD Logs. Logon and admin logs.
• Office 365 General Logs. Includes all workloads not included in other content types.
• Office 365 DLP Event Logs. Data loss prevention (DLP) policy logs to identify, monitor, and automatically protect sensitive information across Office 365.

A single Office 365 Audit Source is limited to collecting audit logs of a single content type. If you want to collect logs from more than one of the available content types, you can create an individual Source for each content type under the same Hosted Collector.

You can use the same metadata across all of the Office 365 Audit Sources, or you can vary the metadata per Source.

Create only one Source for a given workload type. If you create an additional Source with the same workload type, none of the Sources with that workload type will work.

info

Audit log data can contain sensitive information. When you configure any audit log Source, make sure that you implement the appropriate RBAC permissions to limit access to the content as needed. 

Prerequisites

• Enable unified auditing for your Office 365 organization. To enable, see https://docs.microsoft.com/en-us/office365/securitycompliance/turn-audit-log-search-on-or-off
• Office 365 admin roles
• Enable Exchange Audit Logging
• Authentication must be with a new Office 365 Audit Source, we do not support re-authenticating existing sources.

Office 365 admin roles

Office 365 comes with a set of admin roles that you can assign to users in your organization. Each admin role maps to common business functions and gives people in your organization permissions to do specific tasks in the Office 365 admin center.

When you configure a Microsoft Office 365 Audit Source in Sumo Logic, you will need to authenticate with Microsoft using standard OAuth v2. The user who authenticates must have Microsoft Office 365 admin rights for the content that is being audited. For the sake of the principle of least privilege (PoLP), the authenticating account should have the minimum necessary permissions while still enabling appropriate access. The appropriate role depends on the Office 365 edition you use and your security policies.

Using the Global Reader role is recommended to reduce security risks, as it provides read-only access:

Role	Description
Global Reader	This role provides read-only access to the Office 365 environment without the ability to modify settings or content, minimizing security risks.

In cases where read-only access is insufficient and additional permissions are required, you may need to use the Global Administrator role, which provides full access:

Role	Description
Global Administrator	This role enables access to all administrative features in your Office 365 subscription. Use this role only when absolutely necessary, as it grants full control.

Alternatively, you could assign more granular roles to the authenticating account. There are approximately 40 Office 365 roles, and some subset of those roles might meet your collection requirements. For more information, see the following topics in Microsoft help:

• Permissions in the Office 365 Security & Compliance Center
• About Office 365 admin roles
• Assigning administrator roles in Azure Active Directory

note

The variety and range of configurations in Office 365 environments preclude exhaustive testing of log ingestion from Office 365 sources. You might need to experiment with several roles to ensure you are ingesting the data you want. Note also that Office 365 administrators must enable logging in their environments for the logs to be available.

Enable Exchange Audit Logging

Before you can configure a Sumo Logic Microsoft Office 365 Audit Source for Exchange log data, enable Exchange Audit Logging within your Office 365 tenant by following the steps at https://technet.microsoft.com/library/dn879651.aspx.

Microsoft APIs

The Sumo Logic Microsoft Office 365 Audit Source uses Webhook based integration with the Microsoft Office 365 Management Activity API. For more information on the API, see Office 365 Management Activity API reference.

For information on the format of the audit log data that is returned, see Office 365 Management Activity API Schema.

Message format

Each log file from Microsoft contains one or more log messages formatted as a JSON array. If there is more than one message in the array, we separate each log line in the JSON array into an individual log line message within Sumo Logic.

Setup

Vendor configuration

The Microsoft Office 365 Audit Source requires you to provide Tenant Id, Client Id, and Client Secret while configuring. To obtain these values, follow the below steps:

Step 1: Register a new application

1. Sign in to the Azure portal.
   note

   Sign in with an account that has Application Administrator and Global Administrator access for your tenant. Global Administrator access is required later to grant admin consent.

2. In the left menu, navigate to Azure Active Directory > App registrations.
3. Click New registration.
4. Complete the form:
   • Name. Add a display name of the application registration in Azure. For example, SumoLogic-O365AuditSource.
   • Supported account types. Select Single tenant only - Your Tenant Name from the dropdown. This ensures that the application is accessible only to users within your organization’s Azure AD tenant and not to external or personal Microsoft accounts.
5. Click Register.
6. Once the application is created, open the Overview page to collect the Client ID and Tenant ID.

Step 2: Create a client secret

1. In the application menu, navigate to Certificates & Secrets > Client secrets.
2. Click + New client secret.
3. Provide a description. For example, SumoCollectorSecret.
4. Select an expiration period.
5. Click Add.
6. Collect the client secret by copying the generated value and store it securely. This value is your Client Secret, and it will not be displayed again.

Step 3: Grant API permissions

1. In the application menu, select API permissions > + Add a permission.
2. Choose APIs your organization uses and search for Office 365 Management APIs.
3. Select Application permissions (not Delegated).
4. Expand the ActivityFeed and select:
   1. ActivityFeed.Read
   2. (Optional and only for DLP events) ActivityFeed.ReadDlp
5. Click Add permissions.

Step 4: Grant admin consent

1. On the API permissions page, click Grant admin consent for Your Tenant Name.
2. Confirm the action. The permissions should now appear as Granted for tenant.

Source configuration

You must configure a separate Source for each Office 365 application you want to collect logs for. These can all be configured on the same Hosted Collector. 

info

During the configuration, you will need to authenticate to Microsoft using standard OAuth v2. The user who authenticates must have Microsoft Office 365 admin rights for the content that is being audited. Refer to the API references in this article for additional information on Microsoft admin rights.

1. New UI. In the Sumo Logic main menu select Data Management, and then under Data Collection select Collection. You can also click the Go To... menu at the top of the screen and select Collection.
   Classic UI. In the main Sumo Logic menu, select Manage Data > Collection > Collection.
2. Click Add Source next to a Hosted Collector. If you dont already have a hosted collector, see Set Up a Hosted Collector for instructions on setting up a new Hosted Collector.
3. Select Office 365 Audit. 
4. Enter a name to identify the Source. Description is optional.
5. For O365 Region, select the region that corresponds to your Microsoft 365 or Office 365 subscription plan, the supported regions are Commercial, GCC, and GCC High. See Activity API operations for more details.
   note

   Source creation will fail if an incorrect O365 Region is selected. You cannot change the O365 Region setting on an existing Source.

6. For Content Type, select the type of log to collect. If you want to collect from additional content types, create additional instances of this Source type.
7. For Source Category, enter any string to tag the output collected from this Source. (Category metadata is stored in a searchable field called _sourceCategory.) This is an important part of limiting access to this content using RBAC. Recommended Source Category naming conventions:
   • For SharePoint: O365/SharePoint
   • For Exchange: O365/Exchange
   • For Azure: O365/Azure
8. Fields. Click the +Add Field link to define the fields you want to associate, each field needs a name (key) and value.
   •  A green circle with a check mark is shown when the field exists and is enabled in the Fields table schema.
   •  An orange triangle with an exclamation point is shown when the field doesn't exist in the Fields table schema. In this case, you'll see an option to automatically add or enable the nonexistent fields to the Fields table schema. If a field is sent to Sumo Logic but isn’t present or enabled in the schema, it’s ignored and marked as Dropped.
   note

   If you have Cloud SIEM installed and you want to forward log data to Cloud SIEM, click the +Add Field link and add a field whose name is _siemForward and value is true. This will ensure all logs for this source are forwarded to Cloud SIEM.

9. To allow Sumo Logic to access your Office 365 account, select one of the following:
   • (Recommended) App Registration. Enter the Tenant Id, Client Id, and Client Secret obtained in the Vendor configuration section.
     note

     Sumo Logic recommends using App Registration–based authentication instead of user account credentials to securely and reliably collect Microsoft Office 365 audit logs. This method aligns with Microsoft's best practices for service-to-service integrations.

   • Auth (User Account). Click Sign in with Office 365 to authenticate to Microsoft using standard OAuth v2 interaction.  
     note

     Sumo Logic never receives your Microsoft Office 365 credentials.

10. Create any Processing Rules you'd like for the new Source.
11. When you are finished configuring the Source, click Save.

Audit Index events

The Microsoft Office 365 Audit Source has events logged in the Sumo Logic Audit Index for the following:

• Source registration success with Microsoft
• Failure to read back content from Microsoft
• Token-update failure events
• Subscription watchpoint failure events

To search for these events use the Audit Index.

JSON schema

Configuration Object

Parameter	Type	Required	Default	Description	Example
name	String	Yes	null	Type a desired name of the source. The name must be unique per collector. This value is assigned to the metadata field _source.	"mySource"
description	String	No	null	Type a description of the source.	"Testing source"
category	String	No	null	Type a category of the source. This value is assigned to the metadata field _sourceCategory. See best practices for details.	"mySource/test"
fields	JSON Object	No	null	JSON map of key-value fields (metadata) to apply to the collector or source. Use the boolean field _siemForward to enable forwarding to SIEM.	{"_siemForward": false, "fieldA": "valueA"}
workload	String	Yes	null	Select the type of log to collect. If you want to collect from additional content types, create additional instances of this source type.	Audit.Exchange
region	String	Yes	Commercial	Select the region that corresponds to your Microsoft 365 or Office 365 subscription plan.	not modifiable
tenantId	String	Yes	null	Enter the tenant Id collected from the Azure platform.	11111111‑aaaa‑2222‑bbbb‑333333333333
clientId	String	Yes	null	Enter the client Id collected from the Azure platform.	44444444‑cccc‑5555‑dddd‑666666666666
clientSecret	String	Yes	null	Enter the client secret collected from the Azure platform.	xxxxxxxx‑super‑secret‑value‑xxxxxxxx

JSON example

static/files/hosted-collectors/ms-office-audit/example.json

loading...

See full example on GitHub

Known Issues

Refer to the following MSDN article for known issues, and notes: https://msdn.microsoft.com/EN-US/library/office/mt227394.aspx

Here are a few important items:   

• (From Microsoft) “When a subscription is created, it can take up to 12 hours for the first content blobs to become available for that subscription.”  We have found that data starts to arrive at Sumo Logic much sooner than this, but please wait this long before contacting Support.
• (From Microsoft) “The content blobs are created by collecting and aggregating actions and events across multiple servers and data centers. As a result of this distributed process, the actions and events contained in the content blobs will not necessarily appear in the order in which they occurred. One content blob can contain actions and events that occurred prior to the actions and events contained in an earlier content blob. We are working to decrease the latency between the occurrence of actions and events and their availability within a content blob, but we cannot guarantee that they appear sequentially.”
• There can be a significant delay between when an event occurs in O365, and when an audit log is available from Microsoft.  We receive the log files as soon as they are made available to us. The latency for log line available varies between content types, and from our observation, is not consistent. This is not within Sumo Logic’s control.  You may monitor this latency by querying the difference between the event time stamp and the receipt time stamp (when we processed the log message).

OAuth 2.0 access token and subscription expiration

Access Tokens

An access token is granted by a third party service, such as Microsoft Office 365, to Sumo for accessing audit log APIs required for collecting audit events. Access tokens are stored encrypted and have a short expiration time of several hours. Sumo automatically updates them before they expire to prevent data loss. Successful and failed token-update events are logged in the Audit Index. If the request fails Sumo will continue to try to update a token for about a week. After several failures, we recommend recreating the Office 365 Audit Source.

Subscription Watchpoints

A subscription is a channel established with the third party service to receive notification events. Similar to access tokens, subscriptions are valid only before the expiration time. Before a subscription expires, Sumo invalidates the current subscription and obtains a new subscription. In the event of failure to update a subscription, an entry is logged in the Audit Index.