feat(server): Experimental support for OAuth2/OIDC authentication
This commit is contained in:
Chris Coutinho
@@ -0,0 +1,14 @@
|
||||
"""OAuth authentication components for Nextcloud MCP server."""
|
||||
|
||||
from .bearer_auth import BearerAuth
|
||||
from .client_registration import load_or_register_client, register_client
|
||||
from .context_helper import get_client_from_context
|
||||
from .token_verifier import NextcloudTokenVerifier
|
||||
|
||||
__all__ = [
|
||||
"BearerAuth",
|
||||
"NextcloudTokenVerifier",
|
||||
"register_client",
|
||||
"load_or_register_client",
|
||||
"get_client_from_context",
|
||||
]
|
||||
@@ -0,0 +1,34 @@
|
||||
"""Bearer token authentication for httpx."""
|
||||
|
||||
from httpx import Auth, Request
|
||||
|
||||
|
||||
class BearerAuth(Auth):
|
||||
"""
|
||||
Bearer token authentication flow for httpx.
|
||||
|
||||
This auth class adds the Authorization: Bearer <token> header
|
||||
to all outgoing requests.
|
||||
"""
|
||||
|
||||
def __init__(self, token: str):
|
||||
"""
|
||||
Initialize bearer authentication.
|
||||
|
||||
Args:
|
||||
token: The bearer token to use for authentication
|
||||
"""
|
||||
self.token = token
|
||||
|
||||
def auth_flow(self, request: Request):
|
||||
"""
|
||||
Add Authorization header to the request.
|
||||
|
||||
Args:
|
||||
request: The outgoing HTTP request
|
||||
|
||||
Yields:
|
||||
The modified request with Authorization header
|
||||
"""
|
||||
request.headers["Authorization"] = f"Bearer {self.token}"
|
||||
yield request
|
||||
@@ -0,0 +1,260 @@
|
||||
"""Dynamic client registration for Nextcloud OIDC."""
|
||||
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import time
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ClientInfo:
|
||||
"""Client registration information."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
client_id: str,
|
||||
client_secret: str,
|
||||
client_id_issued_at: int,
|
||||
client_secret_expires_at: int,
|
||||
redirect_uris: list[str],
|
||||
):
|
||||
self.client_id = client_id
|
||||
self.client_secret = client_secret
|
||||
self.client_id_issued_at = client_id_issued_at
|
||||
self.client_secret_expires_at = client_secret_expires_at
|
||||
self.redirect_uris = redirect_uris
|
||||
|
||||
@property
|
||||
def is_expired(self) -> bool:
|
||||
"""Check if the client has expired."""
|
||||
return time.time() >= self.client_secret_expires_at
|
||||
|
||||
@property
|
||||
def expires_soon(self) -> bool:
|
||||
"""Check if client expires within 5 minutes."""
|
||||
return time.time() >= (self.client_secret_expires_at - 300)
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
"""Convert to dictionary for storage."""
|
||||
return {
|
||||
"client_id": self.client_id,
|
||||
"client_secret": self.client_secret,
|
||||
"client_id_issued_at": self.client_id_issued_at,
|
||||
"client_secret_expires_at": self.client_secret_expires_at,
|
||||
"redirect_uris": self.redirect_uris,
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, data: dict[str, Any]) -> "ClientInfo":
|
||||
"""Create from dictionary."""
|
||||
return cls(
|
||||
client_id=data["client_id"],
|
||||
client_secret=data["client_secret"],
|
||||
client_id_issued_at=data["client_id_issued_at"],
|
||||
client_secret_expires_at=data["client_secret_expires_at"],
|
||||
redirect_uris=data["redirect_uris"],
|
||||
)
|
||||
|
||||
|
||||
async def register_client(
|
||||
nextcloud_url: str,
|
||||
registration_endpoint: str,
|
||||
client_name: str = "Nextcloud MCP Server",
|
||||
redirect_uris: list[str] | None = None,
|
||||
scopes: str = "openid profile email",
|
||||
) -> ClientInfo:
|
||||
"""
|
||||
Register a new OAuth client with Nextcloud OIDC using dynamic client registration.
|
||||
|
||||
Args:
|
||||
nextcloud_url: Base URL of the Nextcloud instance
|
||||
registration_endpoint: Full URL to the registration endpoint
|
||||
client_name: Name of the client application
|
||||
redirect_uris: List of redirect URIs (default: http://localhost:8000/oauth/callback)
|
||||
scopes: Space-separated list of scopes to request
|
||||
|
||||
Returns:
|
||||
ClientInfo with registration details
|
||||
|
||||
Raises:
|
||||
httpx.HTTPStatusError: If registration fails
|
||||
ValueError: If response is invalid
|
||||
"""
|
||||
if redirect_uris is None:
|
||||
redirect_uris = ["http://localhost:8000/oauth/callback"]
|
||||
|
||||
client_metadata = {
|
||||
"client_name": client_name,
|
||||
"redirect_uris": redirect_uris,
|
||||
"token_endpoint_auth_method": "client_secret_post",
|
||||
"grant_types": ["authorization_code", "refresh_token"],
|
||||
"response_types": ["code"],
|
||||
"scope": scopes,
|
||||
}
|
||||
|
||||
logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
|
||||
logger.debug(f"Registration endpoint: {registration_endpoint}")
|
||||
|
||||
async with httpx.AsyncClient(timeout=30.0) as client:
|
||||
try:
|
||||
response = await client.post(
|
||||
registration_endpoint,
|
||||
json=client_metadata,
|
||||
headers={"Content-Type": "application/json"},
|
||||
)
|
||||
response.raise_for_status()
|
||||
|
||||
client_info = response.json()
|
||||
logger.info(
|
||||
f"Successfully registered client: {client_info.get('client_id')}"
|
||||
)
|
||||
logger.info(
|
||||
f"Client expires at: {client_info.get('client_secret_expires_at')} "
|
||||
f"(in {client_info.get('client_secret_expires_at', 0) - int(time.time())} seconds)"
|
||||
)
|
||||
|
||||
return ClientInfo(
|
||||
client_id=client_info["client_id"],
|
||||
client_secret=client_info["client_secret"],
|
||||
client_id_issued_at=client_info.get(
|
||||
"client_id_issued_at", int(time.time())
|
||||
),
|
||||
client_secret_expires_at=client_info.get(
|
||||
"client_secret_expires_at", int(time.time()) + 3600
|
||||
),
|
||||
redirect_uris=client_info.get("redirect_uris", redirect_uris),
|
||||
)
|
||||
|
||||
except httpx.HTTPStatusError as e:
|
||||
logger.error(f"Failed to register client: HTTP {e.response.status_code}")
|
||||
logger.error(f"Response: {e.response.text}")
|
||||
raise
|
||||
except KeyError as e:
|
||||
logger.error(f"Invalid response from registration endpoint: missing {e}")
|
||||
raise ValueError(f"Invalid registration response: missing {e}")
|
||||
|
||||
|
||||
def load_client_from_file(storage_path: Path) -> ClientInfo | None:
|
||||
"""
|
||||
Load client credentials from storage file.
|
||||
|
||||
Args:
|
||||
storage_path: Path to the JSON file containing client credentials
|
||||
|
||||
Returns:
|
||||
ClientInfo if file exists and is valid, None otherwise
|
||||
"""
|
||||
if not storage_path.exists():
|
||||
logger.debug(f"Client storage file not found: {storage_path}")
|
||||
return None
|
||||
|
||||
try:
|
||||
with open(storage_path, "r") as f:
|
||||
data = json.load(f)
|
||||
|
||||
client_info = ClientInfo.from_dict(data)
|
||||
|
||||
if client_info.is_expired:
|
||||
logger.warning(
|
||||
f"Stored client has expired (expired at {client_info.client_secret_expires_at})"
|
||||
)
|
||||
return None
|
||||
|
||||
logger.info(f"Loaded client from storage: {client_info.client_id[:16]}...")
|
||||
if client_info.expires_soon:
|
||||
logger.warning("Client expires soon (within 5 minutes)")
|
||||
|
||||
return client_info
|
||||
|
||||
except (json.JSONDecodeError, KeyError, ValueError) as e:
|
||||
logger.error(f"Failed to load client from file: {e}")
|
||||
return None
|
||||
|
||||
|
||||
def save_client_to_file(client_info: ClientInfo, storage_path: Path):
|
||||
"""
|
||||
Save client credentials to storage file.
|
||||
|
||||
Args:
|
||||
client_info: Client information to save
|
||||
storage_path: Path to save the JSON file
|
||||
|
||||
Raises:
|
||||
OSError: If file cannot be written
|
||||
"""
|
||||
try:
|
||||
# Create directory if it doesn't exist
|
||||
storage_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Write client info
|
||||
with open(storage_path, "w") as f:
|
||||
json.dump(client_info.to_dict(), f, indent=2)
|
||||
|
||||
# Set restrictive permissions (owner read/write only)
|
||||
os.chmod(storage_path, 0o600)
|
||||
|
||||
logger.info(f"Saved client credentials to {storage_path}")
|
||||
|
||||
except OSError as e:
|
||||
logger.error(f"Failed to save client credentials: {e}")
|
||||
raise
|
||||
|
||||
|
||||
async def load_or_register_client(
|
||||
nextcloud_url: str,
|
||||
registration_endpoint: str,
|
||||
storage_path: str | Path,
|
||||
client_name: str = "Nextcloud MCP Server",
|
||||
redirect_uris: list[str] | None = None,
|
||||
force_register: bool = False,
|
||||
) -> ClientInfo:
|
||||
"""
|
||||
Load client from storage or register a new one if not found/expired.
|
||||
|
||||
This function:
|
||||
1. Checks for existing client credentials in storage
|
||||
2. Validates the credentials are not expired
|
||||
3. Registers a new client if needed
|
||||
4. Saves the new client credentials
|
||||
|
||||
Args:
|
||||
nextcloud_url: Base URL of the Nextcloud instance
|
||||
registration_endpoint: Full URL to the registration endpoint
|
||||
storage_path: Path to store client credentials
|
||||
client_name: Name of the client application
|
||||
redirect_uris: List of redirect URIs
|
||||
force_register: Force registration even if valid credentials exist
|
||||
|
||||
Returns:
|
||||
ClientInfo with valid credentials
|
||||
|
||||
Raises:
|
||||
httpx.HTTPStatusError: If registration fails
|
||||
ValueError: If response is invalid
|
||||
"""
|
||||
storage_path = Path(storage_path)
|
||||
|
||||
# Try to load existing client unless forced to register
|
||||
if not force_register:
|
||||
client_info = load_client_from_file(storage_path)
|
||||
if client_info:
|
||||
return client_info
|
||||
|
||||
# Register new client
|
||||
logger.info("Registering new OAuth client...")
|
||||
client_info = await register_client(
|
||||
nextcloud_url=nextcloud_url,
|
||||
registration_endpoint=registration_endpoint,
|
||||
client_name=client_name,
|
||||
redirect_uris=redirect_uris,
|
||||
)
|
||||
|
||||
# Save to storage
|
||||
save_client_to_file(client_info, storage_path)
|
||||
|
||||
return client_info
|
||||
@@ -0,0 +1,54 @@
|
||||
"""Helper functions for extracting OAuth context from MCP requests."""
|
||||
|
||||
import logging
|
||||
|
||||
from mcp.server.fastmcp import Context
|
||||
from mcp.server.auth.provider import AccessToken
|
||||
|
||||
from ..client import NextcloudClient
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def get_client_from_context(ctx: Context, base_url: str) -> NextcloudClient:
|
||||
"""
|
||||
Extract authenticated user context from MCP request and create NextcloudClient.
|
||||
|
||||
This function retrieves the OAuth access token from the MCP context,
|
||||
extracts the username from the token's resource field (where we stored it
|
||||
during token verification), and creates a NextcloudClient with bearer auth.
|
||||
|
||||
Args:
|
||||
ctx: MCP request context containing session info
|
||||
base_url: Nextcloud base URL
|
||||
|
||||
Returns:
|
||||
NextcloudClient configured with bearer token auth
|
||||
|
||||
Raises:
|
||||
AttributeError: If context doesn't contain expected OAuth session data
|
||||
ValueError: If username cannot be extracted from token
|
||||
"""
|
||||
try:
|
||||
# Get AccessToken from MCP session (set by TokenVerifier)
|
||||
access_token: AccessToken = ctx.request_context.session.access_token
|
||||
|
||||
# Extract username from resource field (RFC 8707)
|
||||
# We stored the username here during token verification
|
||||
username = access_token.resource
|
||||
|
||||
if not username:
|
||||
logger.error("No username found in access token resource field")
|
||||
raise ValueError("Username not available in OAuth token context")
|
||||
|
||||
logger.debug(f"Creating OAuth NextcloudClient for user: {username}")
|
||||
|
||||
# Create client with bearer token
|
||||
return NextcloudClient.from_token(
|
||||
base_url=base_url, token=access_token.token, username=username
|
||||
)
|
||||
|
||||
except AttributeError as e:
|
||||
logger.error(f"Failed to extract OAuth context: {e}")
|
||||
logger.error("This may indicate the server is not running in OAuth mode")
|
||||
raise
|
||||
@@ -0,0 +1,207 @@
|
||||
"""Token verification using Nextcloud OIDC userinfo endpoint."""
|
||||
|
||||
import logging
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from mcp.server.auth.provider import AccessToken, TokenVerifier
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class NextcloudTokenVerifier(TokenVerifier):
|
||||
"""
|
||||
Validates access tokens using Nextcloud OIDC userinfo endpoint.
|
||||
|
||||
This verifier:
|
||||
1. Calls the userinfo endpoint with the bearer token
|
||||
2. Caches successful responses to avoid repeated API calls
|
||||
3. Extracts username from the 'sub' or 'preferred_username' claim
|
||||
4. Optionally supports JWT validation for performance (future enhancement)
|
||||
|
||||
The userinfo endpoint validates the token and returns user claims if valid,
|
||||
or returns HTTP 400/401 if the token is invalid or expired.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
nextcloud_host: str,
|
||||
userinfo_uri: str,
|
||||
cache_ttl: int = 3600,
|
||||
):
|
||||
"""
|
||||
Initialize the token verifier.
|
||||
|
||||
Args:
|
||||
nextcloud_host: Base URL of the Nextcloud instance (e.g., https://cloud.example.com)
|
||||
userinfo_uri: Full URL to the userinfo endpoint
|
||||
cache_ttl: Time-to-live for cached tokens in seconds (default: 3600)
|
||||
"""
|
||||
self.nextcloud_host = nextcloud_host.rstrip("/")
|
||||
self.userinfo_uri = userinfo_uri
|
||||
self.cache_ttl = cache_ttl
|
||||
|
||||
# Cache: token -> (userinfo, expiry_timestamp)
|
||||
self._token_cache: dict[str, tuple[dict[str, Any], float]] = {}
|
||||
|
||||
# HTTP client for userinfo requests
|
||||
self._client = httpx.AsyncClient(timeout=10.0)
|
||||
|
||||
async def verify_token(self, token: str) -> AccessToken | None:
|
||||
"""
|
||||
Verify a bearer token by calling the userinfo endpoint.
|
||||
|
||||
This method:
|
||||
1. Checks the cache first for recent validations
|
||||
2. Calls the userinfo endpoint if not cached
|
||||
3. Returns AccessToken with username stored in metadata
|
||||
|
||||
Args:
|
||||
token: The bearer token to verify
|
||||
|
||||
Returns:
|
||||
AccessToken if valid, None if invalid or expired
|
||||
"""
|
||||
# Check cache first
|
||||
cached = self._get_cached_token(token)
|
||||
if cached:
|
||||
logger.debug("Token found in cache")
|
||||
return cached
|
||||
|
||||
# Validate via userinfo endpoint
|
||||
try:
|
||||
return await self._verify_via_userinfo(token)
|
||||
except Exception as e:
|
||||
logger.warning(f"Token verification failed: {e}")
|
||||
return None
|
||||
|
||||
async def _verify_via_userinfo(self, token: str) -> AccessToken | None:
|
||||
"""
|
||||
Validate token by calling the userinfo endpoint.
|
||||
|
||||
Args:
|
||||
token: The bearer token to verify
|
||||
|
||||
Returns:
|
||||
AccessToken if valid, None otherwise
|
||||
"""
|
||||
try:
|
||||
response = await self._client.get(
|
||||
self.userinfo_uri, headers={"Authorization": f"Bearer {token}"}
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
userinfo = response.json()
|
||||
logger.debug(
|
||||
f"Token validated successfully for user: {userinfo.get('sub')}"
|
||||
)
|
||||
|
||||
# Cache the result
|
||||
expiry = time.time() + self.cache_ttl
|
||||
self._token_cache[token] = (userinfo, expiry)
|
||||
|
||||
# Create AccessToken with username in resource field (workaround for MCP SDK)
|
||||
username = userinfo.get("sub") or userinfo.get("preferred_username")
|
||||
if not username:
|
||||
logger.error("No username found in userinfo response")
|
||||
return None
|
||||
|
||||
return AccessToken(
|
||||
token=token,
|
||||
client_id="", # Not available from userinfo
|
||||
scopes=self._extract_scopes(userinfo),
|
||||
expires_at=int(expiry),
|
||||
resource=username, # Store username in resource field (RFC 8707)
|
||||
)
|
||||
|
||||
elif response.status_code in (400, 401, 403):
|
||||
logger.info(f"Token validation failed: HTTP {response.status_code}")
|
||||
return None
|
||||
else:
|
||||
logger.warning(
|
||||
f"Unexpected response from userinfo: {response.status_code}"
|
||||
)
|
||||
return None
|
||||
|
||||
except httpx.TimeoutException:
|
||||
logger.error("Timeout while validating token via userinfo endpoint")
|
||||
return None
|
||||
except httpx.RequestError as e:
|
||||
logger.error(f"Network error while validating token: {e}")
|
||||
return None
|
||||
except Exception as e:
|
||||
logger.error(f"Unexpected error during token validation: {e}")
|
||||
return None
|
||||
|
||||
def _get_cached_token(self, token: str) -> AccessToken | None:
|
||||
"""
|
||||
Retrieve a token from cache if not expired.
|
||||
|
||||
Args:
|
||||
token: The bearer token to look up
|
||||
|
||||
Returns:
|
||||
AccessToken if cached and valid, None otherwise
|
||||
"""
|
||||
if token not in self._token_cache:
|
||||
return None
|
||||
|
||||
userinfo, expiry = self._token_cache[token]
|
||||
|
||||
# Check if expired
|
||||
if time.time() >= expiry:
|
||||
logger.debug("Cached token expired, removing from cache")
|
||||
del self._token_cache[token]
|
||||
return None
|
||||
|
||||
# Return cached AccessToken
|
||||
username = userinfo.get("sub") or userinfo.get("preferred_username")
|
||||
return AccessToken(
|
||||
token=token,
|
||||
client_id="",
|
||||
scopes=self._extract_scopes(userinfo),
|
||||
expires_at=int(expiry),
|
||||
resource=username,
|
||||
)
|
||||
|
||||
def _extract_scopes(self, userinfo: dict[str, Any]) -> list[str]:
|
||||
"""
|
||||
Extract scopes from userinfo response.
|
||||
|
||||
Since the userinfo response doesn't include the original scopes,
|
||||
we infer them from the claims present in the response.
|
||||
|
||||
Args:
|
||||
userinfo: The userinfo response dictionary
|
||||
|
||||
Returns:
|
||||
List of inferred scopes
|
||||
"""
|
||||
scopes = ["openid"] # Always present
|
||||
|
||||
if "email" in userinfo:
|
||||
scopes.append("email")
|
||||
|
||||
if any(
|
||||
key in userinfo for key in ["name", "given_name", "family_name", "picture"]
|
||||
):
|
||||
scopes.append("profile")
|
||||
|
||||
if "roles" in userinfo:
|
||||
scopes.append("roles")
|
||||
|
||||
if "groups" in userinfo:
|
||||
scopes.append("groups")
|
||||
|
||||
return scopes
|
||||
|
||||
def clear_cache(self):
|
||||
"""Clear the token cache."""
|
||||
self._token_cache.clear()
|
||||
logger.debug("Token cache cleared")
|
||||
|
||||
async def close(self):
|
||||
"""Cleanup resources."""
|
||||
await self._client.aclose()
|
||||
logger.debug("Token verifier closed")
|
||||
Reference in New Issue
Block a user