> 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-and-permissions.md). # M365 Integration & Permissions Augmentt's Microsoft 365 integration is the foundation for Secure and Engage. This article covers what's required to connect, and exactly what each requested permission scope is used for — useful when a client's security or compliance team asks "why does Augmentt need this?" ## Integration requirements * The integration account requires **Global Admin** privileges. * The account needs a valid license **with a mailbox**. Engage sends email through this account for actions like password resets, account creation notifications, and mailbox delegation — without a mailbox, those emails can't be sent. {% hint style="info" %} Augmentt uses a least-privilege approach where possible, but because Augmentt performs a wide range of functions across Secure (posture, MFA, threat detection) and Engage (user lifecycle management), it requires a correspondingly broad set of Graph API and Exchange Online scopes. The table below is the full breakdown. {% endhint %} ## Graph API permission scopes | Scope | Permission Name | What it's used for in Augmentt | | ------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Application.ReadWrite.All` | Read and write applications | Retrieves and stores tenant applications for Conditional Access Policy management under Secure's Admin/User MFA configuration | | `AuditLog.Read.All` | Read audit log data | Reads Unified Audit Log state for the Unified Audit Log posture item in Secure | | `Directory.AccessAsUser.All` | Access the directory as you | Impersonation as the signed-in user; enables user/group deletion | | `Directory.Read.All` | Read directory data | Retrieves users, groups, roles, and licenses in use by the tenant | | `IdentityRiskEvent.Read.All` | Read identity risk event information | Pulls identity risk detections directly from Microsoft for Threat Alerts | | `IdentityRiskyUser.Read.All` | Read identity risky user information | Populates the Threat Report's Risk Detections view in Secure | | `Mail.Send` | Send mail as you | Used exclusively for sending password-reset emails from User Management's Reset Password action | | `Organization.Read.All` | Read organization information | Powers anything using roles/licenses/groups in Secure; also pulls tenant branding for the Login Portal Branding posture item | | `Policy.Read.All` | Read your organization's policies | Feeds Risky Country and Risky IP policy checks in Security Posture | | `Policy.ReadWrite.ConditionalAccess` | Read/write Conditional Access policies | Secure reads/writes Conditional Access policies for Admin/User MFA configuration; Engage creates a dedicated "Augmentt-do-not-modify" policy for managing user MFA | | `Reports.Read.All` | Read all usage reports | Pulls `selfPasswordResetEnabled` state (tenant and user level) for the Self-Service Password Reset posture item | | `SecurityEvents.Read.All` | Read your organization's security events | Pulls Secure Score and risky sign-in events | | `User.Read` | Sign you in and read your profile | Basic sign-in and profile access for MFA status, groups, licenses in Secure/User Management | | `User.Read.All` | Read all users' full profiles | Retrieves the full tenant user list to sync as Augmentt employees | | `UserAuthenticationMethod.Read.All` | Read all users' authentication methods | Feeds the MFA authentication method report in Secure | | `profile` | Read your profile | Used during initial integration sign-in | | `openid` | Maintain access to data you have given access to | Session management and continuous sign-in | | `email` | Read your signed-in user's email address | Used during initial integration sign-in | ## Exchange Online (PowerShell) API scopes | Scope | What it's used for | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `profile`, `openid`, `email` | Sign-in and session management, same as above | | `user_impersonation` | Full delegated PowerShell access as the signed-in admin — this is the scope behind most of Augmentt's Exchange-dependent features | `user_impersonation` specifically powers PowerShell-driven access to: * SharePoint data * Shared mailboxes and shared mailbox members * Anti-spam policies * DLP policies * User groups / distribution / shared mailboxes * Enabling/disabling Azure per-user MFA * User authentication method lists (auth methods per user) * Safe Attachments * Password reset policies * Teams data ## Common issues **"Missing scope" errors on a specific feature.** If you see an error like "There is a missing scope required for this feature. Re-authenticate to grant permission to the following..." — this means the integration was originally consented to before a newer feature (needing an additional scope) was released. The fix is to re-authenticate/reconnect the integration so the tenant admin can consent to the newer scope set; it does not mean anything is broken with your existing setup. **MFA management actions (Re-Register MFA, Temporary Access Pass) blocked despite correct-looking GDAP roles.** This has come up even when GDAP relationships are active, auto-renew is enabled, and all recommended Entra roles (Authentication Administrator, Privileged Authentication Administrator, User Administrator, Security Administrator, Conditional Access Administrator, etc.) are assigned. If role assignment looks correct but the action is still blocked, the integration's token may not have picked up the current scope/role set — re-authenticating the integration is the first troubleshooting step; if that doesn't resolve it, escalate to support with the tenant and affected user. **Clearing a user's MFA/authentication method fails with a "cannot be deleted" error.** If removing a registered authentication method fails because it's currently the user's *default* method, set a different method as default first, then remove the old one. This is a Microsoft Graph constraint, not an Augmentt limitation. {% hint style="warning" %} Permission scopes and their exact in-product uses can change as Augmentt ships new features. Treat the table above as accurate as of this migration but verify against the live consent screen and current release notes before using it to answer a client security questionnaire verbatim. {% 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-and-permissions.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.