prefecthq--fastmcp/docs/integrations/azure.mdx

---
title: Azure (Microsoft Entra ID) OAuth 🤝 FastMCP
sidebarTitle: Azure (Entra ID)
description: Secure your FastMCP server with Azure/Microsoft Entra OAuth
icon: microsoft
---

import { VersionBadge } from "/snippets/version-badge.mdx"

<VersionBadge version="2.13.0" />

This guide shows you how to secure your FastMCP server using **Azure OAuth** (Microsoft Entra ID). Since Azure doesn't support Dynamic Client Registration, this integration uses the [**OAuth Proxy**](/servers/auth/oauth-proxy) pattern to bridge Azure's traditional OAuth with MCP's authentication requirements. FastMCP validates Azure JWTs against your application's client_id.

## Configuration

### Prerequisites

Before you begin, you will need:
1. An **[Azure Account](https://portal.azure.com/)** with access to create App registrations
2. Your FastMCP server's URL (can be localhost for development, e.g., `http://localhost:8000`)
3. Your Azure tenant ID (found in Azure Portal under Microsoft Entra ID)

### Step 1: Create an Azure App Registration

Create an App registration in Azure Portal to get the credentials needed for authentication:

<Steps>
<Step title="Navigate to App registrations">
    Go to the [Azure Portal](https://portal.azure.com) and navigate to **Microsoft Entra ID → App registrations**.
    
    Click **"New registration"** to create a new application.
</Step>

<Step title="Configure Your Application">
    Fill in the application details:
    
    - **Name**: Choose a name users will recognize (e.g., "My FastMCP Server")
    - **Supported account types**: Choose based on your needs:
      - **Single tenant**: Only users in your organization
      - **Multitenant**: Users in any Microsoft Entra directory
      - **Multitenant + personal accounts**: Any Microsoft account
    - **Redirect URI**: Select "Web" and enter your server URL + `/auth/callback` (e.g., `http://localhost:8000/auth/callback`)
    
    <Warning>
    The redirect URI must match exactly. The default path is `/auth/callback`, but you can customize it using the `redirect_path` parameter. For local development, Azure allows `http://localhost` URLs. For production, you must use HTTPS.
    </Warning>
    
    <Tip>
    If you want to use a custom callback path (e.g., `/auth/azure/callback`), make sure to set the same path in both your Azure App registration and the `redirect_path` parameter when configuring the AzureProvider.
    </Tip>

    - **Expose an API**: Configure your Application ID URI and define scopes
      - Go to **Expose an API** in the App registration sidebar.
      - Click **Set** next to "Application ID URI" and choose one of:
        - Keep the default `api://{client_id}`
        - Set a custom value, following the supported formats (see [Identifier URI restrictions](https://learn.microsoft.com/en-us/entra/identity-platform/identifier-uri-restrictions))
      - Click **Add a scope** and create a scope your app will require, for example:
        - Scope name: `read` (or `write`, etc.)
        - Admin consent display name/description: as appropriate for your org
        - Who can consent: as needed (Admins only or Admins and users)

    - **Configure Access Token Version**: Ensure your app uses access token v2
      - Go to **Manifest** in the App registration sidebar.
      - Find the `requestedAccessTokenVersion` property and set it to `2`:
        ```json
        "api": {
            "requestedAccessTokenVersion": 2
        }
        ```
      - Click **Save** at the top of the manifest editor.

    <Warning>
    Access token v2 is required for FastMCP's Azure integration to work correctly. If this is not set, you may encounter authentication errors.
    </Warning>

    <Note>
    In FastMCP's `AzureProvider`, set `identifier_uri` to your Application ID URI (optional; defaults to `api://{client_id}`) and set `required_scopes` to the unprefixed scope names (e.g., `read`, `write`). During authorization, FastMCP automatically prefixes scopes with your `identifier_uri`.
    </Note>


</Step>


<Step title="Create Client Secret">
    After registration, navigate to **Certificates & secrets** in your app's settings.
    
    - Click **"New client secret"**
    - Add a description (e.g., "FastMCP Server")
    - Choose an expiration period
    - Click **"Add"**
    
    <Warning>
    Copy the secret value immediately - it won't be shown again! You'll need to create a new secret if you lose it.
    </Warning>
</Step>

<Step title="Note Your Credentials">
    From the **Overview** page of your app registration, note:
    
    - **Application (client) ID**: A UUID like `835f09b6-0f0f-40cc-85cb-f32c5829a149`
    - **Directory (tenant) ID**: A UUID like `08541b6e-646d-43de-a0eb-834e6713d6d5`
    - **Client Secret**: The value you copied in the previous step
    
    <Tip>
    Store these credentials securely. Never commit them to version control. Use environment variables or a secrets manager in production.
    </Tip>
</Step>
</Steps>

### Step 2: FastMCP Configuration

Create your FastMCP server using the `AzureProvider`, which handles Azure's OAuth flow automatically:

```python server.py
from fastmcp import FastMCP
from fastmcp.server.auth.providers.azure import AzureProvider

# The AzureProvider handles Azure's token format and validation
auth_provider = AzureProvider(
    client_id="835f09b6-0f0f-40cc-85cb-f32c5829a149",  # Your Azure App Client ID
    client_secret="your-client-secret",                 # Your Azure App Client Secret
    tenant_id="08541b6e-646d-43de-a0eb-834e6713d6d5", # Your Azure Tenant ID (REQUIRED)
    base_url="http://localhost:8000",                   # Must match your App registration
    required_scopes=["your-scope"],                 # At least one scope REQUIRED - name of scope from your App
    # identifier_uri defaults to api://{client_id}
    # identifier_uri="api://your-api-id",
    # Optional: request additional upstream scopes in the authorize request
    # additional_authorize_scopes=["User.Read", "openid", "email"],
    # redirect_path="/auth/callback"                  # Default value, customize if needed
    # base_authority="login.microsoftonline.us"      # For Azure Government (default: login.microsoftonline.com)
)

mcp = FastMCP(name="Azure Secured App", auth=auth_provider)

# Add a protected tool to test authentication
@mcp.tool
async def get_user_info() -> dict:
    """Returns information about the authenticated Azure user."""
    from fastmcp.server.dependencies import get_access_token
    
    token = get_access_token()
    # The AzureProvider stores user data in token claims
    return {
        "azure_id": token.claims.get("sub"),
        "email": token.claims.get("email"),
        "name": token.claims.get("name"),
        "job_title": token.claims.get("job_title"),
        "office_location": token.claims.get("office_location")
    }
```

<Note>
**Important**: The `tenant_id` parameter is **REQUIRED**. Azure no longer supports using "common" for new applications due to security requirements. You must use one of:

- **Your specific tenant ID**: Found in Azure Portal (e.g., `08541b6e-646d-43de-a0eb-834e6713d6d5`)
- **"organizations"**: For work and school accounts only
- **"consumers"**: For personal Microsoft accounts only

Using your specific tenant ID is recommended for better security and control.
</Note>

<Note>
**Important**: The `required_scopes` parameter is **REQUIRED** and must include at least one scope. Azure's OAuth API requires the `scope` parameter in all authorization requests - you cannot authenticate without specifying at least one scope. Use the unprefixed scope names from your Azure App registration (e.g., `["read", "write"]`). These scopes must be created under **Expose an API** in your App registration.
</Note>

### Scope Handling

FastMCP automatically prefixes `required_scopes` with your `identifier_uri` (e.g., `api://your-client-id`) since these are your custom API scopes. Scopes in `additional_authorize_scopes` are sent as-is since they target external resources like Microsoft Graph.

**`required_scopes`** — Your custom API scopes, defined in Azure "Expose an API":

| You write | Sent to Azure | Validated on tokens |
|-----------|---------------|---------------------|
| `mcp-read` | `api://xxx/mcp-read` | ✓ |
| `my.scope` | `api://xxx/my.scope` | ✓ |
| `openid` | `openid` | ✗ (OIDC scope) |
| `api://xxx/read` | `api://xxx/read` | ✓ |

**`additional_authorize_scopes`** — External scopes (e.g., Microsoft Graph) for server-side use:

| You write | Sent to Azure | Validated on tokens |
|-----------|---------------|---------------------|
| `User.Read` | `User.Read` | ✗ |
| `Mail.Send` | `Mail.Send` | ✗ |

<Note>
`offline_access` is automatically included to obtain refresh tokens. FastMCP manages token refreshing automatically.
</Note>

<Info>
**Why aren't `additional_authorize_scopes` validated?** Azure issues separate tokens per resource. The access token FastMCP receives is for *your API*—Graph scopes aren't in its `scp` claim. To call Graph APIs, your server uses the upstream Azure token in an on-behalf-of (OBO) flow.
</Info>

<Note>
OIDC scopes (`openid`, `profile`, `email`, `offline_access`) are never prefixed and excluded from validation because Azure doesn't include them in access token `scp` claims.
</Note>

## Testing

### Running the Server

Start your FastMCP server with HTTP transport to enable OAuth flows:

```bash
fastmcp run server.py --transport http --port 8000
```

Your server is now running and protected by Azure OAuth authentication.

### Testing with a Client

Create a test client that authenticates with your Azure-protected server:

```python test_client.py
from fastmcp import Client
import asyncio

async def main():
    # The client will automatically handle Azure OAuth
    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
        # First-time connection will open Azure login in your browser
        print("✓ Authenticated with Azure!")
        
        # Test the protected tool
        result = await client.call_tool("get_user_info")
        print(f"Azure user: {result['email']}")
        print(f"Name: {result['name']}")

if __name__ == "__main__":
    asyncio.run(main())
```

When you run the client for the first time:
1. Your browser will open to Microsoft's authorization page
2. Sign in with your Microsoft account (work, school, or personal based on your tenant configuration)
3. Grant the requested permissions
4. After authorization, you'll be redirected back
5. The client receives the token and can make authenticated requests

<Info>
The client caches tokens locally, so you won't need to re-authenticate for subsequent runs unless the token expires or you explicitly clear the cache.
</Info>

## Production Configuration

<VersionBadge version="2.13.0" />

For production deployments with persistent token management across server restarts, configure `jwt_signing_key` and `client_storage`:

```python server.py
import os
from fastmcp import FastMCP
from fastmcp.server.auth.providers.azure import AzureProvider
from key_value.aio.stores.redis import RedisStore
from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
from cryptography.fernet import Fernet

# Production setup with encrypted persistent token storage
auth_provider = AzureProvider(
    client_id="835f09b6-0f0f-40cc-85cb-f32c5829a149",
    client_secret="your-client-secret",
    tenant_id="08541b6e-646d-43de-a0eb-834e6713d6d5",
    base_url="https://your-production-domain.com",
    required_scopes=["your-scope"],

    # Production token management
    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
    client_storage=FernetEncryptionWrapper(
        key_value=RedisStore(
            host=os.environ["REDIS_HOST"],
            port=int(os.environ["REDIS_PORT"])
        ),
        fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
    )
)

mcp = FastMCP(name="Production Azure App", auth=auth_provider)
```

<Note>
Parameters (`jwt_signing_key` and `client_storage`) work together to ensure tokens and client registrations survive server restarts. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. Store secrets in environment variables and use a persistent storage backend like Redis for distributed deployments.

For complete details on these parameters, see the [OAuth Proxy documentation](/servers/auth/oauth-proxy#configuration-parameters).
</Note>

## Token Verification Only (Managed Identity)

<VersionBadge version="2.15.0" />

For deployments where your server only needs to **validate incoming tokens** — such as Azure Container Apps with Managed Identity — use `AzureJWTVerifier` with `RemoteAuthProvider` instead of the full `AzureProvider`.

This pattern is ideal when:
- Your infrastructure handles authentication (e.g., Managed Identity)
- You don't need the OAuth proxy flow (no `client_secret` required)
- You just need to verify that incoming Azure AD tokens are valid

```python server.py
from fastmcp import FastMCP
from fastmcp.server.auth import RemoteAuthProvider
from fastmcp.server.auth.providers.azure import AzureJWTVerifier
from pydantic import AnyHttpUrl

tenant_id = "your-tenant-id"
client_id = "your-client-id"

# AzureJWTVerifier auto-configures JWKS, issuer, and audience
verifier = AzureJWTVerifier(
    client_id=client_id,
    tenant_id=tenant_id,
    required_scopes=["access_as_user"],  # Scope names from Azure Portal
)

auth = RemoteAuthProvider(
    token_verifier=verifier,
    authorization_servers=[
        AnyHttpUrl(f"https://login.microsoftonline.com/{tenant_id}/v2.0")
    ],
    base_url="https://your-container-app.azurecontainerapps.io",
)

mcp = FastMCP(name="Azure MI App", auth=auth)
```

`AzureJWTVerifier` handles Azure's scope format automatically. You write scope names exactly as they appear in Azure Portal under **Expose an API** (e.g., `access_as_user`). The verifier validates tokens using the short-form scopes that Azure puts in the `scp` claim, while advertising the full URI scopes (e.g., `api://your-client-id/access_as_user`) in OAuth metadata so MCP clients know what to request.

<Note>
For Azure Government, pass `base_authority="login.microsoftonline.us"` to `AzureJWTVerifier`.
</Note>

## On-Behalf-Of (OBO)

<VersionBadge version="3.0.0" />

The On-Behalf-Of (OBO) flow allows your FastMCP server to call downstream Microsoft APIs—like Microsoft Graph—using the authenticated user's identity. When a user authenticates to your MCP server, you receive a token for your API. OBO exchanges that token for a new token that can call other services, maintaining the user's identity and permissions throughout the chain.

This pattern is useful when your tools need to access user-specific data from Microsoft services: reading emails, accessing calendar events, querying SharePoint, or any other Graph API operation that requires user context.

<Note>
OBO features require the `azure` extra:

```bash
pip install 'fastmcp[azure]'
```
</Note>

### Azure Portal Setup

OBO requires additional configuration in your Azure App registration beyond basic authentication.

<Steps>
<Step title="Add API Permissions">
    In your App registration, navigate to **API permissions** and add the Microsoft Graph permissions your tools will need.

    - Click **Add a permission** → **Microsoft Graph** → **Delegated permissions**
    - Select the permissions required for your use case (e.g., `Mail.Read`, `Calendars.Read`, `User.Read`)
    - Repeat for any other APIs you need to call

    <Warning>
    Only add delegated permissions for OBO. Application permissions bypass user context entirely and are inappropriate for the OBO flow.
    </Warning>
</Step>

<Step title="Grant Admin Consent">
    OBO requires admin consent for the permissions you've added. In the **API permissions** page, click **Grant admin consent for [Your Organization]**.

    Without admin consent, OBO token exchanges will fail with an `AADSTS65001` error indicating the user or administrator hasn't consented to use the application.

    <Tip>
    For development, you can grant consent for just your own account. For production, an Azure AD administrator must grant tenant-wide consent.
    </Tip>
</Step>
</Steps>

### Configure AzureProvider for OBO

The `additional_authorize_scopes` parameter tells Azure which downstream API permissions to include during the initial authorization. These scopes establish what your server can request through OBO later.

```python server.py
from fastmcp import FastMCP
from fastmcp.server.auth.providers.azure import AzureProvider

auth_provider = AzureProvider(
    client_id="your-client-id",
    client_secret="your-client-secret",
    tenant_id="your-tenant-id",
    base_url="http://localhost:8000",
    required_scopes=["mcp-access"],  # Your API scope
    # Include Graph scopes for OBO
    additional_authorize_scopes=[
        "https://graph.microsoft.com/Mail.Read",
        "https://graph.microsoft.com/User.Read",
        "offline_access",  # Enables refresh tokens
    ],
)

mcp = FastMCP(name="Graph-Enabled Server", auth=auth_provider)
```

Scopes listed in `additional_authorize_scopes` are requested during the initial OAuth flow but aren't validated on incoming tokens. They establish permission for your server to later exchange the user's token for downstream API access.

<Info>
Use fully-qualified scope URIs for downstream APIs (e.g., `https://graph.microsoft.com/Mail.Read`). Short forms like `Mail.Read` work for authorization requests, but fully-qualified URIs are clearer and avoid ambiguity.
</Info>

### EntraOBOToken Dependency

The `EntraOBOToken` dependency handles the complete OBO flow automatically. Declare it as a parameter default with the scopes you need, and FastMCP exchanges the user's token for a downstream API token before your function runs.

```python
from fastmcp import FastMCP
from fastmcp.server.auth.providers.azure import AzureProvider, EntraOBOToken
import httpx

auth_provider = AzureProvider(
    client_id="your-client-id",
    client_secret="your-client-secret",
    tenant_id="your-tenant-id",
    base_url="http://localhost:8000",
    required_scopes=["mcp-access"],
    additional_authorize_scopes=[
        "https://graph.microsoft.com/Mail.Read",
        "https://graph.microsoft.com/User.Read",
    ],
)

mcp = FastMCP(name="Email Reader", auth=auth_provider)

@mcp.tool
async def get_recent_emails(
    count: int = 10,
    graph_token: str = EntraOBOToken(["https://graph.microsoft.com/Mail.Read"]),
) -> list[dict]:
    """Get the user's recent emails from Microsoft Graph."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://graph.microsoft.com/v1.0/me/messages?$top={count}",
            headers={"Authorization": f"Bearer {graph_token}"},
        )
        response.raise_for_status()
        data = response.json()

    return [
        {"subject": msg["subject"], "from": msg["from"]["emailAddress"]["address"]}
        for msg in data.get("value", [])
    ]
```

The `graph_token` parameter receives a ready-to-use access token for Microsoft Graph. FastMCP handles the OBO exchange transparently—your function just uses the token to call the API.

<Warning>
**Scope alignment is critical.** The scopes passed to `EntraOBOToken` must be a subset of the scopes in `additional_authorize_scopes`. If you request a scope during OBO that wasn't included in the initial authorization, the exchange will fail.
</Warning>

<Tip>
For advanced OBO scenarios, use `CurrentAccessToken()` to get the user's token, then construct an `azure.identity.aio.OnBehalfOfCredential` directly with your Azure credentials.
</Tip>

<Tip>
For a complete working example of Azure OBO with FastMCP, see [Pamela Fox's blog post on OBO flow for Entra-based MCP servers](https://blog.pamelafox.org/2026/01/using-on-behalf-of-flow-for-entra-based.html).
</Tip>

## Azure AD B2C

<VersionBadge version="3.3.0" />

Azure AD B2C (Business-to-Consumer) uses different endpoints, scope URIs, and
token issuers than standard Microsoft Entra ID. The `AzureProvider.from_b2c()`
factory handles all of these differences automatically.

<Warning>
Azure AD B2C does **not** support the On-Behalf-Of (OBO) flow. If you need
OBO for downstream API calls, use `AzureProvider` with standard Entra ID
instead.
</Warning>

### Quick Start

```python server.py
from fastmcp import FastMCP
from fastmcp.server.auth.providers.azure import AzureProvider

auth = AzureProvider.from_b2c(
    tenant_name="mytenant",
    policy_name="B2C_1_susi",
    client_id="00000000-0000-0000-0000-000000000000",
    client_secret="my-secret",
    required_scopes=["mcp-access"],
    base_url="https://myserver.com",
)

mcp = FastMCP("My App", auth=auth)
```

`from_b2c()` derives the following values automatically:

| Derived value | Formula |
|---|---|
| Authority host | `{tenant_name}.b2clogin.com` |
| Authorization endpoint | `https://{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{policy_name}/oauth2/v2.0/authorize` |
| Token endpoint | `https://{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{policy_name}/oauth2/v2.0/token` |
| Scope identifier URI | `https://{tenant_name}.onmicrosoft.com/{client_id}` |

### Token Issuer Validation

B2C access tokens carry the **tenant GUID** (not the `.onmicrosoft.com` name)
in the `iss` claim, and the exact format varies by policy and custom-domain
configuration. `from_b2c()` therefore **disables issuer validation by
default**; **audience validation still enforces that tokens target the correct
application**.

Once you have confirmed a successful end-to-end login, read the actual `iss`
value from the decoded claims and enable strict validation:

```python
auth = AzureProvider.from_b2c(
    tenant_name="mytenant",
    policy_name="B2C_1_susi",
    client_id="00000000-0000-0000-0000-000000000000",
    client_secret="my-secret",
    required_scopes=["mcp-access"],
    base_url="https://myserver.com",
    token_issuer="https://mytenant.b2clogin.com/11111111-2222-3333-4444-555555555555/v2.0/",
)
```

### Custom Domains

If your B2C tenant uses a [custom domain](https://learn.microsoft.com/en-us/azure/active-directory-b2c/custom-domain)
(e.g. `auth.mycompany.com` instead of `mytenant.b2clogin.com`), pass it via
`custom_domain`:

```python
auth = AzureProvider.from_b2c(
    tenant_name="mytenant",
    policy_name="B2C_1_susi",
    client_id="00000000-0000-0000-0000-000000000000",
    client_secret="my-secret",
    required_scopes=["mcp-access"],
    base_url="https://myserver.com",
    custom_domain="auth.mycompany.com",
)
```