brandon/nextcloud-mcp-server

Fork 0

Files

T

Chris Coutinho 3ed24bd5e3 docs: restructure documentation

2025-10-14 01:23:49 +02:00

6.9 KiB

Raw Blame History

OAuth Upstream Status

This document tracks the status of upstream patches and pull requests required for full OAuth functionality.

Overview

The Nextcloud MCP Server's OAuth implementation relies on two Nextcloud apps:

oidc - OIDC Identity Provider (Authorization Server)
user_oidc - OpenID Connect user backend (Token validation)

While the core OAuth flow works, there are pending upstream improvements that enhance functionality and standards compliance.

Required Patches

1. Bearer Token Support for Non-OCS Endpoints

Status: 🟡 Patch Required (Pending Upstream)

Affected Component: user_oidc app

Issue: Bearer token authentication fails for app-specific APIs (Notes, Calendar, etc.) with 401 Unauthorized errors, even though OCS APIs work correctly.

Root Cause: The CORSMiddleware in Nextcloud logs out sessions created by Bearer token authentication when CSRF tokens are missing, which breaks API requests.

Solution: Set the app_api session flag during Bearer token authentication to bypass CSRF checks.

Upstream PR: nextcloud/user_oidc#1221

Workaround: Manually apply the patch to lib/User/Backend.php in the user_oidc app

Impact:

✅ Works: OCS APIs (/ocs/v2.php/cloud/capabilities)
❌ Requires Patch: App APIs (/apps/notes/api/, /apps/calendar/, etc.)

Files Modified: lib/User/Backend.php in user_oidc app

Patch Summary:

// Add before successful Bearer token authentication returns
$this->session->set('app_api', true);

This is added at lines ~243, ~310, ~315, and ~337 in Backend.php.

2. PKCE Support Advertisement in Discovery

Status: 🟢 PR Submitted (Pending Review)

Affected Component: oidc app

Issue: The OIDC discovery endpoint (/.well-known/openid-configuration) does not advertise PKCE support in the code_challenge_methods_supported field.

Why It Matters:

MCP specification requires PKCE with S256 code challenge method
RFC 8414 states that absence of code_challenge_methods_supported means PKCE is not supported
Some MCP clients may reject providers without proper PKCE advertisement

Current Behavior:

PKCE functionally works (the OIDC app accepts and validates PKCE)
PKCE just isn't advertised in discovery metadata

Recommended Fix: Update oidc app to include:

{
  "code_challenge_methods_supported": ["S256"]
}

Workaround: The MCP server implements PKCE validation and logs a warning if not advertised. Functionality still works.

Upstream PR: H2CK/oidc#584 - Submitted 2025-10-13

Changes: Adds code_challenge_methods_supported: ["S256"] to discovery document when PKCE is enabled
Size: +5 lines added, 0 deleted
Status: Open, awaiting review

Upstream PRs Status

PR/Issue	Component	Status	Priority	Notes
user_oidc#1221	`user_oidc`	🟡 Open	High	Required for app-specific APIs
H2CK/oidc#584	`oidc`	🟢 PR Open	Medium	PKCE advertisement for standards compliance

What Works Without Patches

The following functionality works out of the box without any patches:

✅ OAuth Flow:

OIDC discovery
Dynamic client registration
Authorization code flow with PKCE
Token exchange
Userinfo endpoint

✅ MCP Server as Resource Server:

Token validation via userinfo
Per-user client instances
Token caching

✅ Nextcloud OCS APIs:

Capabilities endpoint
All OCS-based APIs

What Requires Patches

The following functionality requires upstream patches:

🟡 App-Specific APIs (Requires user_oidc#1221):

Notes API (/apps/notes/api/)
Calendar API (CalDAV)
Contacts API (CardDAV)
Deck API
Tables API
Custom app APIs

🟡 Standards Compliance (PKCE advertisement):

Full RFC 8414 compliance
MCP client compatibility guarantee

Installation Instructions

For Development/Testing

If the upstream PRs are not yet merged, you can apply patches manually:

1. Apply Bearer Token Patch

# SSH into Nextcloud server
cd /path/to/nextcloud/apps/user_oidc

# Download and apply patch
# (Patch file to be created once PR is ready)
wget https://github.com/nextcloud/user_oidc/pull/XXXX.patch
git apply XXXX.patch

# Or manually edit lib/User/Backend.php
# Add this line before each return statement in getCurrentUserId():
#   $this->session->set('app_api', true);

2. Verify Installation

# Test with OAuth token
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your.nextcloud.com/apps/notes/api/v1/notes

# Should return notes JSON (not 401)

For Production

Recommendation: Wait for upstream PRs to be merged and included in official Nextcloud releases before deploying OAuth in production.

Alternative: Use a patched version of user_oidc app in your deployment:

Fork the user_oidc app
Apply the required patches
Install your patched version
Document the changes for your team

Testing

The integration test suite validates OAuth functionality:

# Start OAuth-enabled MCP server
docker-compose up --build -d mcp-oauth

# Run comprehensive OAuth tests
uv run pytest tests/integration/test_oauth_playwright.py --browser firefox -v

# Tests verify:
# - OAuth flow completion
# - Token validation
# - MCP tool calls with Bearer tokens
# - Notes API access (requires patch)

Monitoring Upstream Progress

To track progress on these issues:

Watch the upstream repositories:
- nextcloud/user_oidc
- nextcloud/oidc
Subscribe to specific issues:
- user_oidc#1221 - Bearer token support
Check Nextcloud release notes for mentions of:
- Bearer token authentication improvements
- OIDC/OAuth enhancements
- AppAPI compatibility

Contributing

Want to help get these patches merged?

Test the patches: Run the integration tests and report results
Review PRs: Provide feedback on upstream pull requests
Document issues: Report any problems or edge cases
Contribute code: Submit improvements or fixes to upstream

Timeline Expectations

Best Case: PRs merged in next Nextcloud minor release (est. 3-6 months)

Realistic: PRs reviewed and merged within 6-12 months

Meanwhile: Use the workarounds documented in this guide

6.9 KiB Raw Blame History