# Collect data from Microsoft Office 365

{% hint style="info" %}
See the changelog of the **Microsoft 365** Listener [here](/listeners/office-365-listener.md).
{% endhint %}

{% hint style="warning" %}
This is a **Pull** Listener and therefore should not be used in environments with more than one cluster.
{% endhint %}

## Overview

Onum supports integration with **Office 365** through the [Office 365 Management Activity API](https://docs.microsoft.com/en-us/office/office-365-management-api/office-365-management-activity-api-reference).

Office 365 provides a suite of cloud-based productivity tools and services, including apps like Word, Excel, PowerPoint, and Teams, along with online storage via OneDrive and advanced security features.

You can use the **Office 365** Listener to send your Office data to Onum.

## Prerequisites

{% hint style="warning" %}
In order to use this Listener, you must activate the following environment variable in your distributor using docker compose: `SINGLETON_LISTENER_EXECUTOR=true`
{% endhint %}

Before starting, you must register an application in Microsoft Entra ID (formerly Azure AD).

After registration, you'll need the **Application (Client) ID**, the **Directory (Tenant) ID**, and either a **Client Secret (password)** or a **Certificate** for authentication.

Then, you must grant the necessary Office 365 Management Activity API permissions:

* `ActivityFeed.Read` - Required for reading activity feeds
* `ActivityFeed.ReadDlp` - Optional (for DLP events)
* `ServiceHealth.Read` - Optional (for service health)

## Start/stop a subscription

The **Office 365** Listener supports the start/stop subscription feature. You can start/stop a subscription using some other Office 365 API or using this `curl` command:

```
curl -d "client_secret={client_secret}&resource={resource}&client_id={app_id}&grant_type=client_credentials" -X POST https://login.windows.net/{tenantID}/oauth2/token
```

You should get a response like this:

```json
{
    "token_type": "Bearer",
    "expires_in": "string",
    "ext_expires_in": "string",
    "expires_on": "string",
    "not_before": "string",
    "resource": "string",
    "access_token": "string"
}
```

Use the `access_token` value to start or stop a subscription. These are the available content values:

* `Audit.AzureActiveDirectory`
* `Audit.Exchange`
* `Audit.SharePoint`
* `Audit.General`
* `DLP.All`

These are some of the requests you can perform:

* Start a subscription to begin receiving notifications and retrieving activity data for a tenant.

```
curl -d "" -H "Authorization: Bearer {access_token}" -X POST "https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/subscriptions/start?contentType={list_of_content_type_you_wanna_subscribe_to}"
```

* Stop a subscription to discontinue retrieving data for a tenant:

```
curl -d "" -H "Authorization: Bearer {access_token}" -X POST "https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/subscriptions/stop?contentType={list_of_content_type_you_wanna_unsubscribe_from}"
```

* Content type example (this will subscribe you to active directory and exchange):

```
contentType=Audit.AzureActiveDirectory,Audit.Exchange
```

[Here](https://learn.microsoft.com/en-us/office/office-365-management-api/office-365-management-activity-api-reference) is the list of all the API requests you can use. Once you start subscription, you can use the Listener to fetch your data.

For easier testing, here is the `curl` command to fetch the list of updates:

```
curl -d "" -H "Authorization: Bearer {access_token}" -X GET "https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/subscriptions/content?contentType={list_of_content_types}"
```

## Onum Setup

{% stepper %}
{% step %}
Log in to your Onum tenant and click **Listeners > New listener**.

<figure><picture><source srcset="/files/5ThFzyY3rmswYy01aoq5" media="(prefers-color-scheme: dark)"><img src="/files/1K3zmkVqShppDMc2Qu7M" alt=""></picture><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Double-click the **Office 365** Listener.
{% endstep %}

{% step %}
Enter a **Name** for the new Listener. Optionally, add a **Description** and some **Tags** to identify the Listener.
{% endstep %}

{% step %}
Enter your Office 365 Azure **Tenant ID**<mark style="color:red;">\*</mark>. Find this in the **Azure Active Directory > Overview**, or in the **Properties** pan&#x65;**.**
{% endstep %}

{% step %}
The **Application (client) ID**<mark style="color:red;">\*</mark> is needed when accessing Office 365 through APIs or applications. For applications registered in other directories, the Application (Client) ID is located in the application credentials.

1. Go to the **Azure Portal**.
2. Find **Microsoft Entra ID** in the left menu.
3. Click **App registrations** under the **Manage** section.
4. Select the **application** you registered (or search for it).
5. Under **Essentials**, find **Application (client) ID**.
6. Click **Copy to clipboard** to save it.
   {% endstep %}

{% step %}
Assign your data a **Content Type** in the form of reusable columns, document templates, workflows, or behaviors. Click **Add element** to add the required content types.

These are the available content values:

* `Audit.AzureActiveDirectory`
* `Audit.Exchange`
* `Audit.SharePoint`
* `Audit.General`  (includes all other workloads not included in the previous content types)
* `DLP.All` (DLP events only for all workloads)

For details about the events and properties associated with these content types, see [Office 365 Management Activity API schema](https://learn.microsoft.com/en-us/office/office-365-management-api/office-365-management-activity-api-schema).
{% endstep %}

{% step %}
The **Client Secret** (also called Application Secret) is used for authentication in **Microsoft Entra ID** (formerly Azure AD) when accessing APIs. To get it:

1. Click **App registrations** under the **Manage** section.
2. Select your **registered application**.
3. In the left menu, click **Certificates & secrets**.
4. Under **Client secrets**, check if an existing secret is available. You cannot view it, so you must have it saved somewhere.
5. If you need a new one, create one and copy the value immediately.

{% hint style="info" %}
Learn more about secrets in Onum in [this article](/administration/global-settings/organization-settings/secrets-management.md).
{% endhint %}
{% endstep %}

{% step %}
In Onum, open the **Secret** field and click **New secret** to create a new one:

* Give the secret a **Name**.
* Turn off the **Expiration date** option.
* Click **Add new value** and paste the secret corresponding to the JWT token you generated before. Remember that the token will be added in the Microsoft 365 configuration.
* Click **Save**.

<figure><picture><source srcset="/files/NeeWsSQzoChVxRIY76Nt" media="(prefers-color-scheme: dark)"><img src="/files/1oTccyPmgZJ1laY7IhZH" alt=""></picture><figcaption></figcaption></figure>

You can now select the secret you just created in the corresponding field.
{% endstep %}

{% step %}
Choose your **Subscription Plan**<mark style="color:red;">**\***</mark> from the list. Find this in the **Microsoft Account Portal** under **Billing > Your Products**.
{% endstep %}

{% step %}
Enter the **Polling Interval**<mark style="color:red;">**\***</mark> frequency in minutes with which to grab events. The minimum value is `1`, and the maximum value is `60`.
{% endstep %}

{% step %}
If you are using a proxy to establish the connection, toggle on the **Proxy configuration** button and enter the details here.&#x20;

* **Scheme**<mark style="color:red;">**\***</mark> - Choose the scheme to connect to.
* **URL**<mark style="color:red;">**\***</mark> - The host and port of the proxy URL used to establish the connection
* **Username** - This is the username used to access the proxy.
* **Password** - Enter the proxy passcode.
  {% endstep %}

{% step %}
Decide whether to skip or require TLS validations to the server.
{% endstep %}

{% step %}
Finally, click **Create labels**. Optionally, you can set labels to be used for internal Onum routing of data. By default, data will be set as **Unlabeled**. Click **Create listener** when you're done.

{% hint style="info" %}
Learn more about labels in [this article](/the-workspace/listeners/labels.md).
{% endhint %}
{% endstep %}
{% endstepper %}

Click **Create listener** when you're done.

### Ports <a href="#ports" id="ports"></a>

The Office 365 Listener has two output ports:

* **Default port** - Events are sent through this port if no error occurs while processing them.
* **Error port** - Events are sent through this port if an error occurs while processing them.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onum.com/the-workspace/listeners/listener-integrations/collect-data-from-microsoft-products/collect-data-from-microsoft-office-365.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.