> 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-troubleshooting.md). # M365 Integration Troubleshooting Use this page when a Microsoft 365 (CSP or direct) integration fails with a **Connection Error**, or a previously working integration stops collecting data. For initial setup, see [Microsoft 365 Integration Setup](broken://pages/m365-integration-setup). {% hint style="info" %} Most Connection Errors trace back to one of four causes: a missing pre-requisite (licensing, GDAP, AdminAgents membership, MFA), a Conditional Access policy blocking the integration, the integration account flagged as risky by Entra ID Protection, or a permission/credential change that broke consent. {% endhint %} ## Step 1 — Pre-flight checks Before digging into logs, re-confirm the basics for the integration type you're running. **CSP integration** * A GDAP relationship is in place and approved for the customer tenant. * The integration user is a member of the AdminAgents security group (or a GDAP security group carrying the required roles). * The integration user has Microsoft Authenticator (or another first-party Microsoft) MFA enabled, and can complete an MFA challenge live during the integration. Third-party MFA tools do not satisfy the CSP API requirement. * The customer tenant has at least one active Microsoft license assigned — brand-new, license-free tenants fail outright. * Expect a \~45 second propagation spinner. If you aren't prompted for all four authentication rounds, disconnect, reconnect, and wait 2–3 minutes between prompts rather than retrying immediately. **Direct integration** * Using an in-private/incognito browser window, with pop-ups allowed for augmentt.com and Microsoft login domains. * Signed in with a Global Administrator account **in the target tenant**, not your own MSP tenant. * At least one active Microsoft 365 license assigned in the target tenant. * The admin account completes MFA successfully using Microsoft MFA. If all of these check out and the error persists, the next most likely cause — by a wide margin — is Conditional Access. ## Step 2 — Conditional Access policy review A Conditional Access (CA) policy in the customer tenant is the most common cause of a Connection Error once the pre-flight items above are confirmed. It can block either the admin account completing consent, or — more commonly — the Augmentt service principal (workload identity) itself. 1. Sign in to the customer tenant at `https://entra.microsoft.com`. 2. Go to **Identity > Monitoring & health > Sign-in logs**. 3. Filter by **Application = Augmentt** (or by the admin UPN used), scoped to the last hour or so around the failed attempt. 4. Look for a **Failure** entry with reason "Access has been blocked by Conditional Access policies," often surfaced as error code **53003**. 5. Open the failed sign-in, go to the **Conditional Access** tab, and note which policy shows **Failure**. **To resolve:** * If the block is against the **admin user**: have the policy owner add a temporary exclusion for that user, re-run the integration, then revert the exclusion. * If the block is against the **Augmentt service principal / workload identity**: add Augmentt to the policy's **Excluded cloud apps**, or exclude the workload identity under **Target resources** (see Microsoft's [Conditional Access for workload identities](https://learn.microsoft.com/entra/identity/conditional-access/workload-identity) guidance). Real cases we've seen at this stage include deployed CAPs unexpectedly blocking legacy auth or requiring phishing-resistant MFA for admins in ways that catch the integration account, and customers asking whether Augmentt caused a CAP change they didn't recognize — Augmentt does not create or modify Conditional Access policies on its own; any change should be traceable to a person or an explicitly configured Augmentt Managed action. ## Step 3 — Entra ID Protection (Risky User) check If Conditional Access isn't the cause, check whether Entra ID Protection has flagged the integration account. 1. Sign in to `https://entra.microsoft.com`. 2. Go to **Protection > Identity Protection > Risky users**. 3. Search for the integration account's UPN. 4. If flagged **At risk**: have a Global Admin review the risk events, confirm they aren't malicious, and select **Confirm user safe** or **Dismiss user risk**. 5. Have the admin sign out everywhere and sign back in once before retrying the integration. ## Step 4 — Re-run the integration Once you've addressed the likely cause: 1. In Augmentt, open the affected customer: **Configuration > Integrations > Microsoft 365**. 2. Click **Disconnect** to clear the previous failed session. 3. Wait roughly 30 seconds for tokens to invalidate, then click **Connect**. 4. Accept all consent prompts — expect to be prompted for MFA twice. **Signs it worked:** * The integration tile shows a green **Connected** badge. * A data collection run starts (a refresh indicator appears in the top banner). * An "Integration created/connected" event appears under **Audit > Activity** for the customer. ## If the integration was previously healthy and just broke Before assuming something is broken on Augmentt's side, check: * Is the integration user still active — not disabled or deleted? * Was the password rotated recently? Some MFA methods require re-consent after a password change. * Have any role assignments been removed from the integration user? * If using GDAP, has the relationship expired (max duration is 730 days) or been revoked by the customer? * Has a new Conditional Access policy been deployed in the customer tenant recently? This is the single most common cause of a previously-healthy integration suddenly failing. If nothing obvious turns up, go back to Step 2 (Conditional Access review). ## "Missing roles" in the GDAP audit As Augmentt ships new functionality, the set of Entra roles required on a GDAP relationship can grow. Relationships created before a given feature shipped may then show as missing one or more roles — this doesn't mean anything changed on the customer's side. To fix: 1. In Augmentt: **Configuration > Integration**, select the M365 CSP tenant, click **Manage CSP Setup**. 2. For each affected tenant, use the **+** button to generate a new GDAP relationship link, and have it approved while signed in to the customer tenant. 3. Once approved, select the tenant(s) and click **Delegate Access** to assign the AdminAgents security group. The GDAP audit in Augmentt always shows which specific roles are missing per tenant. Relationships that already grant Global Administrator are unaffected by this check. {% hint style="info" %} Related symptom: if a specific feature fails with a permissions error like "User is not authorized to perform this operation," a missing role on that tenant's GDAP relationship is the usual root cause — check the GDAP audit before escalating. {% endhint %} ## Escalating to Augmentt Support If the integration still fails after working through the above, include the following in your support ticket so Support can go straight to tenant-side logs: * Integration type: Direct or CSP. * Screenshot of the error shown in the Augmentt UI. * Timestamp (UTC), to the minute, of the most recent failed attempt. * UPN of the admin account used to connect. * Confirmation that CA policies have been reviewed, including the name of any policy excluded or tested. * Tenant name (the customer's primary M365 domain) and the customer's name in Augmentt. Open a ticket at [support.augmentt.com](https://support.augmentt.com). ## Frequently asked questions **How long does setup take?** Under 10 minutes for a CSP integration — a sign-in with a couple of confirmation prompts, no PowerShell required. **What permissions do I need?** Either a Global Administrator account, or a least-privilege account with the specific roles listed in [Microsoft 365 Integration Setup](broken://pages/m365-integration-setup). Either way, the account must be a member of the AdminAgents security group in Partner Center — this is what lets Augmentt reach customer environments through the CSP APIs. Least-privilege accounts may occasionally need a new role added as Augmentt ships features; Global Admin avoids that at the cost of broader standing access. **Does this support GDAP?** Yes — Microsoft requires GDAP for CSP integrations. Augmentt can help upgrade legacy (non-GDAP) client relationships. **Is MFA required?** Yes. A CSP-level integration has access to all client environments, and Microsoft requires MFA for these connections. **How does authentication work?** Augmentt uses CSP-level Graph API and Exchange Online (EXO) API tokens through an application registered in the tenant, allowing it to gather data and run commands on your behalf. **Are there licensing requirements on the Augmentt side?** No — Augmentt functions on all Microsoft 365 license tiers. Higher tiers (e.g., Business Premium with Entra ID P1) unlock additional security features Augmentt can report on or act on, but aren't required to connect. **Are non-CSP (direct) tenants still supported?** Yes — useful for pre-sales security assessments or managing clients outside your CSP relationship. **Can I migrate an existing direct integration to CSP?** Yes — simply change the client's connection from direct to a CSP tenant mapping. All existing client data is retained; going forward, connection requests use the CSP method. {% hint style="warning" %} Exact error codes, menu paths, and timing figures (like the \~45 second propagation window) reflect the source KB content and may have shifted since — the product codebase wasn't available to verify against while writing this page. Confirm current behavior in the live product before relying on specifics here. {% 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-troubleshooting.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.