Secure Microsoft 365 access for AI agents

Through Microsoft 365, agents can read and send mail, manage calendar events, read Teams meeting transcripts and Copilot insights, and reach SharePoint, OneDrive, and Word content. Every call runs through your policies and is logged for audit. A single catalog resource covers all six surfaces, scoped to each user's own Microsoft tenant.

This resource has no single server URL. The gateway builds six endpoints, one each for Mail, Calendar, Teams, SharePoint, OneDrive, and Word, from the tenant ID in the signed-in user's token.

Credential modesCopy Anchor Link

Microsoft 365 supports two modes:

• Use SecureAuth's app – uses SecureAuth's pre-registered multi-tenant Entra application, so there is no app to register in Azure. Recommended for most installs.
• Bring your own app – uses an Entra app registration your tenant owns. Choose this when you need admin-consented apps under your own tenant for compliance, conditional access, or auditing.

See Credential modes for how the modes compare.

Before you beginCopy Anchor Link

• A Microsoft 365 Copilot license for every user who will reach Microsoft 365 tools through the gateway. This integration is built on Microsoft's Agent Tools API, which only operates in tenants with active Copilot licensing. Both options depend on it, and bringing your own app does not sidestep it.
• A Microsoft Entra admin with consent privileges: Global Administrator, Application Administrator, or Cloud Application Administrator.
• Administrator access to your Agent Authority workspace, to add the resource.

Both options need admin consent in your tenant before users can connect. Option 1 grants it at a single URL outside the console. Option 2 also moves between two consoles: you copy a redirect URI in the Agent Authority console, register an app in Microsoft Entra and grant consent there, then return to the console and paste the credentials. Keep both tabs open if you take option 2.

SetupCopy Anchor Link

In the Agent Authority console, go to Resources → Add Resource and select Microsoft 365 Work IQ, which is the name this resource carries in the catalog. Because it supports two credential modes, the console asks you to choose how to install it and shows a card for each mode. Click the card for the option you want, then follow that option below.

Either way, an Admin setup required dialog appears once the resource is added. Its View setup guide button links back to whichever option below matches the mode you picked.

Option 1: Use SecureAuth's appCopy Anchor Link

Picking this option installs the resource immediately, using SecureAuth's pre-registered multi-tenant Entra application, with all tools and scopes pre-configured.

One step remains, and it happens outside the console. An Entra admin with consent privileges opens this URL in a browser while signed in, then clicks Accept:

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

Until consent is granted, users in your tenant see a "your administrator must approve this app" error on first sign-in. Microsoft also shows an unverified-publisher warning on the consent page. That is expected. This URL is the supported way to grant consent today.

If consent fails with AADSTS650052, see Troubleshooting AADSTS650052.

Option 2: Bring your own appCopy Anchor Link

Picking this option opens the credentials form. Step 1 starts there.

1. Copy the redirect URICopy Anchor Link

Copy the Redirect URI shown on the form, using the Copy button next to it. It includes your tenant's region, so copy it rather than typing it. It takes the form https://oauth.aisecurity.services.<region>.connect.secureauth.com/auth/callback.

Leave this page open. You come back to it in step 4.

2. Register an Entra app in AzureCopy Anchor Link

Sign in to portal.azure.com and go to Microsoft Entra ID → App registrations → New registration.

Register the app. Configure:

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

Click Register.

Add the Microsoft Graph permissions. On the new app's API permissions page, click Add a permission → Microsoft Graph → Delegated permissions, and add the 13 Graph scopes listed under Required scopes.

The four OpenID Connect scopes (email, offline_access, openid, profile) live under the OpenId permissions section near the bottom of the picker, which is easy to miss because they are not in the main alphabetical list.

Add the Agent Tools permissions. Click Add a permission again, switch to the APIs my organization uses tab, and search for Agent Tools. Click Agent Tools → Delegated permissions and select every permission in both the McpServers and McpServers Metadata groups, roughly 37 in total.

If Agent Tools does not appear in the search results, the service principal is missing from your tenant. See Troubleshooting AADSTS650052.

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

Then copy the Application (client) ID from the app's Overview page. This is your Client ID.

3. Grant admin consentCopy Anchor Link

Back on the API permissions page, click Grant admin consent for <your tenant> at the top of the permissions list. Confirm that every row shows a green checkmark in the Status column.

4. Finish in the consoleCopy Anchor Link

Back on the Microsoft 365 form in the Agent Authority console, paste the Client ID and Client Secret. Leave Token Endpoint Authentication on Auto-detect. Then click Add.

The resource is added with all tools and scopes pre-configured.

Troubleshooting AADSTS650052Copy Anchor Link

The Agent Tools service principal has to exist in your tenant before either option 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. The symptom depends on the option you took:

• Option 1 – admin consent fails with AADSTS650052 ("your organization lacks a service principal for Agent Tools")
• Option 2 – Agent Tools does not appear when you search for it under 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 through Microsoft Graph and both symptoms clear for the whole tenant:

1. Open Microsoft Graph Explorer

2. Sign in as a tenant admin, using the avatar at the top right

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:

   Copy Text

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

5. Click Run query. If you are prompted for extra permissions, consent to Application.ReadWrite.All and run the query again.

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

This is a one-time operation per tenant. Then return to whichever option you were following: retry the admin-consent URL in option 1, or search for Agent Tools again in option 2.

Verify the connectionCopy Anchor Link

The gateway syncs the Microsoft 365 tools automatically. To check the connection end to end, ask your agent to run a read-only request:

Show my Microsoft 365 time zone and working hours

If your time zone, working hours, and language come back, the connection is working.

How users connectCopy Anchor Link

Access is per user. Each additional user connects their own Microsoft 365 account the first time their agent calls a Microsoft 365 tool: the gateway returns a sign-in link, the user authorizes once, and the tools work from then on. Go to Connections to manage linked accounts.

Each call uses the signed-in user's own token, so Microsoft 365's own permissions control what they can reach. The gateway does not widen access beyond what the authenticated user could already do in Microsoft 365.

Available toolsCopy Anchor Link

The Mail, Calendar, and User tools below ship with the catalog entry, so they appear in tool lists and policy pickers as soon as the resource is installed. The Teams tools, and anything the SharePoint, OneDrive, and Word endpoints serve, are discovered from your tenant when the first user connects their account, so they show up only after that first connection.

Mail – search & readCopy Anchor Link

Mail – drafts & sendingCopy Anchor Link

Mail – reply & forwardCopy Anchor Link

Mail – manageCopy Anchor Link

Mail – attachmentsCopy Anchor Link

Calendar – eventsCopy Anchor Link

Calendar – invitationsCopy Anchor Link

Calendar – schedulingCopy Anchor Link

UserCopy Anchor Link

TeamsCopy Anchor Link

SecureAuth discovers these two tools from your Microsoft 365 account on first connection. They carry no built-in tags because they are not in the catalog entry:

Required scopesCopy Anchor Link

These are the scopes the gateway sends in the authorize request, and they are the same in both options:

• openid, profile – sign-in identity
• offline_access – maintain access when the user is offline
• ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default – the Agent Tools API, which is what actually reaches Mail, Calendar, Teams, SharePoint, OneDrive, and Word

The .default scope carries whatever delegated permissions have already been consented for the app in your tenant. That is why the individual permissions are granted at the app registration rather than requested here.

With SecureAuth's app those permissions come pre-registered, and the admin-consent URL grants them. With your own app you add them by hand in the Azure portal, from two APIs:

Microsoft Graph, 13 delegated permissions:

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, roughly 37 delegated permissions: every entry in the McpServers and McpServers Metadata groups.

Policy examplesCopy Anchor Link

Rules are evaluated top to bottom and the first match wins. Allow rules on their own restrict nothing, because your org starts with a seeded Allow all rule, so any tool your allows don't cover still falls through to it. A restrictive recipe needs a catch-all deny scoped to this resource, ordered below the allows. New rules are inserted at the top of the list, so create them in reverse order or drag them into place. See Policies.

• Read-only access. Allow Search*, Get*, List*, Download*, and Find*, then deny * below them.
• Block sending and replies. Deny Send*, Reply*, and Forward* above any allow rules.
• Block destructive operations. Deny Delete*, Cancel*, and Update*.
• Allow mail triage but block calendar changes. Allow *Message*, Get*, and Search*, then deny *Event*, then deny * (ListEvents still reads if you allow it explicitly above the *Event* deny).
• Allow full access for a specific agent. Scope an allow rule for * to that agent on this MCP server.
• Block destructive tools. Add a deny rule with the built-in destructive tag (Tools pill) for this resource (MCP pill).

Tool patterns are case-sensitive and match exactly unless they contain *, so the PascalCase prefixes above (Get*, not get_*) are what match Microsoft 365 tool names.

Next stepsCopy Anchor Link

• Create a policy – start from the read-only pattern in Policy examples above.
• Connections – manage the Microsoft 365 accounts your users have linked.