---
title: "Microsoft 365 Management API collector"
canonical: "https://docs.devo.com/space/latest/622952489/Microsoft%20365%20Management%20API%20collector"
format: markdown
---
> Macro (toc)
## Purpose
An analyst wants to detect **malicious information sharing in Microsoft 365** (formerly Office) applications. Using the Microsoft 365 [API](https://learn.microsoft.com/en-us/office/office-365-management-api/office-365-management-apis-overview), the analyst will find data exfiltration. As a result, the analyst will deactivate harmful users, preventing them from sharing more sensitive data.
You may also need:
- [Microsoft 365 Exchange Reports](https://docs.devo.com/space/latest/622559292/Microsoft+365+Exchange+Reports+collector): obtain usage reports of Microsoft 365 services and tools.
- [Microsoft 365 Exchange Online](https://docs.devo.com/space/latest/94656748/Microsoft+365+Exchange+Message+Tracing+collector): monitor 365 users' emails.
> ℹ️ Tip: The Microsoft 365 Management API collector will get authentication information into Devo. However, Devo recommends also enabling the [Entra ID collector](https://devodocs.atlassian.net/wiki/spaces/latest/pages/1198063647). The Entra ID collector provides important additional information, such as the name of the application the user accessed.
## Prerequisites
- Microsoft 365 subscription
- Azure subscription associated with your Microsoft 365 Copilot subscription
- Azure [Tenant Admin](https://learn.microsoft.com/en-us/azure/service-health/admin-access-reference) access
## Example Tables
| **Devo table** | **Description** |
| --- | --- |
| [cloud.office365](https://devodocs.atlassian.net/wiki/spaces/latest/pages/94661104).management.* | Data from a particular 365 service, where the service is defined by the `Workload` field in the data. Example: exchange. |
| [cloud.office365](https://devodocs.atlassian.net/wiki/spaces/latest/pages/94661104).management | This table includes all the data from this collector. |
| cloud.office365.management.onedrive | Activity in OneDrive, including access to applications like Word and Excel. |
| [auth.all](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126107) | Authentication logs, including successful and failed login to 365. |
## Authorize It
### Register your application in Microsoft Entra ID
1. Register Devo application in ***Microsoft Entra ID ***from the*** Azure *****portal**:
1. Access **Microsoft Entra ID > App registration > New registration.**
b. On the **Register an application** page:
i. **Assign a name** for the application. Ex: `devo_integration`
ii. Define **application use and API access**
iii. **Redirect URI** field can be left blank.
c. Click “**Register”** button.
> ⚠️ Make note of the ***Client ID*** and ***Tenant ID*** generated during this registration process.
### Generate a new secret
2. To exchange an authorization code for an access tokens you need to generate **keys** (`client_secrets`):
1. Access Azure portal **Microsoft Entra ID > App registrations > Application**
2. Select **Certificates & secrets > New client secret** specifying the key description and expiration.
> ❌ **Data loss** warning: At the secret expiration time, the collector will stop working until the secret is replaced.
3. Click **Add**.
4. Go to **Client secrets **to copy the client **secret value** to the clipboard.
> ⚠️ **Save** the client secret **value**. It will only be shown once.
> ⚠️
> ⚠️
> ⚠️
> ⚠️ The **value** [contains a tilde ~ character.](https://devodocs.atlassian.net/wiki/spaces/latest/pages/1086816286)
### Specify the permissions required to access the Microsoft 365 Management APIs
5. From Azure portal, go to **App registrations > All applications** select the application and the **API permissions > Add a permission** to display the **Request API permission.**
6. On the **Microsoft APIs** tab, select **Microsoft 365 Management APIs**.
7. Select the **Application permissions** type.
8. Enable permissions:
1. Read activity data from your organization.
2. Read service health information from your organization.
3. Read DLP policy events including detected sensitive data (only if pulling `DLP.All` from Management Activity).
9. Select **Add permissions**.
### Get Microsoft 365 tenant admin consent
10. The **[Tenant Admin](https://learn.microsoft.com/en-us/azure/service-health/admin-access-reference)** will need to grant permissions in the [Microsoft Entra consent UI](https://learn.microsoft.com/en-us/office/office-365-management-api/get-started-with-office-365-management-apis).
11. The Permissions status will change from “Not granted“ to “Granted“, once the previous authorization process has been completed by the tenant Admin.
## Run It
In the Cloud Collector App, [create a Microsoft 365 collector instance](https://docs.devo.com/space/latest/409305131/Catalog#Create-an-instance) using this parameters template, replacing the values enclosed in `< >`. The unique ID should be a five digit number.
```
{
"inputs": {
"office365": {
"credentials": {
"client_id": "",
"client_secret": "",
"tenant_id": ""
},
"enabled": true,
"id": "",
"services": {
"azure_active_directory": {},
"general_audit": {},
"exchange": {},
"sharepoint": {},
"dlp": {}
}
}
}
}
```
## Secure It
Use the [authentication](https://devodocs.atlassian.net/wiki/spaces/latest/pages/2206367761/Query+and+alert+library#AUTH) and [365](https://devodocs.atlassian.net/wiki/spaces/latest/pages/2206367761/Query+and+alert+library#CLOUD%2FO365) queries in the library.
### Authentication
An analyst wants to identify who logged in to determine if any malicious users accessed the system.
```
from cloud.office365.management
where Operation = "UserLoggedIn" or Operation = "UserLoginFailed"
group by Operation, ActorIpAddress, UserId, split(hostchain,"-",1) as collector_id
```
### Email Attachments
A machine has been infected with malware. An analyst wants to determine if the malware was spread using an email attachment. Using this query, the analyst will improve email filtering.
```
from cloud.office365.management.exchange
where eq(Operation,"AttachmentDownload")
group by UserId, jsonparse(message)["AttachmentName"]
```
### Exchange Auditing Disabled
A malicious user has hidden their activity by disabling audit logging. An analyst wants to identify the malicious user.
```
from cloud.office365.management.exchange
where eq(Operation,"Remove-AuditConfigurationPolicy")
```
### Insider Risk Policies
A user has been deactivated. The user did not trigger any data theft alerts. An analyst wants to check the history of insider risk policies to see if data theft was being monitored around the time of the deactivation.
```
from cloud.office365.management.securitycompliancecenter
where has(Operation,"InsiderRiskPolicy"), not has(Operation,"Get")
```
### OneDrive Exfiltration
An analyst wants to determine which accounts are sharing strategic information. If information is being shared with an unauthorized recipient, the compromised UserId should be disabled.
```
from cloud.office365.management.onedrive
where Operation = "SharingSet"
select str(jsonparse(message)["ObjectId"]) as file
where weakhas(file,"strategic")
select str(jsonparse(message)["ClientIP"]) as ip,
str(jsonparse(message)["TargetUserOrGroupName"]) as recipient
```
### Teams Exfiltration
It was revealed that a foreign tenant received confidential information. An analyst wants to find which Teams activity was available to foreign tenants in order to find out what other information was disclosed.
```
from cloud.office365.management.microsoftteams
select jqeval(jqcompile(".ParticipantInfo.HasForeignTenantUsers"),jsonparse(message)) as foreign
where isnotnull(foreign)
```
### Sharepoint Data Destruction
A malicious user has destroyed data. An analyst wants to determine which data is lost so that service can be restored.
```
from cloud.office365.management.sharepoint
where Operation = "FileVersionsAllDeleted"
```
## Monitor It
Create an [inactivity alert](https://docs.devo.com/space/latest/95126785/Inactivity+alert) to detect interruptions of transfer of data from popular Microsoft products to the Microsoft 365 Management API using the query
```
from cloud.office365.management
where toktains(hostchain,"collector-")
select split(hostchain,"-",1) as collector_id
where eq(Workload,"Exchange") or eq(Workload,"AzureActiveDirectory") or eq(Workload,"MicrosoftTeams")
```
Set the inactivity alert to keep track of the `collector_id` and `Workload`.