nextcloud-mcp-server/docs/oauth-upstream-status.md

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 (RFC 7636)

Status: ✅ Complete (Merged Upstream)

Affected Component: oidc app

Issue: The OIDC app lacked PKCE (Proof Key for Code Exchange) implementation per RFC 7636.

Resolution: Full PKCE support has been implemented and merged upstream into the oidc app:

Authorization Endpoint (/authorize):

• Accepts code_challenge and code_challenge_method parameters
• Validates code_challenge format (43-128 characters, unreserved chars only)
• Supports both S256 (SHA-256) and plain challenge methods
• Stores challenge and method in database for later verification

Token Endpoint (/token):

• Accepts code_verifier parameter
• Verifies code_verifier against stored code_challenge using proper algorithm
• Uses constant-time comparison to prevent timing attacks
• Enforces code_verifier requirement when PKCE was used in authorization

Discovery Document:

{
  "code_challenge_methods_supported": ["S256", "plain"]
}

Database:

• New columns: code_challenge and code_challenge_method in oc_oauth2_access_tokens
• Migration included for existing installations

Why It Mattered:

• MCP specification requires PKCE with S256 code challenge method
• RFC 7636 PKCE provides security for public clients (no client secret)
• RFC 8414 states that absence of code_challenge_methods_supported means PKCE is not supported
• Prevents authorization code interception attacks

Upstream PR: H2CK/oidc#584 - ✅ Merged 2025-10-20

• Changes: Complete PKCE implementation (+194 lines)
  • Authorization flow with code_challenge validation
  • Token exchange with code_verifier verification
  • Database schema updates
  • Discovery document updates
• Status: Merged and available in v1.10.0+ of the oidc app

---

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	✅ Merged	Medium	✅ PKCE advertisement complete (v1.10.0+)

What Works Without Patches

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

✅ OAuth Flow:

• OIDC discovery with full PKCE support (requires oidc app v1.10.0+)
• Dynamic client registration
• Authorization code flow with PKCE (S256 and plain methods)
• Token exchange with code_verifier verification
• 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: Now complete with oidc app v1.10.0+

• ✅ Full RFC 8414 compliance (PKCE advertisement)
• ✅ 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:

1. Fork the user_oidc app
2. Apply the required patches
3. Install your patched version
4. 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/client/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:

1. Watch the upstream repositories:

   • nextcloud/user_oidc
   • nextcloud/oidc

2. Subscribe to specific issues:

   • user_oidc#1221 - Bearer token support

3. Check Nextcloud release notes for mentions of:

   • Bearer token authentication improvements
   • OIDC/OAuth enhancements
   • AppAPI compatibility

Contributing

Want to help get these patches merged?

1. Test the patches: Run the integration tests and report results
2. Review PRs: Provide feedback on upstream pull requests
3. Document issues: Report any problems or edge cases
4. 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

See Also

• OAuth Architecture - How OAuth works in this implementation
• OAuth Troubleshooting - Common issues and solutions
• OAuth Setup Guide - Configuration instructions

---

Last Updated: 2025-10-20

Next Review: When issue #1221 (Bearer token support) has activity