> For the complete documentation index, see [llms.txt](https://helpdesk.augmentt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.augmentt.com/configuration/m365-integration-setup.md). # M365 Integration Setup Augmentt connects to a customer's Microsoft 365 environment in one of two ways: through your **CSP (Cloud Solution Provider) relationship** with the customer, or through a **direct** connection using a Global Administrator account in that tenant. Most MSPs with a CSP/Partner Center relationship should use the CSP method — it's the fastest to set up across many tenants and is the only method that supports GDAP-scoped, least-privilege access. {% hint style="info" %} Getting connected is usually under 10 minutes: it's a sign-in with a couple of consent prompts, with no PowerShell scripts to run. {% endhint %} ## Before you start: pre-requirements Whichever method you use, confirm these first — they account for the majority of setup failures: * **MFA is mandatory.** The integration account must have Microsoft (Entra) MFA enabled. Third-party MFA tools do not satisfy this — the account will authenticate successfully but every subsequent API call will fail silently, with no data collected. You must actually be prompted for and complete an MFA challenge during the integration flow; an in-private/incognito browser window can help avoid cached sessions interfering with this. * **At least one active Microsoft 365 license must exist and be assigned in the tenant.** Brand-new tenants with zero assigned licenses will fail the integration with a connection error. * **Use a dedicated service account**, not a shared/personal admin account. MSPs that reuse a shared account for other admin work have broken the Augmentt integration by changing that account's roles or MFA method without realizing it disables Augmentt's monitoring for every customer connected through it. ## Recommended: create a dedicated Augmentt service account Rather than connecting with an individual's Global Admin account, create a purpose-built account for Augmentt: 1. **Create the user** in `admin.microsoft.com`: **Users > Active Users > Add User**. 2. **Assign a license** — ensure it includes at least an Exchange license, so Exchange Online–backed functionality works. 3. **Assign admin roles.** You have two options: * **Least privilege (recommended)** — assign only the specific Entra roles Augmentt requires (see the permissions table below). This list can grow as Augmentt ships new functionality, so expect an occasional role addition. * **Global Administrator** — broader access, but no ongoing role maintenance as new features ship. 4. **Enable Microsoft MFA** on the account (not a third-party MFA tool). 5. **Grant Partner Center access**, if using the CSP method: sign in to Partner Center with your existing CSP admin account, go to **Account Settings > User Management > Add user**, and add the new service account. 6. **Add the account to the AdminAgents security group** in Partner Center: go to **My Access**, select the account, choose **Assists your customer as > Admin agent**, and click **Update**. You can verify the service account is set up correctly by logging into Partner Center with it and confirming you can open **Customer List > \[a customer] > Admin Relationships** and create a new admin relationship — if that works, the account has what it needs. To switch an existing CSP integration over to the new service account: in Augmentt, go to **Configuration > Integrations**, use the **⋮** menu on the CSP tile to **Disconnect**, then reconnect using the new account's credentials. ## Minimum Entra roles | Role | What it grants | | --------------------------------------- | -------------------------------------------------------------------------------- | | Authentication Administrator | View/set/reset auth methods for non-admin users | | Authentication Policy Administrator | Manage auth methods policy, tenant-wide MFA settings, password protection policy | | Compliance Administrator | Read/manage compliance configuration and reports | | Conditional Access Administrator | Manage Conditional Access policies | | Exchange Administrator | Manage all aspects of Exchange | | Global Reader | Read everything a Global Admin can, without write access | | Groups Administrator | Create/manage groups and group settings | | License Administrator | Manage product licenses on users and groups | | Password Administrator | Reset passwords for non-admins and Password Administrators | | Privileged Authentication Administrator | View/set/reset auth methods for any user, including admins | | Privileged Role Administrator | Manage role assignments and Privileged Identity Management | | Security Administrator | Read security info/reports; manage security configuration | | SharePoint Administrator | Manage all aspects of SharePoint | | Teams Administrator | Manage Microsoft Teams | | Users Administrator | Manage users/groups, including limited-admin password resets | | Intune Administrator | Manage Microsoft Intune, where present | | Application Administrator | Manage app registrations and enterprise applications | {% hint style="info" %} Global Admin access avoids having to add roles over time as Augmentt ships features that need new scopes, at the cost of broader standing access. Least privilege is the recommended default; treat Global Admin as a maintenance trade-off, not a security downgrade you should avoid outright. {% endhint %} ## Option A: CSP integration (recommended for MSPs with Partner Center) **Part 1 — GDAP relationship (per customer tenant)** CSP-level connections to individual customer tenants require a GDAP (Granular Delegated Admin Privileges) relationship — Microsoft has made this mandatory for CSP integrations. 1. In Partner Center, go to **Customers**, select the tenant from the Customer List. 2. Click **Admin Relationships > Request for new relationship**. 3. Name the relationship (maximum duration is 730 days) and click **Select Microsoft Entra Roles**, choosing the roles listed above (organized in Partner Center under Collaboration / Identity / Security & Compliance groupings). 4. Click **Finalize Request** — this produces an approval link. Send this to the customer; a Global Administrator in the customer tenant must sign in and approve it. 5. Once approved, select the relationship, click **Add security groups**, choose **AdminAgents** (recommended), select all required permissions from the relationship, and **Save**. {% hint style="info" %} If an existing tenant later shows "missing roles" in Augmentt's GDAP audit, you don't need to recreate the relationship. Use the in-app GDAP link from **Configuration > Integrations > Manage CSP Setup** to extend the existing relationship with the missing role, then click **Delegate Access**. This doesn't apply to relationships that already grant Global Administrator. {% endhint %} **Part 2 — Connect in Augmentt** 1. In Augmentt, go to **Configuration > Integrations**, select your MSP Organization from the company selector, and click **Connect** on the **Microsoft 365 Cloud Solution Provider (CSP)** tile. 2. You'll be prompted for the service account's Global Administrator (or least-privilege) credentials up to four times. Each time, check **Consent on behalf of your organization** and click **Accept**. 3. Expect a spinner of up to \~45 seconds while Microsoft creates and propagates the Augmentt application — this is expected. 4. A confirmed connection shows a green **Connected** badge next to the account in the Microsoft 365 box. {% hint style="warning" %} If Microsoft's app propagation is slow, you may not get prompted for all four authentication steps. If this happens, disconnect and reconnect, then wait 2–3 minutes between prompts on retry rather than clicking straight through — this has been the fix in the cases we've seen. {% endhint %} **Part 3 — Map customers** 1. In Augmentt, from **Configuration > Integrations > M365 CSP**, click **Manage CSP Setup**. 2. For each Augmentt company, select the corresponding CSP account from the list. Accounts can only be mapped once, and the available list shrinks as you map more. 3. If a customer isn't yet in Augmentt, add it via **Configuration > Companies** first, or use **Create & Map Companies**, or use a [Magic Link](broken://pages/magic-links) if the customer doesn't yet have a GDAP relationship with you at all. 4. After saving a mapping, allow roughly 15 minutes for that customer's data to start collecting. 5. If you mis-map an account, select it and remove the mapping before re-mapping it correctly. ## Option B: Direct integration (non-CSP tenants) Augmentt continues to support direct integrations for tenants outside your CSP relationship — useful for running a security assessment to win a new customer, or managing clients who aren't provisioned through your Partner Center. 1. In Augmentt: **Configuration > Integrations**, click **Connect** on the **Microsoft 365** tile. 2. Sign in with a Global Administrator account **in the target tenant** (not your own MSP/partner tenant) — use an in-private browser window and allow pop-ups for augmentt.com and Microsoft login domains. 3. Accept the consent prompts (typically two rounds), checking **Consent on behalf of your organization** each time. 4. Confirm the green **Connected** badge appears. You can migrate a direct connection to a CSP-mapped connection later without losing existing client data — this just changes how future connection requests authenticate. ## Option C: Read-only integration (least privilege) For cases where you only need visibility — Secure posture scoring, inventory, and reporting — without any write actions, Augmentt supports a minimal, read-only GDAP relationship: * **Global Reader** — read access to tenant configuration, users, policies, licenses, and security data. * **Application Administrator** — required so Augmentt can deploy its enterprise application into the tenant; without it there's nothing for Augmentt to authenticate against on first connect. Set this up the same way as a standard GDAP relationship (see Option A, Part 1), assigning only these two roles. A customer Global Administrator must still approve it. Once approved, connect via **Configuration > Integrations > Microsoft 365 Cloud Service Provider (CSP)** as usual — on first connection Augmentt deploys its enterprise application, then runs ongoing collection against Global Reader. {% hint style="warning" %} Keep Application Administrator in the relationship even after the initial connection — it's needed again if Augmentt requests new scopes and the enterprise application needs to be reconsented. {% endhint %} **What read-only supports:** Secure posture score and Graph API–based posture items; user, group, license, and role inventory; risk detections and threat alerts; reporting. **What it does not support:** anything requiring write scopes — Engage password resets and user actions, Conditional Access policy creation/editing from Augmentt, MFA enforcement workflows, and Exchange Online PowerShell–backed posture items (anti-spam, DLP, safe attachments, shared mailbox details). {% hint style="info" %} The Magic Link flow (see [Magic Links](broken://pages/magic-links)) requests the broader standard permission set and cannot be used to set up a read-only deployment — build the read-only GDAP relationship manually in Partner Center instead. {% endhint %} To upgrade later from read-only to full functionality, replace the relationship with the full GDAP role set, or connect the tenant through a Magic Link. ## Dutch-tenant permission naming (regional variant) If your Partner Center or the customer tenant is configured with Dutch as the display language, the same Entra roles appear under Dutch names during the GDAP role-selection step. They map directly to the English roles above: | English role | Dutch label | | -------------------------------- | -------------------------------------- | | Exchange Administrator | Exchange-Beheerder | | Groups Administrator | Groepsbeheerder | | Teams Administrator | Teams-Beheerder | | SharePoint Administrator | SharePoint-beheerder | | Authentication Administrator | Verificatiebeheerder | | Conditional Access Administrator | Beheerder voor voorwaardelijke toegang | | Privileged Role Administrator | Bevoorrechte rolbeheerder | | License Administrator | Licentiebeheerder | | Password Administrator | Wachtwoordbeheerder | | Users Administrator | Gebruikersbeheerder | | Application Administrator | Toepassingsbeheerder | | Compliance Administrator | Beheerder voor naleving | | Security Administrator | Beveiligingsbeheerder | Select the same set of roles regardless of which language they're labeled in — the underlying Entra role and its permissions don't change. ## Confirming a successful connection After connecting by any method, you should see the account listed with a green **Connected** status in the relevant Microsoft 365 integration box. If a data collection run doesn't start within roughly 15 minutes of mapping a customer, treat that as a signal to check the connection rather than assume it's still catching up — see [M365 Integration Troubleshooting](broken://pages/m365-integration-troubleshooting). {% hint style="warning" %} Some UI labels here (button names, exact menu paths) reflect the underlying KB source content and may drift slightly from the current live product — the app codebase wasn't available to verify against while writing this page. Confirm current wording in the live Augmentt UI. {% endhint %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://helpdesk.augmentt.com/configuration/m365-integration-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.