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

# Connecting Microsoft 365 (Graph)

> This page assumes you have a Microsoft tenant and a directory admin who can create app registrations in it. For what to create across all the vendors, and how far each has been proven, start at [Systems your apps can reach](/setting-up-your-accounts/systems-apps-can-reach.md).

Microsoft 365 — people and groups, SharePoint, OneDrive, Outlook mail, calendars and Teams — is a **separate connector** from Dynamics/Dataverse, on purpose. Dataverse holds business records. Graph reaches **your people's own content**, so it carries a different risk profile and a different setup.

## The one thing to understand before you set this up

Every app that requests Microsoft 365 can only ever ask for **"only what the person using it can already see"** — the app acts as whoever is signed in, and Microsoft applies that person's own permissions. There is no "wider access, set up by IT" option for this connector, and no request form here will offer one: mail, calendars, files and Teams content are personal by nature, so this product doesn't let an app be granted a broad account that reads everyone's. If a genuinely org-wide reporting need comes up, it needs its own conversation with Microsoft's own tenant-level controls, not a setting in Emseapea.

That's a change from earlier setup guidance, if you followed it before this page was corrected: there is no longer a choice of "delegated" vs "dedicated mailbox" vs "org-wide application" to make when granting an app Microsoft 365 access. There's one kind, always.

## Two separate things you're setting up

**1. The connector itself**, below — an app registration with *application* permissions, consented once by an admin. This is what lets Emseapea show you, per tenant, which Microsoft 365 capabilities actually work — some fail for reasons that have nothing to do with permissions (a license your plan doesn't include, for instance), and this setup is what makes that visible under **Test connection** rather than a builder finding out the hard way in production.

**2. Each person's own connection** — a one-time, self-service "connect your Microsoft account" step every builder and every person using a governed app does for themselves, once, on their own account. This is what actually backs the "only what the person using it can already see" promise for real: without it, there's no way to know who's asking, so there's nothing to scope a token to. There's no admin step for this part — it's between each person and their own Microsoft sign-in.

## Setting up the connector

> **Read this before you grant anything.** The application permissions below are, by nature, organisation-wide: an app registration holding `Mail.Read` can technically read **every mailbox in your tenant**. That capability is only ever used for the tenant-level capability check described above, not to hand any governed app that reach — but consenting to it is still worth understanding before you click **Grant admin consent**.

1. [entra.microsoft.com](https://entra.microsoft.com) → **Applications → App registrations** → your `emseapea-gateway` app.
2. **API permissions** → **Add a permission** → **Microsoft Graph** → **Application permissions**.
3. Add what you want Emseapea able to check: for example `User.Read.All`/`Group.Read.All` (people and groups), `Sites.Read.All`/`Files.Read.All` (SharePoint/OneDrive), `Mail.Read` and `Calendars.Read` (mail and calendars).
4. Click **Grant admin consent for \<your tenant>**. This button requires a **Global Administrator** (or Privileged Role Administrator). Without it, every capability check for that permission comes back "needs admin consent" rather than working.
5. In Emseapea → **Settings → Data Systems → Microsoft 365 (Graph) → Set up connection**:
   * Web address: `https://graph.microsoft.com`
   * Sign-in address: `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`
   * Scope: `https://graph.microsoft.com/.default`
   * Client secret: held by your gateway, never by Emseapea
6. **Test connection** to see, per capability, whether it works, needs consent, or isn't included in your Microsoft 365 plan — three different situations that need three different people to act on them.

## Setting up "connect your Microsoft account" (what makes access real)

This is what a per-person Microsoft 365 request actually depends on, and it needs a **second, separate** Entra app registration from the one above — this one asking for *delegated* permissions (`User.Read`, `Mail.Read`, `Calendars.Read`, `Files.Read`) with a redirect URI of `<your Emseapea URL>/api/connect/msgraph/callback`. Registering it and granting its permissions needs a human with directory-admin rights; nothing in Emseapea can do this step for you. Once it's registered, its client ID, secret and tenant ID are set as Emseapea configuration alongside your other environment secrets.

**Be honest with yourself about where this stands.** Until that second app registration exists and is configured, every Microsoft 365 request answers "you need a Microsoft 365 account to see this" for everyone, always — the correct, fail-closed behaviour, but it means nobody's app can actually reach Microsoft 365 yet. This exchange is real, tested code, but as of this writing it has not yet been run end to end against a live Microsoft tenant — that last step needs the app registration above, which only a directory admin can create.

## Narrowing further, if you still want to

If, after understanding that this connector never grants an app more than the signed-in person could already see, you still want an extra layer of defence in depth at Microsoft's own level, **application access policies** can limit which mailboxes the connector's own app registration can ever touch — even for the tenant-capability checks above. Ask your Exchange administrator for `New-ApplicationAccessPolicy` scoped to a mail-enabled security group.