Skip to main content

Connect Microsoft 365

Connecting Microsoft 365 lets Retrievy audit your Exchange Online, SharePoint, Teams, Defender for Office 365, and the underlying Entra ID tenant in one shot. Findings flow into the Command Center and feed your Retrievy Index the moment the first scan lands.

M365 uses the same Microsoft Graph permissions as the Azure integration, and shares the same Retrievy multi-tenant app for Quick Connect. If you've already connected Azure with Quick Connect, adding M365 is a two-click reuse-the-existing-consent flow.

Before you start​

You need:

  • A Microsoft 365 tenant where you (or a tenant admin) can grant admin consent and assign the Global Reader directory role.
  • A Retrievy workspace with CSPM enabled (every plan).
  • The manage-cloud-accounts permission in Retrievy.
  • One free data-source slot on your plan.

M365 is treated as a separate data source from Azure even though they share the same Entra app. That means you can connect M365 standalone without connecting any Azure subscriptions, and vice versa.

Path A — Quick Connect (recommended)​

Step A1. Start the Quick Connect flow​

In Retrievy:

  1. Open Settings → Cloud Integrations → Add Cloud Account.
  2. On the IDENTIFY TARGET step, pick Microsoft 365, then click Connect with Microsoft 365 in the panel that appears.
  3. Retrievy redirects you to Microsoft's consent screen. Sign in with a tenant-admin account.
  4. The consent screen lists the permissions Retrievy is requesting (see table below). Click Accept.
PermissionTypeWhy Retrievy needs it
AuditLog.Read.AllMicrosoft Graph (Application)Reads sign-in and directory audit logs.
Directory.Read.AllMicrosoft Graph (Application)Enumerates users, groups, roles.
Policy.Read.AllMicrosoft Graph (Application)Reads conditional access and authentication policies.

If you've already connected an Azure subscription with Quick Connect, Microsoft shows the Reuse existing consent shortcut and skips re-prompting for the same permissions. Click through.

After consent, Microsoft redirects you back to Retrievy and the wizard moves to step A2 with a green Tenant connected banner.

Step A2. Assign the Global Reader role​

The Graph permissions cover identity. Exchange Online, Defender for Office 365, and SharePoint admin-centre data need an extra directory role on the Retrievy service principal. The minimum-privilege role is Global Reader (read-only across every M365 admin centre).

In the Microsoft Entra admin centre:

  1. Open Identity → Roles & admins → Roles.
  2. Find Global Reader in the list. Click it.
  3. Click + Add assignments.
  4. Search for Retrievy (the app name Microsoft created during consent). Pick it.
  5. Click Add.

Global Reader is read-only by definition; it can never modify anything in any admin centre. If your security policy requires a tighter scope, you can substitute the more granular Security Reader role, but you'll lose some Exchange and SharePoint findings.

Step A3. Validate and run​

Back in Retrievy:

  1. Click Validate permissions on the wizard. Retrievy uses the consent it received to request a Microsoft Graph token, then calls GET /v1.0/organization (proves admin consent landed) and GET /v1.0/auditLogs/directoryAudits?$top=1 (proves the Global Reader role landed).
  2. If both calls return 200 OK, the green Permissions validated message appears.
  3. Click Run first scan.

If the audit-logs call returns 403, the role assignment hasn't propagated yet (Microsoft can take up to 10 minutes) or you assigned Security Reader instead of Global Reader.

Path B — Manual app registration​

Use this path if your security policy forbids multi-tenant apps. You create your own single-tenant app registration in Entra, paste its credentials into Retrievy, and skip Microsoft's consent flow entirely.

The steps are identical to Path B on the Azure setup page — same app, same Graph permissions, same client secret. The only differences:

  • On the Retrievy wizard, pick Microsoft 365 instead of Azure in the IDENTIFY TARGET step.
  • Skip the Reader on subscription assignment from the Azure flow. M365 doesn't need it.
  • Add the Global Reader directory role to your app's service principal (the steps in Path A Step A2 above apply to manual app registrations too — same role, same Entra admin centre flow, just search for the app you registered instead of "Retrievy").

The four wizard fields are the same: Tenant ID, Client ID, Client Secret, and an optional scope field that for M365 acts as a tenant filter (leave blank).

What you see in the account list​

The Cloud Integrations page shows your M365 account as a card. Quick Connect accounts carry a small Quick Connect badge. Manual accounts carry the app registration's display name in the friendly name slot.

The status badge, scan state pill, last-scan timestamp, and the three actions (Scan Now, Test Connection, Deactivate) all work the same as every other cloud account.

What Retrievy scans​

The M365 module covers:

  • Identity: privileged role members, stale guest accounts, conditional access policy gaps, MFA enforcement gaps, password protection settings.
  • Exchange Online: mailbox audit, anti-phishing policies, safe links and safe attachments, sharing policies.
  • SharePoint and OneDrive: external sharing settings, anonymous link policies, default access levels.
  • Teams: federation settings, meeting policies, app permission policies.
  • Defender for Office 365: alert policies, anti-malware tuning, threat policies.
  • Secure Score: Microsoft's own posture score appears alongside the Retrievy Index per-module score for M365.

Findings carry CIS Microsoft 365 Foundations Benchmark mappings out of the box.

Connecting both Azure and M365 from the same tenant​

This is the common case for organisations that run Azure subscriptions and M365 from one Entra tenant. The cleanest setup:

  1. Connect Azure with Quick Connect first. Assign the Reader role on each subscription. Validate.
  2. Connect M365 from the same workspace. When Microsoft offers Reuse existing consent, accept. Assign Global Reader on the same service principal. Validate.

Both accounts share the consent + service principal but show as two distinct cards in your cloud integrations list, count as two data-source slots, and feed two separate per-module dashboards (Azure CSPM + M365 CSPM).

Rotating credentials and revoking access​

Quick Connect: nothing to rotate. To revoke, Deactivate in Retrievy, then in the Entra admin centre remove the Retrievy service principal's role assignments or delete the service principal entirely.

Manual: rotate the client secret in the same way as Azure manual (Azure setup, step B2). To revoke, delete the app registration in Entra.

Troubleshooting​

Symptom: Consent screen says AADSTS650056: Misconfigured application. → Fix: Quick Connect uses Retrievy's multi-tenant app, which requires admin consent at the tenant level. If you're signed in as a regular user, the screen tells you to ask an admin. Either ask your Entra admin to run the wizard with you, or forward the consent URL Retrievy generated and have them complete it.

Symptom: Validate permissions says Global Reader role not detected, but I assigned it. → Fix: Three things in order. (1) Wait 10 minutes for the role to propagate (Microsoft Entra is slower than Azure RBAC). (2) In the Entra admin centre, Roles & admins → Global Reader → Assignments, confirm the Retrievy service principal is in the list. (3) Confirm you didn't assign Security Reader by mistake; Global Reader is the broader role Retrievy needs.

Symptom: First scan succeeds but every Defender for Office 365 finding is empty. → Fix: Your M365 plan doesn't include Defender for Office 365 (it requires E5 or a standalone Defender plan). Retrievy can't audit what isn't running.

Symptom: Scan finishes but SharePoint findings are missing. → Fix: SharePoint Online needs Global Reader; Security Reader is not enough for SharePoint admin data. Switch to Global Reader.

Symptom: I want to scan only one of multiple M365 tenants I administer. → Fix: Add one account per tenant. Each Quick Connect run prompts for the tenant to sign into; pick the one you want for that data source. Repeat for the next tenant in a new wizard run.