fastapi-mcp-azure-oauth

RFC-compliant Azure AD OAuth 2.0 router for FastAPI MCP servers, with first-class support for Copilot Studio and other Azure AD clients.

What it does

Drop a single call into any FastAPI application to get:

Plus a TokenValidator that:

• Verifies Azure AD JWT signatures via JWKS with per-tenant key caching
• Supports both single-tenant and multi-tenant (/organizations) deployments
• Enforces explicit issuer binding after signature verification (closes PyJWT verify_iss no-op gap)
• Rejects api://{app_id}/.default as an audience (it's a scope suffix, not a valid token audience)
• Accepts only access tokens: delegated tokens need an scp claim (optionally a specific scope); ID tokens and app-only tokens are rejected unless you opt in via required_roles
• Rejects non-GUID tenant IDs before any JWKS fetch, and caps the JWKS client cache at 50 tenants with FIFO eviction
• Offers validate_token_async() so JWKS fetches never block the event loop

Installation

pip install fastapi-mcp-azure-oauth

Requires Python 3.10+ and FastAPI 0.115+.

Quick start

from fastapi import FastAPI, Depends
from fastapi_mcp_azure_oauth import build_oauth_router, TokenValidator

app = FastAPI()

# 1 — Mount the OAuth router (all RFC-required endpoints)
app.include_router(
    build_oauth_router(
        app_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",   # Azure AD App (client) ID
        tenant_id="yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", # Home tenant ID
        client_secret="your-client-secret",
        api_scope="access_as_user",                       # exposed under api://{app_id}/
        resource_path="/mcp",                             # your protected resource path
        base_url="https://mcp.example.com",               # public URL of this server
        allowed_tenant_ids=["yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"],
    )
)

# 2 — Validate incoming Bearer tokens on protected endpoints
validator = TokenValidator(
    app_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    allowed_tenant_ids=["yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"],
    required_scopes=["access_as_user"],
)

@app.post("/mcp")
async def mcp_handler(claims: dict = Depends(validator.as_dependency)):
    user_id = validator.get_user_id(claims)
    return {"user": user_id}

Configuration reference

build_oauth_router()

TokenValidator()

Use await validator.validate_token_async(token) from async code (middleware etc.). as_dependency already does this.

How it works

Client                    This server               Azure AD / Graph
  │                           │                           │
  │  GET /.well-known/...     │                           │
  │──────────────────────────>│                           │
  │<── auth/token endpoints ──│  (points at Azure AD)     │
  │                           │                           │
  │  POST /register           │                           │
  │──────────────────────────>│  POST /oauth2/token ─────>│
  │                           │<── access_token ──────────│
  │                           │  PATCH /applications ─────>│
  │<── client_id ─────────────│<── 204 ───────────────────│
  │                           │                           │
  │  GET /authorize (→ AAD)   │                           │
  │──────────────────────────────────────────────────────>│
  │<────────────────────── code ──────────────────────────│
  │  POST /token (→ AAD)      │                           │
  │──────────────────────────────────────────────────────>│
  │<──────────────── access_token ────────────────────────│
  │                           │                           │
  │  POST /mcp                │                           │
  │  Authorization: Bearer .. │                           │
  │──────────────────────────>│  GET /discovery/v2.0/keys>│
  │                           │<── JWKS ──────────────────│
  │                           │  Verify signature         │
  │                           │  Check iss binding        │
  │                           │  Check aud                │
  │<─── MCP response ─────────│                           │

Step 3 (auth code flow) and step 4 (token exchange) happen entirely on Microsoft's side — this server is not involved.

Azure AD app registration requirements

1. Register an app in Azure AD / Entra ID.
2. Create a Client secret and note it. Configure it directly in your MCP client (e.g. Copilot Studio's connector settings) — this server never hands it out.
3. Under Expose an API, add a scope (e.g. access_as_user).
4. Under Authentication, add the following as SPA redirect URIs:
   • https://your-server/oauth/callback
   • Any other redirect URIs your clients use
5. Optional: to let POST /register enrol redirect URIs automatically, grant the app the Application.ReadWrite.OwnedBy Microsoft Graph permission and list the permitted URIs in allowed_redirect_uris. If you register redirect URIs manually (step 4), skip this — the app then needs no Graph permissions at all.

Upgrading from 1.x

2.0.0 is a security release with breaking changes:

• GET /register and POST /register no longer return client_secret. Configure the secret in your client directly.
• POST /register only enrols redirect URIs listed in allowed_redirect_uris, and only enrols the server's own callback when base_url is set.
• TokenValidator rejects ID tokens, tokens without exp, app-only tokens (unless required_roles is set) and non-GUID tenant IDs.

If you ran 1.x on a reachable server, rotate the client secret and review the app registration's redirect URIs and credentials for anything you did not add.

Multi-tenant deployments

Pass allowed_tenant_ids=None (the default) and use tenant_id as your app's home tenant:

build_oauth_router(
    app_id="...",
    tenant_id="your-home-tenant-id",   # used for Graph API only
    client_secret="...",
    allowed_tenant_ids=None,            # accept tokens from any AAD tenant
)

validator = TokenValidator(
    app_id="...",
    allowed_tenant_ids=None,            # accept tokens from any AAD tenant
    required_scopes=["access_as_user"],
)

Accepting every tenant means any Microsoft work or school account can obtain a token for your API. Do your own authorisation on the returned claims, or restrict tenants as below.

To restrict to a specific set of tenants:

validator = TokenValidator(
    app_id="...",
    allowed_tenant_ids=[
        "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    ],
)

Contributing

See CONTRIBUTING.md. All contributions are welcome.

Security

Please report security vulnerabilities privately. See SECURITY.md.

License

MIT © 2026 Lee Pasifull