admin/mcp-nextcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: Consolidate OAuth callbacks and implement PKCE for all flows

Browse Source 
This PR fixes multiple OAuth-related issues:

## Unified OAuth Callback
- Consolidated `/oauth/callback-nextcloud` and `/oauth/login-callback` into single `/oauth/callback` endpoint
- Flow type determined by session lookup via state parameter (no query params in redirect_uri)
- Fixes redirect_uri validation issues with IdPs requiring exact match
- Legacy endpoints kept as aliases for backwards compatibility

## PKCE Implementation
- Implemented PKCE (RFC 7636) for Flow 2 (resource provisioning)
  - Generate code_verifier and code_challenge
  - Store code_verifier in session storage
  - Retrieve and use in token exchange
- Fixed PKCE for browser login (integrated mode)
  - Previously only worked for external IdP (Keycloak)
  - Now works for both Nextcloud OIDC and external IdP

## Login Elicitation Fixes (ADR-006)
- Fixed elicitation URL to route through MCP server endpoint
  - Changed from direct Nextcloud URL to `/oauth/authorize-nextcloud`
  - Ensures PKCE is properly handled by server
- Fixed login detection after OAuth flow completes
  - Look up refresh token by state parameter instead of user_id
  - Works even when Flow 1 token not present
- Added `get_refresh_token_by_provisioning_client_id()` method

## Session Authentication
- Fixed `/user/page` redirect loop
  - Shared oauth_context with mounted browser_app
  - SessionAuthBackend can now validate sessions correctly

## Tests
- Added comprehensive login elicitation test suite
- Updated scope authorization test expectations
- All 43 OAuth tests passing

## Files Changed
- `app.py`: Shared oauth_context, unified callback route
- `oauth_routes.py`: Unified callback, PKCE for Flow 2
- `browser_oauth_routes.py`: PKCE for integrated mode
- `oauth_tools.py`: Fixed elicitation URL generation
- `refresh_token_storage.py`: Added lookup by provisioning_client_id
- `test_login_elicitation.py`: New test suite

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2025-11-07 21:08:55 +01:00
co-authored by Claude
parent dfa6d08ba7
commit 0c9a9ea24d
13 changed files with 978 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nextcloud_mcp_server/auth/browser_oauth_routes.py
+43 -38
View File
@@ -4,9 +4,11 @@ Separate from MCP OAuth flow - these routes establish browser sessions
for accessing admin UI endpoints like /user/page.
"""
import hashlib
import logging
import os
import secrets
from base64 import urlsafe_b64encode
from urllib.parse import urlencode
import httpx
@@ -53,39 +55,36 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
# Build OAuth authorization URL
mcp_server_url = oauth_config["mcp_server_url"]
callback_uri = f"{mcp_server_url}/oauth/login-callback"
callback_uri = f"{mcp_server_url}/oauth/callback"
# Request only basic OIDC scopes for browser session
# Note: Nextcloud app scopes (notes:read, etc.) are for MCP client access tokens,
# not for the MCP server's own browser authentication
scopes = "openid profile email offline_access"
code_challenge = ""
code_verifier = ""
# Generate PKCE values for ALL modes (both external and integrated IdP require PKCE)
code_verifier = secrets.token_urlsafe(32)
digest = hashlib.sha256(code_verifier.encode()).digest()
code_challenge = urlsafe_b64encode(digest).decode().rstrip("=")
# Store code_verifier in session for retrieval during callback (using state as key)
await storage.store_oauth_session(
session_id=state, # Use state as session ID
client_id="browser-ui",
client_redirect_uri="/user/page",
state=state,
code_challenge=code_challenge,
code_challenge_method="S256",
mcp_authorization_code=code_verifier, # Store code_verifier here temporarily
flow_type="browser",
ttl_seconds=600, # 10 minutes
)
if oauth_client:
# External IdP mode (Keycloak)
# Keycloak requires PKCE, so generate code_verifier and code_challenge
if not oauth_client.authorization_endpoint:
await oauth_client.discover()
# Generate PKCE values
code_verifier, code_challenge = oauth_client.generate_pkce_challenge()
# Store code_verifier temporarily (using state as key)
# We'll retrieve it in the callback using the state parameter
await storage.store_oauth_session(
session_id=state, # Use state as session ID
client_id="browser-ui",
client_redirect_uri="/user/page",
state=state,
code_challenge=code_challenge,
code_challenge_method="S256",
mcp_authorization_code=code_verifier, # Store code_verifier here temporarily
flow_type="browser",
ttl_seconds=600, # 10 minutes
)
idp_params = {
"client_id": oauth_client.client_id,
"redirect_uri": callback_uri,
@@ -138,6 +137,8 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
"response_type": "code",
"scope": scopes,
"state": state,
"code_challenge": code_challenge,
"code_challenge_method": "S256",
"prompt": "consent", # Ensure refresh token
}
@@ -213,20 +214,18 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
oauth_client = oauth_ctx["oauth_client"]
oauth_config = oauth_ctx["config"]
# Retrieve code_verifier from session storage (if using PKCE)
# Retrieve code_verifier from session storage (PKCE required for all modes)
code_verifier = ""
if oauth_client:
# For Keycloak (external IdP), we stored the code_verifier in the session
oauth_session = await storage.get_oauth_session(state)
if oauth_session:
# code_verifier was stored in mcp_authorization_code field
code_verifier = oauth_session.get("mcp_authorization_code", "")
# Clean up the temporary session
# Note: We don't have delete_oauth_session method, but it will expire after TTL
oauth_session = await storage.get_oauth_session(state)
if oauth_session:
# code_verifier was stored in mcp_authorization_code field
code_verifier = oauth_session.get("mcp_authorization_code", "")
# Clean up the temporary session
# Note: We don't have delete_oauth_session method, but it will expire after TTL
# Exchange authorization code for tokens
mcp_server_url = oauth_config["mcp_server_url"]
callback_uri = f"{mcp_server_url}/oauth/login-callback"
callback_uri = f"{mcp_server_url}/oauth/callback"
try:
if oauth_client:
@@ -263,16 +262,22 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
discovery = response.json()
token_endpoint = discovery["token_endpoint"]
token_params = {
"grant_type": "authorization_code",
"code": code,
"redirect_uri": callback_uri,
"client_id": oauth_config["client_id"],
"client_secret": oauth_config["client_secret"],
}
# Add code_verifier for PKCE (required by Nextcloud OIDC)
if code_verifier:
token_params["code_verifier"] = code_verifier
async with httpx.AsyncClient() as http_client:
response = await http_client.post(
token_endpoint,
data={
"grant_type": "authorization_code",
"code": code,
"redirect_uri": callback_uri,
"client_id": oauth_config["client_id"],
"client_secret": oauth_config["client_secret"],
},
data=token_params,
)
response.raise_for_status()
token_data = response.json()
nextcloud_mcp_server/auth/keycloak_oauth.py
+2
View File
@@ -90,6 +90,8 @@ class KeycloakOAuthClient:
)
# Parse server URL to construct redirect URI
# Note: This is for OAuth client initialization, not used for actual redirects
# since this client is used for backend token operations (exchange, refresh)
parsed_url = urlparse(server_url)
redirect_uri = f"{parsed_url.scheme}://{parsed_url.netloc}/oauth/callback"
nextcloud_mcp_server/auth/oauth_routes.py
+134 -14
View File
@@ -1,7 +1,7 @@
"""
OAuth 2.0 Login Routes for ADR-004 Progressive Consent Architecture
OAuth 2.0 Login Routes for ADR-004 (Offline Access Architecture)
Implements dual OAuth flows with explicit provisioning:
Implements dual OAuth flows with optional offline access provisioning:
Flow 1: Client Authentication - MCP client authenticates directly to IdP
- Client requests: Nextcloud MCP resource scopes (notes:*, calendar:*, etc.)
@@ -19,8 +19,11 @@ Flow 2: Resource Provisioning - MCP server gets delegated Nextcloud access
"""
import hashlib
import logging
import os
import secrets
from base64 import urlsafe_b64encode
from urllib.parse import urlencode
import httpx
@@ -118,7 +121,7 @@ async def oauth_authorize(request: Request) -> RedirectResponse | JSONResponse:
status_code=400,
)
# Validate client_id (required for Progressive Consent Flow 1)
# Validate client_id (required for Flow 1)
if not client_id:
return JSONResponse(
{
@@ -168,7 +171,7 @@ async def oauth_authorize(request: Request) -> RedirectResponse | JSONResponse:
# The MCP server does NOT see the IdP authorization code!
logger.info(
f"Starting Progressive Consent Flow 1 - no server session needed, "
f"Starting Flow 1 - no server session needed, "
f"client will handle IdP response directly at {redirect_uri}"
)
@@ -188,7 +191,7 @@ async def oauth_authorize(request: Request) -> RedirectResponse | JSONResponse:
# Use client's own client_id (client must be pre-registered at IdP)
idp_client_id = client_id
logger.info("Flow 1 (Progressive Consent): Direct client auth to IdP")
logger.info("Flow 1: Direct client auth to IdP")
logger.info(f" Client ID: {client_id}")
logger.info(f" Client will receive IdP code directly at: {callback_uri}")
logger.info(f" Scopes: {scopes} (resource access for MCP tools)")
@@ -314,12 +317,31 @@ async def oauth_authorize_nextcloud(
)
mcp_server_url = oauth_config["mcp_server_url"]
callback_uri = f"{mcp_server_url}/oauth/callback-nextcloud"
callback_uri = f"{mcp_server_url}/oauth/callback"
# Flow 2: Server only needs identity + offline access (no resource scopes)
# Resource scopes are requested by client in Flow 1
scopes = "openid profile email offline_access"
# Generate PKCE values (required by Nextcloud OIDC)
code_verifier = secrets.token_urlsafe(32)
digest = hashlib.sha256(code_verifier.encode()).digest()
code_challenge = urlsafe_b64encode(digest).decode().rstrip("=")
# Store code_verifier in session for retrieval during callback
storage = oauth_ctx["storage"]
await storage.store_oauth_session(
session_id=state,
client_id=mcp_server_client_id,
client_redirect_uri=callback_uri,
state=state,
code_challenge=code_challenge,
code_challenge_method="S256",
mcp_authorization_code=code_verifier, # Store code_verifier here temporarily
flow_type="flow2",
ttl_seconds=600, # 10 minutes
)
# Get authorization endpoint
discovery_url = oauth_config.get("discovery_url")
if not discovery_url:
@@ -358,6 +380,8 @@ async def oauth_authorize_nextcloud(
"response_type": "code",
"scope": scopes,
"state": state,
"code_challenge": code_challenge,
"code_challenge_method": "S256",
"prompt": "consent", # Force consent to show resource access
"access_type": "offline", # Request refresh token
"resource": oauth_config["nextcloud_resource_uri"], # Nextcloud audience
@@ -416,6 +440,16 @@ async def oauth_callback_nextcloud(request: Request):
storage: RefreshTokenStorage = oauth_ctx["storage"]
oauth_config = oauth_ctx["config"]
# Retrieve code_verifier from session storage (PKCE required by Nextcloud OIDC)
code_verifier = ""
oauth_session = await storage.get_oauth_session(state)
if oauth_session:
# code_verifier was stored in mcp_authorization_code field
code_verifier = oauth_session.get("mcp_authorization_code", "")
logger.info(
f"Retrieved code_verifier for Flow 2 callback (state={state[:16]}...)"
)
# Exchange code for tokens
mcp_server_client_id = os.getenv(
"MCP_SERVER_CLIENT_ID", oauth_config.get("client_id")
@@ -424,7 +458,7 @@ async def oauth_callback_nextcloud(request: Request):
"MCP_SERVER_CLIENT_SECRET", oauth_config.get("client_secret")
)
mcp_server_url = oauth_config["mcp_server_url"]
callback_uri = f"{mcp_server_url}/oauth/callback-nextcloud"
callback_uri = f"{mcp_server_url}/oauth/callback"
discovery_url = oauth_config.get("discovery_url")
async with httpx.AsyncClient() as http_client:
@@ -433,17 +467,24 @@ async def oauth_callback_nextcloud(request: Request):
discovery = response.json()
token_endpoint = discovery["token_endpoint"]
# Build token exchange params
token_params = {
"grant_type": "authorization_code",
"code": code,
"redirect_uri": callback_uri,
"client_id": mcp_server_client_id,
"client_secret": mcp_server_client_secret,
}
# Add code_verifier for PKCE (required by Nextcloud OIDC)
if code_verifier:
token_params["code_verifier"] = code_verifier
# Exchange code for tokens
async with httpx.AsyncClient() as http_client:
response = await http_client.post(
token_endpoint,
data={
"grant_type": "authorization_code",
"code": code,
"redirect_uri": callback_uri,
"client_id": mcp_server_client_id,
"client_secret": mcp_server_client_secret,
},
data=token_params,
)
response.raise_for_status()
token_data = response.json()
@@ -502,3 +543,82 @@ async def oauth_callback_nextcloud(request: Request):
from starlette.responses import HTMLResponse
return HTMLResponse(content=success_html, status_code=200)
async def oauth_callback(request: Request):
"""
Unified OAuth callback endpoint supporting multiple flows.
This endpoint consolidates all OAuth callback handling into a single URL.
The flow type is determined by looking up the OAuth session using the
state parameter.
This simplifies IdP configuration by requiring only one callback URL
to be registered: /oauth/callback
Query parameters:
code: Authorization code from IdP
state: CSRF protection state (also used to lookup flow type)
error: Error code (if authorization failed)
Returns:
Response from the appropriate flow handler
"""
# Get state parameter to lookup OAuth session
state = request.query_params.get("state")
if not state:
logger.warning("Unified callback called without state parameter")
return JSONResponse(
{
"error": "invalid_request",
"error_description": "state parameter is required",
},
status_code=400,
)
# Lookup OAuth session to determine flow type
oauth_ctx = request.app.state.oauth_context
if not oauth_ctx:
logger.error("OAuth context not available")
return JSONResponse(
{
"error": "server_error",
"error_description": "OAuth not configured on server",
},
status_code=500,
)
storage = oauth_ctx["storage"]
oauth_session = await storage.get_oauth_session(state)
# Determine flow type from session, default to "browser" for backwards compatibility
flow_type = (
oauth_session.get("flow_type", "browser") if oauth_session else "browser"
)
logger.info(f"Unified callback: flow_type={flow_type} (from session lookup)")
if flow_type == "flow2":
# Flow 2: Resource Provisioning - MCP server gets delegated Nextcloud access
logger.info("Routing to Flow 2 (resource provisioning)")
return await oauth_callback_nextcloud(request)
elif flow_type == "browser":
# Browser UI Login - establish browser session for /user/page access
logger.info("Routing to browser login flow")
from nextcloud_mcp_server.auth.browser_oauth_routes import (
oauth_login_callback,
)
return await oauth_login_callback(request)
else:
# Unknown flow type
logger.warning(f"Unknown flow_type in OAuth session: {flow_type}")
return JSONResponse(
{
"error": "invalid_request",
"error_description": f"Unknown flow type: {flow_type}",
},
status_code=400,
)
nextcloud_mcp_server/auth/provisioning_decorator.py
+3 -3
View File
@@ -1,8 +1,8 @@
"""
Provisioning decorator for ADR-004 Progressive Consent Architecture.
Provisioning decorator for ADR-004 (Offline Access Architecture).
This decorator ensures users have completed Flow 2 (Resource Provisioning)
before accessing Nextcloud resources.
before accessing Nextcloud resources when offline access is enabled.
"""
import functools
@@ -73,7 +73,7 @@ def require_provisioning(func: Callable) -> Callable:
logger.debug("Token exchange mode detected - skipping provisioning check")
return await func(*args, **kwargs)
# Progressive Consent mode (offline access) - check if user has completed Flow 2 provisioning
# Offline access mode - check if user has completed Flow 2 provisioning
# Get user_id from authorization token
user_id = None
if hasattr(ctx, "authorization") and ctx.authorization:
nextcloud_mcp_server/auth/refresh_token_storage.py
+78
View File
@@ -430,6 +430,84 @@ class RefreshTokenStorage:
logger.error(f"Failed to decrypt refresh token for user {user_id}: {e}")
return None
async def get_refresh_token_by_provisioning_client_id(
self, provisioning_client_id: str
) -> Optional[dict]:
"""
Retrieve and decrypt refresh token by provisioning_client_id (state parameter).
This is used to check if an OAuth Flow 2 login completed successfully
by looking up the refresh token using the state parameter that was generated
during the authorization request.
Args:
provisioning_client_id: OAuth state parameter from the authorization request
Returns:
Dictionary with token data or None if not found
"""
if not self._initialized:
await self.initialize()
async with aiosqlite.connect(self.db_path) as db:
async with db.execute(
"""
SELECT user_id, encrypted_token, expires_at, flow_type, token_audience,
provisioned_at, provisioning_client_id, scopes
FROM refresh_tokens WHERE provisioning_client_id = ?
""",
(provisioning_client_id,),
) as cursor:
row = await cursor.fetchone()
if not row:
logger.debug(
f"No refresh token found for provisioning_client_id {provisioning_client_id[:16]}..."
)
return None
(
user_id,
encrypted_token,
expires_at,
flow_type,
token_audience,
provisioned_at,
prov_client_id,
scopes_json,
) = row
# Check expiration
if expires_at is not None and expires_at < time.time():
logger.warning(
f"Refresh token for provisioning_client_id {provisioning_client_id[:16]}... has expired"
)
return None
try:
decrypted_token = self.cipher.decrypt(encrypted_token).decode()
scopes = json.loads(scopes_json) if scopes_json else None
logger.debug(
f"Retrieved refresh token for provisioning_client_id {provisioning_client_id[:16]}... (user_id: {user_id})"
)
return {
"user_id": user_id,
"refresh_token": decrypted_token,
"expires_at": expires_at,
"flow_type": flow_type or "hybrid",
"token_audience": token_audience or "nextcloud",
"provisioned_at": provisioned_at,
"provisioning_client_id": prov_client_id,
"scopes": scopes,
}
except Exception as e:
logger.error(
f"Failed to decrypt refresh token for provisioning_client_id {provisioning_client_id[:16]}...: {e}"
)
return None
async def delete_refresh_token(self, user_id: str) -> bool:
"""
Delete refresh token for user.
nextcloud_mcp_server/auth/scope_authorization.py
+5 -5
View File
@@ -130,13 +130,13 @@ def require_scopes(*required_scopes: str):
token_scopes = set(access_token.scopes or [])
required_scopes_set = set(required_scopes)
# Check if Progressive Consent is enabled
enable_progressive = (
os.getenv("ENABLE_PROGRESSIVE_CONSENT", "false").lower() == "true"
# Check if offline access is enabled
enable_offline_access = (
os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
)
# In Progressive Consent mode, check if Nextcloud scopes require provisioning
if enable_progressive:
# In offline access mode, check if Nextcloud scopes require provisioning
if enable_offline_access:
# Check if any required scopes are Nextcloud-specific
nextcloud_scopes = [
s