> For the complete documentation index, see [llms.txt](https://docs.threatdefence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.threatdefence.com/microsoft-365/microsoft-itdr-connector.md).

# Microsoft ITDR Connector

The **Microsoft ITDR Connector** is the current way to onboard a Microsoft 365 tenant to ThreatDefence. It replaces the manual Entra ID app registration flow, where you created your own application, uploaded the ThreatDefence certificate, and granted each API permission by hand.

Instead, you pick the connector in the ThreatDefence Alert Centre, and a Microsoft Global Administrator approves the ThreatDefence application once. Consent covers identity, Microsoft 365 audit, and Defender telemetry in a single approval, there is no separate Graph, Defender XDR, or Defender for Endpoint setup to complete afterwards.

The Microsoft 365 Integration, MS365 Graph API, Microsoft Defender XDR, and Microsoft Defender for Endpoint guides describe the legacy manual flow. They are retained for tenants that were onboarded that way and remain supported, but they should not be used for new onboarding. 

***

### Before you begin

> **Requirements:**
>
> * Access to the [ThreatDefence Alert Center](https://secops.threatdefence.io/), with permission to manage the MSP and tenant you are onboarding.
> * A **Microsoft Global Administrator** for the customer tenant, who can approve the application. This can be you, or someone you send an approval link to — they do not need a ThreatDefence account.
> * **Auditing enabled** in Microsoft 365. Most tenants have this on by default. If unsure, see Microsoft's guide to [turn auditing on or off](https://learn.microsoft.com/en-us/purview/audit-log-enable-disable).
> * **Licensing:** any Microsoft 365 licensing tier is supported. E5 or P1/P2 are not required — ThreatDefence automatically collects whatever telemetry your subscription exposes.

***

### Step 1: Open the Integrations page

1. Sign in to the [ThreatDefence Alert Center](https://secops.threatdefence.io/).
2. Go to **Deployment > Integrations**, or open [secops.threatdefence.io/deployment/integrations](https://secops.threatdefence.io/deployment/integrations) directly.

<figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2FE7mGvyQ4fbGOWbZEmnnL%2Fimage.png?alt=media&amp;token=6a4a813f-296c-43c3-a79e-ca678b76efed" alt=""><figcaption></figcaption></figure>

***

### Step 2: Select the tenant you are onboarding

Use the **global picker** in the top bar to select the MSP and the tenant you want to connect.

The connector catalogue is visible regardless of what is selected, but a connector can only be added once a tenant is in scope. If no tenant is selected, the page prompts you to pick one.

<figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2FgfMarn2K33b71E2em6nn%2FScreenshot%202026-09-21%20at%2011.06.27%E2%80%AFAM.png?alt=media&amp;token=cbdefb6b-3e66-47ff-b968-4e36789212d1" alt=""><figcaption></figcaption></figure>

Check the selected tenant before you continue. The connector is added to whichever tenant is currently in scope.&#x20;

***

### Step 3: Select the Microsoft ITDR Connector

1. In the **Add an integration** section, find **Microsoft ITDR Connector** in the connector catalogue. You can use the search box to filter the list.

<figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2F98goNfMMovpoHaH8Mm8Y%2FScreenshot%202026-09-21%20at%2011.09.15%E2%80%AFAM.png?alt=media&amp;token=eadebe82-1d45-4ae8-9907-3d2281b021c7" alt=""><figcaption></figcaption></figure>

1. Click the connector. A drawer opens on the right with the onboarding steps: **1. Connection details** and 2. **Authorisation**.

<figure><img src="https://4191868192-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOlFHF8fl339QOw3Og8L7%2Fuploads%2FoBTSOdcuB3uKT3FxIiNb%2FScreenshot%202026-09-21%20at%2011.11.52%E2%80%AFAM.png?alt=media&amp;token=9441440e-8f57-4f23-a1ef-2578e1411fbc" alt=""><figcaption></figcaption></figure>

***

### Step 4: Enter the connection details

1. In **the instance name**, enter a label for this connection. Use `primary` unless you are connecting more than one Microsoft tenant to the same ThreatDefence tenant, in which case give each one a distinguishable name.
2. **Microsoft 365 / Entra ID domain name** — the domain of the tenant you are onboarding, for example, `acme.com` or `acme.onmicrosoft.com`. This identifies the tenant for the Microsoft sign-in, so the approver lands on the right directory rather than having to pick one.
3. Click **Continue**.

The drawer moves to the **Authorisation** step and shows two ways to approve the tenant.

***

### Step 5: Authorise the tenant

Choose whichever option suits who has the Microsoft credentials.

#### Option 1: Approve via Microsoft

Use this when you hold global administrator rights on the tenant yourself.

1. Click **Sign in with Microsoft**.
2. Sign in with the tenant's Global Administrator account and review the permissions. ThreatDefence is requesting.
3. Accept the consent prompt.

You are returned to the Alert Centre, and the drawer closes.

#### Option 2: Send to a global admin

Use this when the customer holds the Microsoft credentials or when you are onboarding on their behalf.

1. Copy the **consent link** shown in the drawer.
2. Send it to a global administrator of the tenant. They can approve the integration without having a ThreatDefence account.
3. They open the link, sign in to Microsoft, and accept the consent prompt.

**The consent link is single-use and expires.** The drawer shows the exact expiry time. If it lapses or the link has already been used, reopen the connector, go through **connection details** again, and generate a fresh link.&#x20;

***

### Step 6: Confirm the tenant is connected

Once consent is granted, the connector appears in the connected integrations list for the tenant, under **Live data sources**.

Click the connector to open its drawer and check:

* **Configuration** — the connection details and the option to change them.
* **Health** — whether the connector is collecting successfully.
* **Logs** — recent collector output, useful when diagnosing a failed connection.

Logs typically begin appearing on dashboards within **30–60 minutes** of approval. Identity analytics and baselining build up over the following hours as historical activity is ingested.

***

### What the connector collects

A single approval covers the telemetry that previously required four separate integrations:

| Source                                       | What it provides                                                                                   |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Microsoft 365 audit logs (Unified Audit Log) | User and admin activity across Entra ID, Exchange Online, SharePoint, OneDrive, and Teams          |
| Microsoft Entra ID                           | Sign-ins, risky users and risk detections, directory and application configuration, consent grants |
| Microsoft Defender XDR                       | Incidents and alerts across Defender for Office 365, Cloud Apps, Identity, and Cloud               |
| Microsoft Defender for Endpoint              | Endpoint detection and response telemetry, where licensed                                          |

ThreatDefence adjusts automatically to the telemetry your licensing exposes a tenant without Defender licensing still delivers full audit and identity coverage.

Data is retained for three months. See Microsoft 365 Monitoring for related FAQs.

***

### Troubleshooting

**The consent link has expired or says it was already used.**\
Links are single-use and time-limited. Reopen the connector in **Deployment > Integrations**, step through **Connection details** again, and send the new link.

**The approver hit an error signing in to Microsoft.**\
Confirm they are signing in with an account in the tenant you are onboarding, not their own MSP tenant, and that the account holds Global Administrator rights.

**The connector is listed, but Health reports an error.**\
Open the **Logs** tab in the connector drawer for the collector output. If the cause is not clear, send the error to ThreatDefence support.

**I onboarded the wrong tenant.**\
Remove the integration from the connected list for that tenant, then re-add it against the correct tenant. Removing an integration stops its data flowing into the SIEM.

***

### Need help?

If you have any questions or need further assistance, please contact: **<support@threatdefence.com>**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.threatdefence.com/microsoft-365/microsoft-itdr-connector.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.