Microsoft

The Microsoft auth provider enables tools and agents to call the Microsoft Graph API  on behalf of a user. It supports Arcade’s MCP servers for Outlook Calendar, Outlook Mail, Microsoft Teams, and SharePoint, as well as your own custom tools and app code.

On this page

• Configure Microsoft auth — three options depending on your security posture
• Production readiness — custom user verifier, admin consent, conditional access
• MCP server scopes reference — which permissions each MCP server requires
• Use Microsoft auth in app code — get a user token for Graph API calls
• Use Microsoft auth in custom tools — build tools that call Graph APIs

Configure Microsoft auth

Arcade supports three ways to connect Microsoft auth. Choose based on your team’s security requirements and how much control you need over the Azure app registration.

Option 1: Use Arcade’s included provider

The fastest path. Arcade provides a pre-configured Microsoft OAuth app — no Azure app registration required. Your IT or security team approves the app in Microsoft Entra ID, and you’re ready to go.

Trade-off: The granted scopes are tied to the specific agent use case. If you add MCP servers or tools that require additional permissions, your security team will need to approve the updated scope set.

Option 2: Register a multi-tenant Azure app

Register your own app in Azure to get full control over branding, permissions, and token policies. This configuration allows users from any Azure AD tenant to authenticate.

Option 3: Register a tenant-specific Azure app

Restrict authentication to a single Microsoft Entra ID tenant. Use this when your organization’s security policy requires tenant isolation.

Production readiness

Custom user verifier

For Options 2 and 3, where you bring your own Azure app credentials, you must configure a custom user verifier before deploying to production.

Without a custom verifier, your end-users would need an Arcade.dev account to complete the OAuth flow — which is not what you want in a production environment. The custom verifier lets your application handle user identity, so the auth flow stays within your own UX.

Enterprise environment configuration

For organizations that require additional security controls beyond the app registration:

1. Admin consent and conditional access:

   • Go to Enterprise Applications in Azure Portal
   • Find your application
   • Configure conditional access policies as required by your security team
   • Set up user assignment requirements to control which users can authorize
   • Grant tenant-wide admin consent if needed

2. Security team coordination:

   • Review the required permissions per MCP server with your security team before granting consent
   • Ensure conditional access policies don’t block Microsoft Graph API access
   • Configure token lifetime policies that align with your organization’s session management standards

If you have multiple Microsoft providers configured in Arcade, see using multiple auth providers of the same type.

MCP server scopes reference

Each Arcade Microsoft MCP server requires a specific set of Microsoft Graph API delegated permissions. The table below summarizes the scopes per server. For a detailed breakdown of scopes per tool, including API endpoints, see permissions and scopes.

Use Microsoft auth in app code

Use the Microsoft auth provider in your agents and AI apps to get a user token for Microsoft Graph APIs. See authorizing agents with Arcade to understand how this works.

Use client.auth.start() to get a user token for Microsoft Graph APIs:

from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "{arcade_user_id}"
 
# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="microsoft",
    scopes=["User.Read", "Files.Read"],
)
 
if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)
 
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
 
token = auth_response.context.token
# TODO: Do something interesting with the token...

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade();
 
const userId = "{arcade_user_id}";
 
// Start the authorization process
let authResponse = await client.auth.start(userId, "microsoft", {
  scopes: ["User.Read", "Files.Read"],
});
 
if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}
 
// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);
 
const token = authResponse.context.token;
// TODO: Do something interesting with the token...

Use Microsoft auth in custom tools

You can build your own custom tools that interact with Microsoft Graph APIs.

Use the Microsoft() auth class to specify that a tool requires authorization with Microsoft. The context.authorization.token field is automatically populated with the user’s Microsoft token:

from typing import Annotated
 
import httpx
 
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import Microsoft
 
 
@tool(
    requires_auth=Microsoft(
        scopes=["User.Read", "Files.Read"],
    )
)
async def get_file_contents(
    context: ToolContext,
    file_id: Annotated[str, "The ID of the file to get the contents of"],
) -> Annotated[str, "The contents of the file"]:
    """Get the contents of a file from Microsoft Graph."""
    url = f"https://graph.microsoft.com/v1.0/me/drive/items/{file_id}"
    headers = {"Authorization": f"Bearer {context.authorization.token}"}
 
    async with httpx.AsyncClient() as client:
        response = await client.get(
            url=url,
            headers=headers,
        )
        response.raise_for_status()
        return response.json()