addresses feedback from Pamela

Author: madebygps

README.md

@@ -15,6 +15,7 @@ A demonstration project showcasing Model Context Protocol (MCP) implementations
 - [Run local Agents <-> MCP](#run-local-agents---mcp)
 - [Deploy to Azure](#deploy-to-azure)
 - [Deploy to Azure with private networking](#deploy-to-azure-with-private-networking)
+- [Deploy to Azure with Keycloak authentication](#deploy-to-azure-with-keycloak-authentication)
 
 ## Getting started
 
@@ -276,3 +277,122 @@ When using VNet configuration, additional Azure resources are provisioned:
 - **Virtual Network**: Pay-as-you-go tier. Costs based on data processed. [Pricing](https://azure.microsoft.com/pricing/details/virtual-network/)
 - **Azure Private DNS Resolver**: Pricing per month, endpoints, and zones. [Pricing](https://azure.microsoft.com/pricing/details/dns/)
 - **Azure Private Endpoints**: Pricing per hour per endpoint. [Pricing](https://azure.microsoft.com/pricing/details/private-link/)
+
+---
+
+## Deploy to Azure with Keycloak authentication
+
+This project supports deploying with OAuth 2.0 authentication using Keycloak as the identity provider, implementing the [MCP OAuth specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) with Dynamic Client Registration (DCR).
+
+### Architecture
+
+```text
+┌─────────────┐     1. DCR + Token      ┌─────────────┐
+│  LangChain  │ ──────────────────────► │  Keycloak   │
+│   Agent     │ ◄────────────────────── │  (direct)   │
+│             │                         └─────────────┘
+│             │     2. MCP + Bearer
+│             │ ──────────────────────► ┌─────────────┐
+│             │ ◄────────────────────── │  mcproutes  │ → MCP Server
+└─────────────┘                         └─────────────┘
+```
+
+### What gets deployed
+
+| Component | Description |
+|-----------|-------------|
+| **Keycloak Container App** | Keycloak 26.0 with pre-configured realm |
+| **HTTP Route Configuration** | Rule-based routing: `/auth/*` → Keycloak, `/*` → MCP Server |
+| **OAuth-protected MCP Server** | FastMCP with JWT validation against Keycloak's JWKS endpoint |
+
+### Deployment steps
+
+1. Set the Keycloak admin password (required):
+
+   ```bash
+   azd env set KEYCLOAK_ADMIN_PASSWORD "YourSecurePassword123!"
+   ```
+
+2. Optionally customize the realm name (default: `mcp`):
+
+   ```bash
+   azd env set KEYCLOAK_REALM_NAME "mcp"
+   ```
+
+3. Deploy to Azure:
+
+   ```bash
+   azd up
+   ```
+
+   This will create the Azure Container Apps environment, deploy Keycloak with the pre-configured realm, deploy the MCP server with OAuth validation, and configure HTTP route-based routing.
+
+4. Verify deployment by checking the outputs:
+
+   ```bash
+   azd env get-value MCP_SERVER_URL
+   azd env get-value KEYCLOAK_DIRECT_URL
+   azd env get-value KEYCLOAK_ADMIN_CONSOLE
+   ```
+
+5. Visit the Keycloak admin console to verify the realm is configured:
+
+   ```text
+   https://<your-mcproutes-url>/auth/admin
+   ```
+
+   Login with `admin` and your configured password.
+
+### Testing with the LangChain agent
+
+1. Generate the local environment file:
+
+   ```bash
+   ./infra/write_env.sh
+   ```
+
+   This creates `.env` with `KEYCLOAK_REALM_URL`, `MCP_SERVER_URL`, and Azure OpenAI settings.
+
+2. Run the agent:
+
+   ```bash
+   uv run agents/langchainv1_keycloak.py
+   ```
+
+   Expected output:
+
+   ```text
+   ============================================================
+   LangChain Agent with Keycloak-Protected MCP Server
+   ============================================================
+
+   Configuration:
+     MCP Server:  https://mcproutes.<env>.azurecontainerapps.io/mcp
+     Keycloak:    https://mcp-<name>-kc.<env>.azurecontainerapps.io/realms/mcp
+     LLM Host:    azure
+     Auth:        Dynamic Client Registration (DCR)
+
+   [11:40:48] INFO     📝 Registering client via DCR...
+              INFO     ✅ Registered client: caef6f47-0243-474d-b...
+              INFO     🔑 Getting access token from Keycloak...
+              INFO     ✅ Got access token (expires in 300s)
+              INFO     📡 Connecting to MCP server...
+              INFO     🔧 Getting available tools...
+              INFO     ✅ Found 1 tools: ['add_expense']
+              INFO     💬 User query: Add an expense: yesterday I bought a laptop...
+              ...
+              INFO     📊 Agent Response:
+   The expense of $1200 for the laptop purchase has been successfully recorded.
+   ```
+
+### Known limitations (demo trade-offs)
+
+| Item | Current | Production Recommendation | Why |
+|------|---------|---------------------------|-----|
+| Keycloak mode | `start-dev` | `start` with proper config | Dev mode has relaxed security defaults |
+| Database | H2 in-memory | PostgreSQL | H2 doesn't persist data across restarts |
+| Replicas | 1 (due to H2) | Multiple with shared DB | H2 is in-memory, can't share state |
+| Keycloak access | Public (direct URL) | Internal only via routes | Route URL isn't known until after deployment |
+| DCR | Open (anonymous) | Require initial access token | Any client can register without auth |
+
+> **Note:** Keycloak must be publicly accessible because its URL is dynamically generated by Azure. Token issuer validation requires a known URL, but the mcproutes URL isn't available until after deployment. Using a custom domain would fix this.

agents/agentframework_http.py

@@ -5,7 +5,6 @@
 import os
 from datetime import datetime
 
-import httpx
 from agent_framework import ChatAgent, MCPStreamableHTTPTool
 from agent_framework.azure import AzureOpenAIChatClient
 from agent_framework.openai import OpenAIChatClient
@@ -14,6 +13,11 @@
 from rich import print
 from rich.logging import RichHandler
 
+try:
+    from keycloak_auth import get_auth_headers
+except ImportError:
+    from agents.keycloak_auth import get_auth_headers
+
 # Configure logging
 logging.basicConfig(level=logging.WARNING, format="%(message)s", datefmt="[%X]", handlers=[RichHandler()])
 logger = logging.getLogger("agentframework_mcp_http")
@@ -56,65 +60,6 @@
     )
 
 
-# --- Keycloak Authentication Helpers (only used if KEYCLOAK_REALM_URL is set) ---
-
-
-async def register_client_via_dcr() -> tuple[str, str]:
-    """Register a new client dynamically using Keycloak's DCR endpoint."""
-    dcr_url = f"{KEYCLOAK_REALM_URL}/clients-registrations/openid-connect"
-    logger.info("📝 Registering client via DCR...")
-
-    async with httpx.AsyncClient() as http_client:
-        response = await http_client.post(
-            dcr_url,
-            json={
-                "client_name": f"agent-{datetime.now().strftime('%Y%m%d-%H%M%S')}",
-                "grant_types": ["client_credentials"],
-                "token_endpoint_auth_method": "client_secret_basic",
-            },
-            headers={"Content-Type": "application/json"},
-        )
-        if response.status_code not in (200, 201):
-            raise RuntimeError(f"DCR registration failed: {response.status_code} - {response.text}")
-
-        data = response.json()
-        logger.info(f"✅ Registered client: {data['client_id'][:20]}...")
-        return data["client_id"], data["client_secret"]
-
-
-async def get_keycloak_token(client_id: str, client_secret: str) -> str:
-    """Get an access token from Keycloak using client_credentials grant."""
-    token_url = f"{KEYCLOAK_REALM_URL}/protocol/openid-connect/token"
-    logger.info("🔑 Getting access token from Keycloak...")
-
-    async with httpx.AsyncClient() as http_client:
-        response = await http_client.post(
-            token_url,
-            data={
-                "grant_type": "client_credentials",
-                "client_id": client_id,
-                "client_secret": client_secret,
-            },
-            headers={"Content-Type": "application/x-www-form-urlencoded"},
-        )
-        if response.status_code != 200:
-            raise RuntimeError(f"Token request failed: {response.status_code} - {response.text}")
-
-        token_data = response.json()
-        logger.info(f"✅ Got access token (expires in {token_data.get('expires_in', '?')}s)")
-        return token_data["access_token"]
-
-
-async def get_auth_headers() -> dict[str, str] | None:
-    """Get authorization headers if Keycloak is configured, otherwise return None."""
-    if not KEYCLOAK_REALM_URL:
-        return None
-
-    client_id, client_secret = await register_client_via_dcr()
-    access_token = await get_keycloak_token(client_id, client_secret)
-    return {"Authorization": f"Bearer {access_token}"}
-
-
 # --- Main Agent Logic ---
 
 
@@ -126,7 +71,7 @@ async def http_mcp_example() -> None:
     Otherwise, connects without authentication.
     """
     # Get auth headers if Keycloak is configured
-    headers = await get_auth_headers()
+    headers = await get_auth_headers(KEYCLOAK_REALM_URL, client_name_prefix="agentframework")
     if headers:
         logger.info(f"🔐 Auth enabled - connecting to {MCP_SERVER_URL} with Bearer token")
     else:
@@ -137,12 +82,11 @@ async def http_mcp_example() -> None:
         ChatAgent(
             chat_client=client,
             name="Expenses Agent",
-            instructions="You help users to log expenses.",
+            instructions=f"You help users to log expenses. Today's date is {datetime.now().strftime('%Y-%m-%d')}.",
         ) as agent,
     ):
-        today = datetime.now().strftime("%Y-%m-%d")
         user_query = "yesterday I bought a laptop for $1200 using my visa."
-        result = await agent.run(f"Today's date is {today}. {user_query}", tools=mcp_server)
+        result = await agent.run(user_query, tools=mcp_server)
         print(result)
 
         # Keep the worker alive in production

agents/keycloak_auth.py

@@ -0,0 +1,126 @@
+"""
+Keycloak authentication helpers for MCP agents.
+
+Provides OAuth2 client credentials flow authentication via Keycloak's
+Dynamic Client Registration (DCR) endpoint.
+
+Usage:
+    from keycloak_auth import get_auth_headers
+
+    headers = await get_auth_headers(keycloak_realm_url)
+    # Returns {"Authorization": "Bearer <token>"} or None if no URL provided
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+async def register_client_via_dcr(keycloak_realm_url: str, client_name_prefix: str = "agent") -> tuple[str, str]:
+    """
+    Register a new client dynamically using Keycloak's DCR endpoint.
+
+    Args:
+        keycloak_realm_url: The Keycloak realm URL (e.g., http://localhost:8080/realms/myrealm)
+        client_name_prefix: Prefix for the generated client name
+
+    Returns:
+        Tuple of (client_id, client_secret)
+
+    Raises:
+        RuntimeError: If DCR registration fails
+    """
+    dcr_url = f"{keycloak_realm_url}/clients-registrations/openid-connect"
+    logger.info("📝 Registering client via DCR...")
+
+    async with httpx.AsyncClient() as http_client:
+        response = await http_client.post(
+            dcr_url,
+            json={
+                "client_name": f"{client_name_prefix}-{datetime.now().strftime('%Y%m%d-%H%M%S')}",
+                "grant_types": ["client_credentials"],
+                "token_endpoint_auth_method": "client_secret_basic",
+            },
+            headers={"Content-Type": "application/json"},
+        )
+
+        if response.status_code not in (200, 201):
+            raise RuntimeError(
+                f"DCR registration failed at {dcr_url}: "
+                f"status={response.status_code}, "
+                f"response={response.text}"
+            )
+
+        data = response.json()
+        logger.info(f"✅ Registered client: {data['client_id'][:20]}...")
+        return data["client_id"], data["client_secret"]
+
+
+async def get_keycloak_token(keycloak_realm_url: str, client_id: str, client_secret: str) -> str:
+    """
+    Get an access token from Keycloak using client_credentials grant.
+
+    Args:
+        keycloak_realm_url: The Keycloak realm URL
+        client_id: The OAuth client ID
+        client_secret: The OAuth client secret
+
+    Returns:
+        The access token string
+
+    Raises:
+        RuntimeError: If token request fails
+    """
+    token_url = f"{keycloak_realm_url}/protocol/openid-connect/token"
+    logger.info("🔑 Getting access token from Keycloak...")
+
+    async with httpx.AsyncClient() as http_client:
+        response = await http_client.post(
+            token_url,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": client_id,
+                "client_secret": client_secret,
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"Token request failed at {token_url}: "
+                f"status={response.status_code}, "
+                f"response={response.text}"
+            )
+
+        token_data = response.json()
+        logger.info(f"✅ Got access token (expires in {token_data.get('expires_in', '?')}s)")
+        return token_data["access_token"]
+
+
+async def get_auth_headers(
+    keycloak_realm_url: str | None, client_name_prefix: str = "agent"
+) -> dict[str, str] | None:
+    """
+    Get authorization headers if Keycloak is configured.
+
+    This is the main entry point for agents that need OAuth authentication.
+    It handles the full flow: DCR registration -> token acquisition -> headers.
+
+    Args:
+        keycloak_realm_url: The Keycloak realm URL, or None to skip auth
+        client_name_prefix: Prefix for the dynamically registered client name
+
+    Returns:
+        {"Authorization": "Bearer <token>"} if keycloak_realm_url is set, None otherwise
+    """
+    if not keycloak_realm_url:
+        return None
+
+    client_id, client_secret = await register_client_via_dcr(keycloak_realm_url, client_name_prefix)
+    access_token = await get_keycloak_token(keycloak_realm_url, client_id, client_secret)
+    return {"Authorization": f"Bearer {access_token}"}