refactor: integrate token exchange into unified get_client() pattern
Resolves the token exchange implementation gap where get_session_client() was implemented but never used by tools. Unifies token acquisition into a single async get_client() method that handles both pass-through and token exchange modes transparently. Core Changes: - Make get_client() async and merge token exchange logic into it - Remove scopes parameter from token exchange (Nextcloud doesn't support OAuth scopes) - Update all 8 tool modules to use await get_client(ctx) - Fix provisioning decorator to skip checks in BasicAuth mode Token Acquisition Modes: 1. BasicAuth: Returns shared client (no token operations) 2. OAuth pass-through (default): Verifies and passes Flow 1 token to Nextcloud 3. OAuth token exchange (opt-in): Exchanges Flow 1 token for ephemeral token via RFC 8693 Key Architectural Clarifications: - Progressive Consent (Flow 1/2) = Authorization architecture - Token Exchange = Token acquisition pattern during tool execution - Refresh tokens from Flow 2 are NEVER used for tool calls (only background jobs) - Nextcloud scopes are "soft-scopes" enforced by MCP server, not IdP Documentation Updates: - ADR-004: Added comprehensive token acquisition patterns section - CRITICAL-TOKEN-EXCHANGE-PATTERN.md: Updated to reflect implementation status - CLAUDE.md: Updated architectural patterns with async get_client() Testing: - All 36 unit tests passing - All 4 smoke tests passing (BasicAuth mode) - Linting issues fixed (ruff) Configuration: ENABLE_TOKEN_EXCHANGE=false (default) - pass-through mode ENABLE_TOKEN_EXCHANGE=true (opt-in) - token exchange mode 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
@@ -0,0 +1,445 @@
|
||||
"""RFC 8693 Token Exchange implementation for ADR-004 Progressive Consent.
|
||||
|
||||
This module implements the token exchange pattern to convert Flow 1 MCP tokens
|
||||
(aud: "mcp-server") into ephemeral delegated Nextcloud tokens (aud: "nextcloud")
|
||||
for session operations.
|
||||
|
||||
Key Properties:
|
||||
- On-demand generation during tool execution
|
||||
- Ephemeral tokens (NOT stored, discarded after use)
|
||||
- Limited scopes (only what tool needs)
|
||||
- Short-lived (5 minutes default)
|
||||
"""
|
||||
|
||||
import logging
|
||||
import time
|
||||
from typing import Any, Dict, Optional, Tuple
|
||||
from urllib.parse import urljoin
|
||||
|
||||
import httpx
|
||||
import jwt
|
||||
|
||||
from ..config import get_settings
|
||||
from .refresh_token_storage import RefreshTokenStorage
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class TokenExchangeService:
|
||||
"""Implements RFC 8693 OAuth 2.0 Token Exchange."""
|
||||
|
||||
# RFC 8693 Token Type Identifiers
|
||||
TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token"
|
||||
TOKEN_TYPE_JWT = "urn:ietf:params:oauth:token-type:jwt"
|
||||
TOKEN_TYPE_ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token"
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
oidc_discovery_url: Optional[str] = None,
|
||||
client_id: Optional[str] = None,
|
||||
client_secret: Optional[str] = None,
|
||||
nextcloud_host: Optional[str] = None,
|
||||
):
|
||||
"""Initialize token exchange service.
|
||||
|
||||
Args:
|
||||
oidc_discovery_url: OIDC discovery endpoint URL
|
||||
client_id: OAuth client ID for token exchange
|
||||
client_secret: OAuth client secret
|
||||
nextcloud_host: Nextcloud instance URL
|
||||
"""
|
||||
settings = get_settings()
|
||||
self.oidc_discovery_url = oidc_discovery_url or settings.oidc_discovery_url
|
||||
self.client_id = client_id or settings.oidc_client_id
|
||||
self.client_secret = client_secret or settings.oidc_client_secret
|
||||
self.nextcloud_host = nextcloud_host or settings.nextcloud_host
|
||||
|
||||
self._token_endpoint: Optional[str] = None
|
||||
self._jwks_uri: Optional[str] = None
|
||||
self._discovery_cache: Optional[Dict[str, Any]] = None
|
||||
self._discovery_cache_time: float = 0
|
||||
self._discovery_cache_ttl: float = 3600 # 1 hour
|
||||
|
||||
# Initialize storage for checking provisioning
|
||||
self.storage = RefreshTokenStorage()
|
||||
|
||||
# Create HTTP client
|
||||
self.http_client = httpx.AsyncClient(
|
||||
timeout=30.0,
|
||||
follow_redirects=True,
|
||||
)
|
||||
|
||||
async def __aenter__(self):
|
||||
"""Async context manager entry."""
|
||||
await self.storage.initialize()
|
||||
return self
|
||||
|
||||
async def __aexit__(self, exc_type, exc_val, exc_tb):
|
||||
"""Async context manager exit."""
|
||||
await self.close()
|
||||
|
||||
async def close(self):
|
||||
"""Close HTTP client and storage."""
|
||||
await self.http_client.aclose()
|
||||
# RefreshTokenStorage doesn't have a close method
|
||||
|
||||
async def _discover_endpoints(self) -> Dict[str, Any]:
|
||||
"""Discover OIDC endpoints from discovery URL.
|
||||
|
||||
Returns:
|
||||
Discovery document containing endpoint URLs
|
||||
"""
|
||||
# Check cache
|
||||
if (
|
||||
self._discovery_cache
|
||||
and (time.time() - self._discovery_cache_time) < self._discovery_cache_ttl
|
||||
):
|
||||
return self._discovery_cache
|
||||
|
||||
if not self.oidc_discovery_url:
|
||||
# Fallback to Nextcloud OIDC if no discovery URL
|
||||
self.oidc_discovery_url = urljoin(
|
||||
self.nextcloud_host, "/.well-known/openid-configuration"
|
||||
)
|
||||
|
||||
try:
|
||||
response = await self.http_client.get(self.oidc_discovery_url)
|
||||
response.raise_for_status()
|
||||
|
||||
self._discovery_cache = response.json()
|
||||
self._discovery_cache_time = time.time()
|
||||
|
||||
# Cache frequently used endpoints
|
||||
self._token_endpoint = self._discovery_cache.get("token_endpoint")
|
||||
self._jwks_uri = self._discovery_cache.get("jwks_uri")
|
||||
|
||||
return self._discovery_cache
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to discover OIDC endpoints: {e}")
|
||||
raise
|
||||
|
||||
async def exchange_token_for_delegation(
|
||||
self,
|
||||
flow1_token: str,
|
||||
requested_scopes: list[str],
|
||||
requested_audience: str = "nextcloud",
|
||||
) -> Tuple[str, int]:
|
||||
"""Exchange Flow 1 MCP token for delegated Nextcloud token.
|
||||
|
||||
This implements RFC 8693 Token Exchange for on-behalf-of delegation.
|
||||
|
||||
Args:
|
||||
flow1_token: The MCP session token (aud: "mcp-server")
|
||||
requested_scopes: Scopes needed for this operation
|
||||
requested_audience: Target audience (usually "nextcloud")
|
||||
|
||||
Returns:
|
||||
Tuple of (delegated_token, expires_in)
|
||||
|
||||
Raises:
|
||||
ValueError: If token validation fails
|
||||
RuntimeError: If provisioning not completed or exchange fails
|
||||
"""
|
||||
# 1. Validate Flow 1 token audience
|
||||
await self._validate_flow1_token(flow1_token)
|
||||
|
||||
# 2. Extract user ID from token
|
||||
user_id = self._extract_user_id(flow1_token)
|
||||
|
||||
# 3. Check user has provisioned Nextcloud access (Flow 2)
|
||||
if not await self._check_provisioning(user_id):
|
||||
raise RuntimeError(
|
||||
"Nextcloud access not provisioned. "
|
||||
"User must complete Flow 2 provisioning first."
|
||||
)
|
||||
|
||||
# 4. Get stored refresh token for user (from Flow 2)
|
||||
refresh_token = await self._get_user_refresh_token(user_id)
|
||||
if not refresh_token:
|
||||
raise RuntimeError(
|
||||
"No refresh token found. User must complete provisioning."
|
||||
)
|
||||
|
||||
# 5. Perform token exchange with IdP
|
||||
delegated_token, expires_in = await self._perform_token_exchange(
|
||||
subject_token=flow1_token,
|
||||
refresh_token=refresh_token,
|
||||
requested_scopes=requested_scopes,
|
||||
requested_audience=requested_audience,
|
||||
)
|
||||
|
||||
# 6. Log the exchange for audit trail
|
||||
logger.info(
|
||||
f"Token exchange completed for user {user_id}: "
|
||||
f"scopes={requested_scopes}, audience={requested_audience}, "
|
||||
f"expires_in={expires_in}s"
|
||||
)
|
||||
|
||||
return delegated_token, expires_in
|
||||
|
||||
async def _validate_flow1_token(self, token: str):
|
||||
"""Validate that token has correct audience for MCP server.
|
||||
|
||||
Args:
|
||||
token: JWT token to validate
|
||||
|
||||
Raises:
|
||||
ValueError: If token is invalid or has wrong audience
|
||||
"""
|
||||
try:
|
||||
# Decode without verification first to check audience
|
||||
# In production, should verify signature against JWKS
|
||||
payload = jwt.decode(token, options={"verify_signature": False})
|
||||
|
||||
# Check audience
|
||||
audience = payload.get("aud", [])
|
||||
if isinstance(audience, str):
|
||||
audience = [audience]
|
||||
|
||||
if "mcp-server" not in audience:
|
||||
raise ValueError(
|
||||
f"Invalid token audience. Expected 'mcp-server', got {audience}"
|
||||
)
|
||||
|
||||
# Check expiration
|
||||
exp = payload.get("exp", 0)
|
||||
if exp < time.time():
|
||||
raise ValueError("Token has expired")
|
||||
|
||||
except jwt.DecodeError as e:
|
||||
raise ValueError(f"Invalid JWT token: {e}")
|
||||
|
||||
def _extract_user_id(self, token: str) -> str:
|
||||
"""Extract user ID from JWT token.
|
||||
|
||||
Args:
|
||||
token: JWT token
|
||||
|
||||
Returns:
|
||||
User ID from token
|
||||
"""
|
||||
try:
|
||||
payload = jwt.decode(token, options={"verify_signature": False})
|
||||
|
||||
# Try standard claims in order of preference
|
||||
user_id = (
|
||||
payload.get("sub")
|
||||
or payload.get("preferred_username")
|
||||
or payload.get("email")
|
||||
or payload.get("name")
|
||||
)
|
||||
|
||||
if not user_id:
|
||||
raise ValueError("No user identifier in token")
|
||||
|
||||
return user_id
|
||||
|
||||
except jwt.DecodeError as e:
|
||||
raise ValueError(f"Failed to extract user ID: {e}")
|
||||
|
||||
async def _check_provisioning(self, user_id: str) -> bool:
|
||||
"""Check if user has completed Flow 2 provisioning.
|
||||
|
||||
Args:
|
||||
user_id: User identifier
|
||||
|
||||
Returns:
|
||||
True if provisioned, False otherwise
|
||||
"""
|
||||
token_data = await self.storage.get_refresh_token(user_id)
|
||||
return token_data is not None
|
||||
|
||||
async def _get_user_refresh_token(self, user_id: str) -> Optional[str]:
|
||||
"""Get stored refresh token for user from Flow 2 provisioning.
|
||||
|
||||
Args:
|
||||
user_id: User identifier
|
||||
|
||||
Returns:
|
||||
Refresh token if found, None otherwise
|
||||
"""
|
||||
token_data = await self.storage.get_refresh_token(user_id)
|
||||
if token_data:
|
||||
return token_data.get("refresh_token")
|
||||
return None
|
||||
|
||||
async def _perform_token_exchange(
|
||||
self,
|
||||
subject_token: str,
|
||||
refresh_token: str,
|
||||
requested_scopes: list[str],
|
||||
requested_audience: str,
|
||||
) -> Tuple[str, int]:
|
||||
"""Perform RFC 8693 token exchange with IdP.
|
||||
|
||||
Args:
|
||||
subject_token: The token being exchanged (Flow 1 token)
|
||||
refresh_token: User's stored refresh token for delegation
|
||||
requested_scopes: Minimal scopes for this operation
|
||||
requested_audience: Target audience
|
||||
|
||||
Returns:
|
||||
Tuple of (access_token, expires_in)
|
||||
"""
|
||||
# Discover token endpoint
|
||||
discovery = await self._discover_endpoints()
|
||||
token_endpoint = discovery.get("token_endpoint")
|
||||
|
||||
if not token_endpoint:
|
||||
raise RuntimeError("No token endpoint found in discovery")
|
||||
|
||||
# Build token exchange request per RFC 8693
|
||||
data = {
|
||||
# Token exchange grant type
|
||||
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
|
||||
# The token we're exchanging (Flow 1 MCP token)
|
||||
"subject_token": subject_token,
|
||||
"subject_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
|
||||
# Use refresh token as actor token (proves we have delegation rights)
|
||||
"actor_token": refresh_token,
|
||||
"actor_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
|
||||
# Requested token properties
|
||||
"requested_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
|
||||
"audience": requested_audience,
|
||||
"scope": " ".join(requested_scopes),
|
||||
}
|
||||
|
||||
# Add client credentials if configured
|
||||
if self.client_id and self.client_secret:
|
||||
data["client_id"] = self.client_id
|
||||
data["client_secret"] = self.client_secret
|
||||
|
||||
try:
|
||||
# Attempt RFC 8693 token exchange
|
||||
response = await self.http_client.post(
|
||||
token_endpoint,
|
||||
data=data,
|
||||
headers={"Content-Type": "application/x-www-form-urlencoded"},
|
||||
)
|
||||
|
||||
if response.status_code == 400:
|
||||
# Token exchange might not be supported, fall back to refresh grant
|
||||
logger.info(
|
||||
"Token exchange not supported, falling back to refresh grant"
|
||||
)
|
||||
return await self._fallback_refresh_grant(
|
||||
refresh_token=refresh_token,
|
||||
requested_scopes=requested_scopes,
|
||||
token_endpoint=token_endpoint,
|
||||
)
|
||||
|
||||
response.raise_for_status()
|
||||
result = response.json()
|
||||
|
||||
access_token = result.get("access_token")
|
||||
expires_in = result.get("expires_in", 300) # Default 5 minutes
|
||||
|
||||
if not access_token:
|
||||
raise RuntimeError("No access token in exchange response")
|
||||
|
||||
return access_token, expires_in
|
||||
|
||||
except httpx.HTTPStatusError as e:
|
||||
logger.error(f"Token exchange failed: {e.response.text}")
|
||||
raise RuntimeError(f"Token exchange failed: {e}")
|
||||
except Exception as e:
|
||||
logger.error(f"Token exchange error: {e}")
|
||||
raise
|
||||
|
||||
async def _fallback_refresh_grant(
|
||||
self, refresh_token: str, requested_scopes: list[str], token_endpoint: str
|
||||
) -> Tuple[str, int]:
|
||||
"""Fallback to standard refresh token grant if token exchange not supported.
|
||||
|
||||
This is less secure than token exchange but provides compatibility.
|
||||
|
||||
Args:
|
||||
refresh_token: User's stored refresh token
|
||||
requested_scopes: Minimal scopes for this operation
|
||||
token_endpoint: Token endpoint URL
|
||||
|
||||
Returns:
|
||||
Tuple of (access_token, expires_in)
|
||||
"""
|
||||
data = {
|
||||
"grant_type": "refresh_token",
|
||||
"refresh_token": refresh_token,
|
||||
"scope": " ".join(requested_scopes), # Request minimal scopes
|
||||
}
|
||||
|
||||
# Add client credentials if configured
|
||||
if self.client_id and self.client_secret:
|
||||
data["client_id"] = self.client_id
|
||||
data["client_secret"] = self.client_secret
|
||||
|
||||
try:
|
||||
response = await self.http_client.post(
|
||||
token_endpoint,
|
||||
data=data,
|
||||
headers={"Content-Type": "application/x-www-form-urlencoded"},
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
result = response.json()
|
||||
|
||||
access_token = result.get("access_token")
|
||||
expires_in = result.get("expires_in", 300) # Default 5 minutes
|
||||
|
||||
if not access_token:
|
||||
raise RuntimeError("No access token in refresh response")
|
||||
|
||||
# Log that we're using fallback
|
||||
logger.warning(
|
||||
f"Using refresh grant fallback for token exchange. "
|
||||
f"Scopes: {requested_scopes}"
|
||||
)
|
||||
|
||||
return access_token, expires_in
|
||||
|
||||
except httpx.HTTPStatusError as e:
|
||||
logger.error(f"Refresh grant failed: {e.response.text}")
|
||||
raise RuntimeError(f"Refresh grant failed: {e}")
|
||||
except Exception as e:
|
||||
logger.error(f"Refresh grant error: {e}")
|
||||
raise
|
||||
|
||||
|
||||
# Singleton instance
|
||||
_token_exchange_service: Optional[TokenExchangeService] = None
|
||||
|
||||
|
||||
async def get_token_exchange_service() -> TokenExchangeService:
|
||||
"""Get or create the singleton token exchange service.
|
||||
|
||||
Returns:
|
||||
TokenExchangeService instance
|
||||
"""
|
||||
global _token_exchange_service
|
||||
|
||||
if _token_exchange_service is None:
|
||||
_token_exchange_service = TokenExchangeService()
|
||||
await _token_exchange_service.storage.initialize()
|
||||
|
||||
return _token_exchange_service
|
||||
|
||||
|
||||
async def exchange_token_for_delegation(
|
||||
flow1_token: str, requested_scopes: list[str], requested_audience: str = "nextcloud"
|
||||
) -> Tuple[str, int]:
|
||||
"""Convenience function to exchange tokens.
|
||||
|
||||
Args:
|
||||
flow1_token: The MCP session token (aud: "mcp-server")
|
||||
requested_scopes: Scopes needed for this operation
|
||||
requested_audience: Target audience (usually "nextcloud")
|
||||
|
||||
Returns:
|
||||
Tuple of (delegated_token, expires_in)
|
||||
"""
|
||||
service = await get_token_exchange_service()
|
||||
return await service.exchange_token_for_delegation(
|
||||
flow1_token=flow1_token,
|
||||
requested_scopes=requested_scopes,
|
||||
requested_audience=requested_audience,
|
||||
)
|
||||
Reference in New Issue
Block a user