Microsoft 365

Microsoft 365 integration connects your agents to Mail, Calendar, Teams, SharePoint, OneDrive, and Word through Microsoft's Work IQ MCP servers (part of Microsoft 365 Copilot). A single catalog resource covers all six surfaces, and each user's account is automatically scoped to their own Microsoft tenant.

Prerequisites

• Microsoft 365 Copilot license assigned to every user who will access Microsoft 365 tools through the gateway. The integration is built on Microsoft's Agent Tools API (ea9ffc3e-.../.default), which only operates in tenants with active Copilot licensing. Both credential modes below depend on this — Bring-Your-Own-App does not sidestep it.
• A Microsoft Entra admin with consent privileges (Global Administrator, Application Administrator, or Cloud Application Administrator) in your tenant.
• If admin consent fails with AADSTS650052 even after Copilot licenses are assigned, see Troubleshooting AADSTS650052 — Microsoft provisions the Agent Tools service principal lazily, and a one-time fix is required on fresh Copilot deployments.

Setup

1. Navigate to Resources and click Add Resource
2. Select Microsoft 365 from the catalog
3. Choose a credential mode (see below)
4. Click Add

The resource is added with all tools and scopes pre-configured. Each user connects their own Microsoft 365 account via OAuth when they first use a Microsoft 365 tool. Navigate to Connections to manage linked accounts.

Credential modes

Microsoft 365 supports two modes:

• Use SecureAuth's app — install instantly with SecureAuth's pre-registered multi-tenant Entra application. No setup on your side. Recommended for most installs.
• Bring your own app — use an Entra app registration owned by your tenant. Recommended for organizations that require admin-consented apps under their own tenant for compliance, conditional access, or auditing.

See Credential modes for the full comparison.

Use SecureAuth's app

Install instantly with SecureAuth's pre-registered multi-tenant Entra application. No setup on your side beyond admin consent.

The Entra admin opens this URL in a browser while signed in with consent privileges, and clicks Accept on the consent page:

https://login.microsoftonline.com/organizations/adminconsent?client_id=c96ff7c8-cea6-41a6-b06d-47433d87e3c1

Users in your tenant can sign in to the gateway after consent is granted. Without this step, end users see a "your administrator must approve this app" error on first sign-in.

After clicking Accept, you may briefly see a "Something went wrong" page on the SecureAuth side. This is expected when using the standalone admin-consent URL above — consent has been recorded with Microsoft, and you can proceed to add the Microsoft 365 resource through your AI Security workspace.

This admin-consent URL workflow is in place while SecureAuth completes Microsoft Publisher Verification. After verification lands, customer admins will also be able to grant consent through Azure portal's standard Enterprise applications UI, and the "unverified publisher" warning shown during consent today will no longer appear.

Bring your own app

Use an Entra app registration owned by your tenant. Recommended for organizations that require admin-consented apps under their own tenant for compliance, conditional access, or auditing.

The flow has three phases: collect the redirect URI from SecureAuth, register and configure the app in Microsoft Entra, then return to SecureAuth with the credentials.

SecureAuth side — get the redirect URI. In your AI Security workspace, go to Resources > Add Resource > Microsoft 365 > Bring your own app and copy the redirect URI shown in the dialog. Keep the dialog open — you will return to it at the end of this flow to paste the Client ID and Client Secret.

Entra ID side — register and configure the app. Sign in to portal.azure.com and navigate to Microsoft Entra ID > App registrations > New registration.

1. Register the app. Configure:

• Name — your preferred name (for example, <your-company> AI Gateway)
• Supported account types — Multiple Entra ID tenants, with Allow all tenants as the sub-option (the default). Multi-tenant is required because the SecureAuth gateway's OAuth flow uses Microsoft's /common endpoint, which does not accept single-tenant apps.
• Redirect URI — choose Web platform and paste the redirect URI you copied from AI Security

Click Register.

2. Configure API permissions. On the new app's API permissions page, click Add a permission. The gateway needs delegated permissions from two APIs:

• Microsoft Graph — in the Add a permission dialog, select Microsoft Graph > Delegated permissions and add all 13 scopes below. The four OIDC scopes (email, offline_access, openid, profile) live under the OpenId permissions section near the bottom of the picker — easy to miss because they are not in the main alphabetical list.

  • Calendars.ReadWrite
  • ChannelMessage.Read.All
  • ChannelMessage.Send
  • Chat.ReadWrite
  • email
  • Files.ReadWrite.All
  • Mail.ReadWrite
  • Mail.Send
  • offline_access
  • openid
  • profile
  • Sites.ReadWrite.All
  • User.Read

• Agent Tools — in the Add a permission dialog, switch to APIs my organization uses and search for "Agent Tools." If "Agent Tools" does not appear in the search results, see Troubleshooting AADSTS650052 below — the Agent Tools service principal needs to be provisioned in your tenant first. Once found, click Agent Tools > Delegated permissions and check all permissions in both the McpServers and McpServers Metadata permission groups (roughly 37 total).

3. Grant admin consent. After adding permissions from both APIs, click Grant admin consent for <your tenant> at the top of the API permissions list. Confirm that every row shows a green checkmark in the Status column.

4. Create a client secret. On Certificates & secrets, click New client secret, set an expiry, and copy the secret value immediately — Microsoft only displays it once. This is your Client Secret.

5. Copy the Application (client) ID from the app's Overview page.

SecureAuth side — enter your credentials. Return to your AI Security workspace's Bring-your-own-app dialog (still open from the first step). Paste the Client ID and Client Secret, then click Add. The Microsoft 365 resource is now configured for your tenant, and users can begin connecting their accounts through Connections.

Troubleshooting AADSTS650052

The Agent Tools service principal must exist in your tenant before either credential mode works. Microsoft creates it lazily — only after a licensed user actively uses Copilot for the first time — so a fresh Copilot deployment commonly hits this gap. Symptoms differ by credential mode:

• Use SecureAuth's app — admin consent fails with AADSTS650052 ("your organization lacks a service principal for Agent Tools")
• Bring your own app — "Agent Tools" does not appear when you search for it in API permissions → Add a permission → APIs my organization uses, or admin consent on your own app fails with AADSTS650052 after the permissions are added

Force-create the service principal once via Microsoft Graph and both symptoms clear for the entire tenant:

1. Open Microsoft Graph Explorer

2. Sign in (top-right avatar) as a tenant admin

3. Set the request to:

   • Method: POST
   • Version: v1.0
   • URL: https://graph.microsoft.com/v1.0/servicePrincipals

4. On the Request body tab, paste:

   { "appId": "ea9ffc3e-8a23-4a7d-836d-234d7c7565c1" }

5. Click Run query. If prompted for additional permissions, consent to Application.ReadWrite.All and re-run the query.

6. A 201 Created response with "displayName": "Agent Tools" confirms the service principal was created.

7. Return to your original setup flow:

   • Use SecureAuth's app — retry the admin-consent URL; AADSTS650052 should no longer appear:

     https://login.microsoftonline.com/organizations/adminconsent?client_id=c96ff7c8-cea6-41a6-b06d-47433d87e3c1

   • Bring your own app — go back to your app's API permissions page in Azure portal, click Add a permission > APIs my organization uses, and search for "Agent Tools." The API should now appear, and you can continue with the Agent Tools permissions step in the Bring your own app section above.

This is a one-time operation per tenant.

The Agent Tools service principal alone does not grant tool access — users still need a Microsoft 365 Copilot license assigned to actually call tools through the gateway. The workaround only resolves the missing-service-principal error encountered during admin consent.

Available tools

Mail — search & read

Mail — drafts & sending

Mail — reply & forward

Mail — manage

Mail — attachments

Calendar — events

Calendar — invitations

Calendar — scheduling

Teams

User

Required scopes

• openid, profile — sign-in identity
• offline_access — maintain access when the user is offline
• User.Read — read the signed-in user's profile
• Mail.ReadWrite — read, create, update, and delete mail
• Mail.Send — send mail as the signed-in user
• Calendars.ReadWrite — read and write calendar events
• Chat.ReadWrite — read and write Teams chat messages
• ChannelMessage.Read.All — read Teams channel messages
• ChannelMessage.Send — send Teams channel messages
• Files.ReadWrite.All — read and write OneDrive and SharePoint files
• Sites.ReadWrite.All — read and write SharePoint site content

Policy examples

• Allow read-only access: tool patterns Search*, Get*, List*, Download*, Find*
• Block sending and replies: deny rules for Send*, Reply*, Forward* above any allow rules
• Block destructive operations: deny rules for Delete*, Cancel*, Update*
• Allow mail triage but block calendar changes: allow *Message*, Get*, Search*, then deny *Event* (still permits read via ListEvents if you allow it explicitly above the deny)
• Allow full access for a specific agent: scope an allow rule for * to that agent on this MCP server