Azure-Samples / Azure-Samples/msdocs-fastapi-postgresql-sample-app

Enable Agent Identity Auth for Foundry Agents for sample msdocs-fastapi-postgresql-sample-app

Offen
#18 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Bicep
Sterne
11
Forks
60
Ø Merge
1 T. 18 Std.
Gemergte PRs (30 T.)
2

Beschreibung

## Summary

Add a Model Context Protocol (MCP) server to the existing FastAPI restaurant reviews sample app, secure it with Microsoft Entra ID authentication (EasyAuth v2), and preauthorize Azure AI Foundry agent identities to call the MCP tools using managed identity (`ServiceIdentity`) authentication via the `client_credentials` flow.

## Motivation

Azure AI Foundry agents need to consume MCP servers hosted on Azure App Service. The existing samples needs to demonstrate how to secure an MCP endpoint for agent identity access to ensure agentic securty risks are minimized. This change provides a working, end-to-end example that developers can follow to:

1. Add an MCP server to an existing FastAPI app
2. Secure it with Entra ID authentication
3. Preauthorize Foundry agent identities (which use `ServiceIdentity` type principals, not standard app registrations)

## Changes

### New Files
- **`src/fastapi_app/mcp_server.py`** — MCP server with 4 tools (`list_restaurants_mcp`, `get_details_mcp`, `create_review_mcp`, `create_restaurant_mcp`) using `FastMCP` with `stateless_http=True`
- **`GUIDE_AUTH_MCP_SERVER.md`** — Comprehensive step-by-step guide covering app registration, EasyAuth configuration, PRM setup, Foundry agent preauthorization, verification, troubleshooting, and 22 test cases

### Modified Files
- **`src/pyproject.toml`** — Added `mcp[cli]` to dependencies
- **`src/fastapi_app/app.py`** — Imported and mounted MCP server at `/mcp`, added `mcp_lifespan` context manager to FastAPI app
- **`src/my_uvicorn_worker.py`** — Changed `lifespan` from `"auto"` to `"on"` (required for MCP session manager to start under gunicorn)
- **`README.md`** — Updated title, description, and added sections for MCP tools, architecture diagram, local MCP verification, Entra ID auth setup steps, Foundry agent integration, and key learnings
- **`infra/main.bicep`**, **`infra/resources.bicep`** — Infrastructure updates from `azd up` deployment

## Technical Details

### MCP Server
- Mounted at `/mcp/mcp` under the existing FastAPI app
- Uses `stateless_http=True` for compatibility with FastAPI mount
- `mcp_lifespan` context manager ensures the MCP session manager starts/stops with the app
- Tools use `asyncio.to_thread()` to run synchronous SQLModel/SQLAlchemy DB queries

### Authentication Architecture
Azure AI Foundry Agent

│ client_credentials flow → token with MCP.Access role

Azure App Service (EasyAuth ~2, Return401)

│ JWT validated: issuer, audience, allowedClientApplications

FastAPI + gunicorn (lifespan: on)

│ /mcp/mcp → FastMCP (stateless_http)

MCP Tools → PostgreSQL

### Key Configuration

| Component | Setting | Value |
|-----------|---------|-------|
| EasyAuth | `runtimeVersion` | `~2` (v1 doesn't enforce auth properly) |
| EasyAuth | `unauthenticatedClientAction` | `Return401` |
| App Role | `MCP.Access` | `allowedMemberTypes: ["Application"]` |
| PRM | `WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES` | `api:///user_impersonation` |
| Gunicorn | `lifespan` | `"on"` (critical for MCP session manager) |

### Key Learnings Documented
- **`ServiceIdentity` principals** (Foundry agents) cannot be added to `preAuthorizedApplications` — use app role assignments + `allowedClientApplications` instead
- A **service principal must be created** for the app registration before role assignments work (commonly missed step)
- **`runtimeVersion: "~2"`** is required for EasyAuth to properly enforce authentication
- The **PRM endpoint** (`/.well-known/oauth-protected-resource`) is served by EasyAuth and is exempt from authentication by design

## Test Coverage

22 test cases across 3 groups:
- **Group A (8 tests):** MCP functionality without authentication (auth disabled)
- **Group B (11 tests):** Authentication enforcement — unauthenticated, fake token, wrong audience, valid token flows
- **Group C (3 tests):** Python MCP client programmatic tests (with/without auth)

## Verification

- Foundry agent (`mslearnagent`) successfully connects and enumerates all 4 MCP tools (`mcp_list_tools` status: `OK`)
- Entra ID sign-in logs show successful `ServiceIdentity` authentication
- PRM endpoint serves correct OAuth metadata
- Unauthenticated requests correctly return 401

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginnen Sie mit src/fastapi_app/app.py und src/fastapi_app/mcp_server.py, und überprüfen Sie anschließend src/pyproject.toml sowie die Infrastrukturänderungen in infra/main.bicep und infra/resources.bicep. Führen Sie die 22 im Issue beschriebenen Testfälle aus und überprüfen Sie die vier MCP-Tools, die PRM-Metadaten, authentifizierte und nicht authentifizierte Antworten sowie die Verbindung des Foundry agent.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
azure, fastapi, postgresql, python
Bereich
api, authentication, backend, cloud, databases, security
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
30/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.