brandon/nextcloud-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
853 Commits 193 Branches 339 Tags
dc7abcbd481a9c85b9bb1cc0cb233f2d1d6ffae9
Commit Graph

11 Commits

Author SHA1 Message Date
Chris Coutinho dc7abcbd48 fix: move audience mapper from scope to nextcloud-mcp-server client 
The token-exchange-nextcloud scope was being inherited by DCR clients
and requested by external MCP clients (like Gemini CLI), causing all
tokens to have aud: "nextcloud" even when targeting the MCP server.

## Problem

When external clients registered via DCR, they inherited all optional
scopes from the realm defaults, including token-exchange-nextcloud. When
these clients requested tokens, they would include this scope, which added
aud: "nextcloud" via the scope's protocol mapper.

This caused authentication failures for MCP server access:
```
'aud': 'nextcloud'
WARNING - Token rejected: wrong audience ['nextcloud'], expected nextcloud-mcp-server
```

## Root Cause

Client scopes with protocol mappers are applied whenever that scope is
requested, regardless of which client requests it. The token-exchange-nextcloud
scope was designed for the MCP server's own token requests to Nextcloud APIs,
but external clients were also requesting it.

## Solution

Move the audience mapper from the token-exchange-nextcloud scope to a
direct protocol mapper on the nextcloud-mcp-server client itself.

### Changes

1. **Remove token-exchange-nextcloud from nextcloud-mcp-server optional scopes**
   - External DCR clients won't inherit this scope
   - Prevents external clients from requesting it

2. **Add nextcloud-audience protocol mapper directly to nextcloud-mcp-server**
   - Hardcode aud: "nextcloud" for this client only
   - Only tokens issued TO nextcloud-mcp-server will have this audience
   - External MCP clients won't be affected

## Behavior After Fix

**Gemini CLI (DCR client) → MCP Server**:
- Client doesn't have token-exchange-nextcloud scope
- Token audience: Based on RFC 8707 resource parameter (if provided)
- Result: No hardcoded audience ✅

**MCP Server (nextcloud-mcp-server) → Nextcloud APIs**:
- Client has nextcloud-audience protocol mapper
- Token audience: Always "nextcloud" (hardcoded)
- Result: aud: "nextcloud" for Nextcloud API access ✅

## Related
- RFC 8707: Resource Indicators for OAuth 2.0
- Keycloak client scopes vs. client protocol mappers
- DCR client scope inheritance

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-04 06:09:16 +01:00
Chris Coutinho 3d4dfcbb35 fix: move token-exchange-nextcloud from default to optional scopes 
The token-exchange-nextcloud scope was in both default and optional scopes
for the nextcloud-mcp-server client, causing all tokens to have aud: "nextcloud"
even when clients requested tokens for the MCP server itself.

## Problem

When external MCP clients (like Gemini CLI) requested tokens with
`resource=http://localhost:8002/mcp`, the tokens still had `aud: "nextcloud"`
because the token-exchange-nextcloud scope was automatically included as a
default scope. This caused authentication failures:

```
WARNING - Token rejected: wrong audience ['nextcloud'], expected nextcloud-mcp-server
ERROR - Received Nextcloud token in MCP context - client may be using wrong token
```

## Solution

Remove token-exchange-nextcloud from defaultClientScopes array. It remains in
optionalClientScopes for when the MCP server explicitly needs to request tokens
for Nextcloud API access.

### Before
```json
"defaultClientScopes": [
  "web-origins",
  "profile",
  "roles",
  "email",
  "token-exchange-nextcloud"  // ❌ Auto-included
]
```

### After
```json
"defaultClientScopes": [
  "web-origins",
  "profile",
  "roles",
  "email"  // ✅ Only OIDC basics
]
```

## Behavior

**External MCP Clients (Gemini CLI)**:
- Request: `resource=http://localhost:8002/mcp` (no token-exchange scope)
- Token audience: Determined by RFC 8707 resource parameter
- Result: `aud: "http://localhost:8002/mcp"` ✅

**MCP Server → Nextcloud APIs**:
- Request: `scope=token-exchange-nextcloud` (explicitly included)
- Token audience: Set by scope's audience mapper
- Result: `aud: "nextcloud"` ✅

## Related
- RFC 8707: Resource Indicators for OAuth 2.0
- RFC 9728: OAuth 2.0 Protected Resource Metadata
- Previous commit: Removed hardcoded audience-mcp-server mapper

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-04 05:35:07 +01:00
Chris Coutinho de99296779 feat: implement scope-based audience mapping and RFC 9728 support 
This commit removes hardcoded Keycloak audience mappers and implements
dynamic audience assignment based on OAuth client scopes and RFC 8707
resource indicators.

## MCP Server Changes

### Protected Resource Metadata (app.py)
- Change resource field from client_id to URL (RFC 9728 compliance)
- Use `{mcp_server_url}/mcp` as resource identifier
- Update DCR registration to include all Nextcloud API scopes
- Add resource_url parameter to client registration

### Client Registration (auth/client_registration.py)
- Add resource_url parameter to register_client()
- Pass resource_url to DCR endpoint
- Support RFC 9728 resource metadata

### Browser OAuth Routes (auth/browser_oauth_routes.py)
- Enhanced error logging for token exchange failures
- Log HTTP status code and response body for debugging
- Improved error messages for OAuth provisioning issues

### Token Verifier (auth/progressive_token_verifier.py)
- Add introspection_uri and client_secret parameters
- Initialize HTTP client for introspection requests
- Enable opaque token validation support

## Keycloak Configuration

### realm-export.json
- **Remove** hardcoded `audience-mcp-server` protocol mapper
- Audience now determined by client scopes:
  - External clients: RFC 8707 resource parameter → `aud: {resource_url}`
  - MCP Server: `token-exchange-nextcloud` scope → `aud: "nextcloud"`

### OIDC App (third_party/oidc)
- Updated submodule with RFC 9728 support
- Added resource_url database field
- Enhanced introspection authorization logic

## Architecture

Two separate audience flows:

1. **Gemini CLI → MCP Server**
   - Client requests: `resource=http://localhost:8002/mcp`
   - Token audience: `aud: "http://localhost:8002/mcp"`
   - MCP server validates via progressive_token_verifier

2. **MCP Server → Nextcloud APIs**
   - MCP server includes: `scope=token-exchange-nextcloud`
   - Token audience: `aud: "nextcloud"` (via scope mapper)
   - Nextcloud user_oidc validates via SelfEncodedValidator

## Benefits
- ✅ RFC 8707 compliant (resource indicators)
- ✅ RFC 9728 compliant (protected resource metadata)
- ✅ Dynamic audience based on OAuth context
- ✅ Fixes Gemini CLI authentication failures
- ✅ Maintains Nextcloud API access for background jobs
- ✅ Clear security boundaries between flows

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-04 05:28:58 +01:00
Chris Coutinho 0ff85dbe4f feat: implement RFC 8693 Standard Token Exchange for Keycloak 
Configure Keycloak 26.4.2 realm to support Standard Token Exchange V2,
enabling the MCP server to exchange client tokens (aud: nextcloud-mcp-server)
for Nextcloud-scoped tokens (aud: nextcloud) via RFC 8693.

Changes:
- Remove duplicate audience workarounds from realm configuration
- Add token-exchange-nextcloud client scope with audience mapper
- Configure scope as default for nextcloud-mcp-server client
- Enable standard.token.exchange.enabled on both clients
- Add comprehensive integration tests (7 tests, all passing)

Token Exchange Flow:
1. Client obtains token with aud: [nextcloud-mcp-server, nextcloud]
2. Server exchanges to aud: nextcloud, azp: nextcloud-mcp-server
3. Exchanged token used for Nextcloud API calls
4. Each request gets fresh ephemeral token (stateless)

Key Implementation Details:
- Uses Keycloak 26.2+ scope-based authorization (no FGAP required)
- Target audiences must be in client's default/optional scopes
- Protocol mappers alone don't grant exchange permission
- Tokens expire after 300s (5 minutes)

Tests validate:
- Basic token exchange flow
- Nextcloud API integration (Capabilities, Notes)
- CRUD operations with exchanged tokens
- Multiple stateless exchanges from same client token
- Token claims preservation (aud, azp, sub)
- Scope configuration validation

See docs/ADR-004-progressive-consent.md for architecture details.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-04 02:30:37 +01:00
Chris Coutinho 7cb616c7ce feat: Auto-configure impersonation role in Keycloak realm import 
Add service account user with impersonation role to realm-export.json
so that Tier 1 impersonation works out-of-the-box without requiring
manual CLI configuration.

Changes:
- Add service-account-nextcloud-mcp-server user to realm import
- Grant "impersonation" role from "realm-management" client
- Eliminates need for manual `kcadm.sh add-roles` command

Benefits:
- Impersonation tests now pass automatically
- No manual permission configuration required
- Consistent development environment setup

Verified:
- Manual test: tests/manual/test_impersonation.py ✅ PASS
- Integration tests: tests/integration/auth/test_token_exchange_legacy_v1.py ✅ 3 PASS

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-02 22:03:22 +01:00
Chris Coutinho 4c7d1cfc8d test: Add scope-based authorization tests for Keycloak external IdP 
This enhances the Keycloak integration test suite with comprehensive
scope-based authorization validation, matching the OIDC test structure.

Changes:
- Add 3 test users to Keycloak realm (read-only, write-only, no-custom-scopes)
- Create OAuth token fixtures with different scope combinations
- Create MCP client fixtures for each scope configuration
- Add 4 new tests validating scope-based tool filtering:
  * Read-only tokens filter out write tools
  * Write-only tokens filter out read tools
  * Full access tokens show all 90+ tools
  * No custom scopes result in zero tools

Test Results:
- All 15 Keycloak integration tests pass (11 existing + 4 new)
- Validates proper JWT scope enforcement in external IdP architecture
- Confirms security isolation when users decline custom scopes

This completes ADR-002 scope authorization testing for the Keycloak
external identity provider integration.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-02 22:03:21 +01:00
Chris Coutinho 849c67c32a fix: Complete Keycloak external IdP integration with all tests passing 
This commit completes the Keycloak external IdP integration for the MCP
server, implementing ADR-002 Tier 2 (External Identity Provider) with
full Bearer token authentication support.

Key Changes:
1. **Keycloak backchannel-dynamic configuration**
   - Added --hostname-strict=false and --hostname-backchannel-dynamic=true
   - Allows external issuer (localhost:8888) with internal endpoints (keycloak:8080)
   - Solves Docker networking issue where containers can't reach localhost

2. **CORSMiddleware Bearer token patch**
   - Created app-hooks/patches/cors-bearer-token.patch from upstream commit 8fb5e77db82
   - Allows Bearer tokens to bypass CORS/CSRF checks (stateless authentication)
   - Applied via post-installation hook 20-apply-cors-bearer-token-patch.sh
   - Enables app-specific APIs (Notes, Calendar, etc.) to work with Bearer tokens

3. **Patch organization**
   - Moved patches to app-hooks/patches/ directory
   - Updated docker-compose.yml to mount entire app-hooks directory
   - Consolidated patch management for better maintainability

4. **Test improvements**
   - All 11 Keycloak integration tests passing
   - Tests validate OAuth token acquisition, MCP connectivity, token validation,
     tool execution, token persistence, user provisioning, scope filtering,
     and error handling

Architecture:
- Keycloak acts as external OAuth/OIDC identity provider
- MCP server uses Keycloak tokens to access Nextcloud APIs
- Nextcloud user_oidc app validates Bearer tokens from Keycloak
- No admin credentials needed - all API access uses user's OAuth tokens

Cache Note:
- Discovery and JWKS caches must be cleared when switching Keycloak configurations
- Use: docker compose exec redis redis-cli DEL "<cache-key>"
- Or: docker compose exec app php occ user_oidc:provider keycloak --clientid nextcloud

Related:
- ADR-002: Vector sync background jobs authentication
- Validates external IdP integration pattern
- Demonstrates offline_access with refresh tokens (Tier 1 & 2)

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-02 22:03:20 +01:00
Chris Coutinho 6117aaaed3 fix: Complete Keycloak external IdP integration with all tests passing 
This commit completes the Keycloak external identity provider integration,
implementing the ADR-002 architecture where Keycloak acts as an external
OAuth/OIDC provider and Nextcloud validates tokens via the user_oidc app.

Architecture:
  MCP Client → Keycloak (OAuth) → MCP Server → Nextcloud user_oidc → APIs

Key Fixes:

1. Keycloak JWT token configuration
   - Added 'sub' claim protocol mapper to realm-export.json
   - Updated token_verifier.py to accept both 'sub' and 'preferred_username'
   - Ensures tokens contain required OIDC claims

2. Keycloak hostname configuration for Docker networking
   - Implemented --hostname-backchannel-dynamic=true in docker-compose.yml
   - External clients use localhost:8888 (public)
   - Internal services use keycloak:8080 (Docker network)
   - Same issuer (localhost:8888) everywhere for token consistency
   - Restored frontendUrl in realm attributes

3. MCP server provider mode detection
   - Fixed URL normalization to handle port differences (http://app vs http://app:80)
   - Correctly distinguishes integrated mode vs external IdP mode
   - Removes explicit default ports (80 for HTTP, 443 for HTTPS)

4. Nextcloud SSRF protection configuration
   - Added allow_local_remote_servers=true to user_oidc install script
   - Enables Nextcloud to fetch JWKS from internal Keycloak container
   - Required for external IdP token validation

5. OAuth lifespan cleanup
   - Fixed RefreshTokenStorage close() error (uses context managers)
   - Added safe cleanup for oauth_client with hasattr check
   - Prevents session crash on shutdown

6. Test suite fixes
   - Fixed test_user_auto_provisioning to reflect actual behavior
   - Fixed test_scope_filtering_with_keycloak tool name (nc_webdav_write_file)
   - Updated test_keycloak_oauth_client_credentials_discovery for hostname config
   - All 11 Keycloak external IdP tests now passing

Testing:
  ✅ All 11 tests in test_keycloak_external_idp.py passing
  ✅ OAuth token acquisition via Playwright automation
  ✅ Token validation through Nextcloud user_oidc app
  ✅ Write operations (Notes create, Calendar create, File upload)
  ✅ Read operations (search, list, get)
  ✅ Token persistence across multiple operations
  ✅ User authentication and bearer token validation
  ✅ Scope-based tool filtering
  ✅ Error handling for invalid operations

Implementation validates:
  - ADR-002 external identity provider architecture
  - No admin credentials needed in MCP server
  - Centralized identity management via Keycloak
  - Standards-based OAuth 2.0 / OIDC integration
  - User auto-provisioning from IdP claims

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-02 22:03:20 +01:00
Chris Coutinho 403f8be429 feat: Add Keycloak external IdP integration with custom scopes 
Add comprehensive support for using Keycloak as an external identity
provider with Nextcloud custom scopes. This enables testing of ADR-002
external IdP integration patterns.

**Keycloak Realm Configuration:**
- Add frontendUrl attribute to issue tokens with public issuer URL
- Define 18 Nextcloud custom client scopes (notes:read/write,
  calendar:read/write, contacts:read/write, cookbook:read/write,
  deck:read/write, tables:read/write, files:read/write,
  sharing:read/write, todo:read/write)
- Add all custom scopes to nextcloud-mcp-server client optional scopes
- Scopes include consent screen text for user-friendly OAuth flow

**MCP Server Configuration:**
- Add OIDC_JWKS_URI environment variable support
- Implement JWKS URI override logic for Docker networking
- Update NEXTCLOUD_PUBLIC_ISSUER_URL to include full realm path
- Enable MCP server to fetch JWKS from internal Docker network

**Test Infrastructure:**
- Add keycloak_oauth_client_credentials fixture (session-scoped)
- Add keycloak_oauth_token fixture with Playwright automation
- Implement PKCE (S256) support for Keycloak OAuth flow
- Add nc_mcp_keycloak_client fixture for MCP testing
- Create comprehensive test suite in test_keycloak_external_idp.py

**Tests Created:**
- test_keycloak_oauth_token_acquisition: Token acquisition via Playwright
- test_keycloak_oauth_client_credentials_discovery: OIDC discovery
- test_mcp_client_connects_to_keycloak_server: MCP connectivity
- test_external_idp_server_initialization: Server auto-detection
- test_external_idp_token_validation: Token validation flow
- test_tools_work_with_keycloak_token: End-to-end tool execution
- test_keycloak_token_persistence: Multi-operation token reuse
- test_user_auto_provisioning: Nextcloud user provisioning
- test_scope_filtering_with_keycloak: Scope-based tool filtering
- test_keycloak_error_handling: Error handling
- test_external_idp_architecture: Architecture documentation

**Current Status:**
- ✅ Keycloak realm configuration complete
- ✅ Custom scopes defined and available
- ✅ OAuth token acquisition working (1 test passing)
- ⚠️  Token validation needs additional work (external IdP userinfo)

**Files Modified:**
- keycloak/realm-export.json: Realm configuration with scopes
- tests/conftest.py: Keycloak OAuth fixtures (+285 lines)
- tests/server/oauth/test_keycloak_external_idp.py: New test suite
- docker-compose.yml: OIDC_JWKS_URI and issuer configuration
- nextcloud_mcp_server/app.py: JWKS URI override logic

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-02 22:03:20 +01:00
Chris Coutinho e331544cee feat: Implement RFC 8693 token exchange for Keycloak (ADR-002 Tier 2) 
Implements OAuth 2.0 Token Exchange (RFC 8693) enabling the MCP server to
exchange service account tokens for user-scoped tokens. This provides an
alternative to refresh tokens for background operations.

**Core Implementation:**
- Added `get_service_account_token()` method to KeycloakOAuthClient for
  client_credentials grant
- Added `exchange_token_for_user()` method implementing RFC 8693 token exchange
- Fixed Fernet encryption key handling in RefreshTokenStorage (was incorrectly
  base64 decoding already-encoded keys)
- Updated OAuth configuration to support offline_access scope and refresh token
  storage infrastructure

**Keycloak Configuration:**
- Enabled `serviceAccountsEnabled` in realm-export.json
- Added `token.exchange.grant.enabled` attribute
- Added `client.token.exchange.standard.enabled` attribute (required for
  Keycloak 26.2+ Standard Token Exchange V2)
- Fresh Keycloak imports now correctly enable token exchange

**Docker Compose:**
- Added TOKEN_ENCRYPTION_KEY and ENABLE_OFFLINE_ACCESS environment variables
- Created oauth-tokens volume for refresh token storage
- Configured both mcp-oauth and mcp-keycloak services

**Testing & Documentation:**
- Added tests/manual/test_token_exchange.py - Validates complete RFC 8693 flow
- Added tests/manual/test_nextcloud_impersonate.py - Documents session-based
  impersonation limitations
- Added docs/oauth-impersonation-findings.md - Comprehensive investigation
  findings and resolution documentation

**Verified Working:**
✅ Service account token acquisition (client_credentials grant)
✅ RFC 8693 token exchange for internal-to-internal tokens
✅ Exchanged tokens validate with Nextcloud APIs
✅ Keycloak 26.4.2 Standard Token Exchange V2 support

**Known Limitations:**
- User impersonation (requested_subject) requires Keycloak Legacy V1 with
  preview features
- Cross-client token exchange limited to same realm
- Refresh token storage infrastructure ready but unused (MCP protocol limitation)

Dependencies: aiosqlite>=0.20.0

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-02 22:03:19 +01:00
Chris Coutinho 529dc4616b docs: Implement separate clients architecture for Keycloak integration 
Implements proper OAuth 2.0 separation following RFC 8707 best practices
with distinct resource server and OAuth client configurations.

## Architecture Changes

- Create separate "nextcloud" bearer-only client (resource server)
- Configure "nextcloud-mcp-server" OAuth client with audience mapper
- Audience mapper targets "nextcloud" resource server
- Token flow: aud="nextcloud", azp="nextcloud-mcp-server"

## Benefits

- Proper OAuth client vs resource server separation
- Support for future multi-resource tokens: aud=["nextcloud", "other-service"]
- RFC 8707 Resource Indicators compliance
- Clear requester identification via azp claim

## Documentation Updates

- Correct OAuth flow: MCP Client initiates, handles redirect, shares tokens
- Explain MCP Server as protected resource architecture
- Document offline_access with refresh tokens (Tier 1, current)
- Document token exchange with delegation (Tier 2, future when Keycloak adds support)
- Reference Keycloak issue #38279 for delegation status

## Files

- keycloak/realm-export.json: Add separate clients configuration
- app-hooks/post-installation/15-setup-keycloak-provider.sh: Setup user_oidc with "nextcloud" client
- docs/audience-validation-setup.md: Comprehensive documentation with corrected OAuth flow and delegation comparison
- docker-compose.yml: Fix Keycloak healthcheck (bash TCP instead of curl)
- scripts/test_separate_clients.sh: Verification script for architecture

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-02 22:03:19 +01:00