- Token Broker Service manages Nextcloud access tokens with audience validation
- Implements short-lived token caching (5-minute TTL) with early refresh
- Enhanced token storage schema with ADR-004 fields (flow_type, audience, provisioning)
- MCP provisioning tools for explicit Flow 2 resource authorization
- Comprehensive unit tests for Token Broker Service (14 tests, all passing)
- Environment configuration for Progressive Consent mode
This implements the foundation for the dual OAuth flow architecture where:
- Flow 1: MCP clients authenticate to MCP server (aud: "mcp-server")
- Flow 2: MCP server gets delegated Nextcloud access (aud: "nextcloud")
Users must explicitly call provision_nextcloud_access tool to grant resource access,
implementing the "stateless by default" principle from ADR-004.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace hybrid flow model with true progressive consent where MCP client authenticates directly to IdP (Flow 1) and server requests separate explicit provisioning for Nextcloud access (Flow 2). This separates client authentication from resource authorization, uses distinct client_id for each flow, and keeps server stateless by default until user explicitly grants offline access via provision_nextcloud_access tool.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Refactor ADR-004 to document the proper OAuth architecture where MCP
clients are registered at the IdP level (not with MCP server) and use
a progressive consent pattern with dual OAuth flows.
## Key Changes
### MCP Client Registration
- Document that MCP clients (Claude Desktop, etc.) register at IdP level
- Show DCR and pre-registration options
- Clarify client validation happens against IdP registry
### Progressive Consent Architecture
Replace single "Hybrid Flow" with three-phase progressive consent:
**Phase 1: MCP Client Authentication** (Always)
- MCP client uses own client_id (e.g., "claude-desktop")
- User consents to "Claude Desktop accessing MCP Server"
- MCP server validates client exists at IdP
- Stores MCP client access token
**Phase 2: Nextcloud Consent** (Conditional)
- Only if MCP server doesn't have refresh token for user
- MCP server uses own client_id ("nextcloud-mcp-server")
- User consents to "MCP Server accessing Nextcloud offline"
- MCP server stores master refresh token
- SSO: If already authenticated, only consent needed
**Phase 3: Token Exchange** (Standard PKCE)
- Client exchanges MCP authorization code
- Validates PKCE code_verifier
- Returns access token (aud: mcp-server)
- Client never sees master refresh token
### Implementation Status Section
- Document current implementation as "simplified hybrid flow"
- List what's implemented vs what needs refactoring
- Clarify current tests use simplified version
- Note progressive consent is target architecture
## Benefits of Progressive Consent
✅ Standards-compliant: Proper OAuth clients at IdP level
✅ Secure: Client validation against IdP registry
✅ Efficient: Nextcloud consent only once per user
✅ Transparent: Users understand each authorization step
✅ SSO-friendly: Minimal re-authentication in Phase 2
## Implementation Tracking
The refactoring from simplified hybrid flow to progressive consent will
be tracked in a separate issue. Current implementation demonstrates:
- MCP server can intercept OAuth callbacks
- Refresh tokens stored securely
- PKCE flow works end-to-end
- Tool execution succeeds
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical architectural corrections to properly implement secure token brokering:
## Key Changes:
1. **Removed Dual Token Concept**: MCP server no longer generates its own JWTs.
Instead, it acts as a token broker using IdP-issued tokens with proper
audience validation.
2. **Strict Audience Isolation**:
- Tokens with `aud: "mcp-server"` can ONLY authenticate to MCP server
- Tokens with `aud: "nextcloud"` can ONLY access Nextcloud APIs
- No tokens have multiple audiences (security boundary violation)
- Compromised MCP tokens cannot access Nextcloud directly
3. **Linked Authorization Pattern**: Single OAuth flow obtains a master
refresh token capable of minting tokens for different audiences as needed.
This solves the challenge of needing both MCP authentication and Nextcloud
access from a single user authorization.
4. **Token Broker Implementation**:
- Validates incoming tokens have `audience: "mcp-server"`
- Uses stored refresh tokens to obtain `audience: "nextcloud"` tokens
- Never exposes Nextcloud tokens to MCP clients
- Maintains short-lived cache for performance
5. **PKCE and Native Client Updates**:
- Proper 302 redirects (no HTML pages)
- Complete PKCE verification in token endpoint
- IdP tokens returned directly (not MCP-generated)
6. **Security Enhancements**:
- Comprehensive audience validation examples
- Token exchange pattern documentation
- Keycloak configuration for audience mapping
- Trust boundary diagrams
This architecture maintains strict security boundaries while enabling the
MCP server to act on behalf of users for both authentication and resource
access, following OAuth best practices and enterprise security standards.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major rewrite of ADR-004 to reflect federated authentication pattern with
shared identity provider (IdP) instead of direct Nextcloud authentication.
Key changes:
- Replaced "Sign-in with Nextcloud" with "Federated Authentication"
- Added shared IdP (Keycloak, Okta, Azure AD) as central auth provider
- MCP server now acts as OAuth client to shared IdP, not Nextcloud
- Single user authentication grants both identity and Nextcloud access
- Updated all diagrams to show 4-party architecture
- Removed authorize_nextcloud tool - uses standard 401 flow
- Added proper token rotation with reuse detection
- Clarified Pattern 3 vs Pattern 4 differences in comparison doc
- Pattern 3 can use external IdPs via user_oidc (not limited to NC)
Architecture benefits:
- True single sign-on with enterprise IdP support
- OAuth-compliant on-behalf-of pattern
- Supports SAML/LDAP backends through IdP
- Nextcloud validates IdP tokens, not MCP-specific tokens
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
- Supersedes ADR-002 which fundamentally misunderstood MCP protocol constraints
- Introduces "Sign-in with Nextcloud" architecture pattern
- MCP server becomes OAuth client to enable offline/background operations
- Implements full token rotation with reuse detection for security
- Includes comprehensive implementation details and migration strategy
Key architectural shift:
- From: Pass-through authentication (stateless, no offline access)
- To: MCP server as OAuth client (stateful, full offline capabilities)
The solution enables background workers to operate independently of MCP
sessions by storing and rotating refresh tokens securely.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
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>
This commit implements and documents both RFC 8693 token exchange tiers
from ADR-002, enabling both production-ready delegation and advanced
impersonation capabilities.
- Enable Keycloak preview features (`--features=preview`) to support
both Standard V2 and Legacy V1 token exchange modes
- Update Tier 1 status from "NOT IMPLEMENTED" to "IMPLEMENTED (Legacy V1)"
- Add detailed empirical testing results showing:
- Standard V2 rejects `requested_subject` parameter
- Legacy V1 accepts parameter but requires impersonation permissions
- Complete configuration steps for enabling impersonation
- Add comparison table showing when to use each tier
- Add "When to Use" guidance for both tiers
- Document that Tier 2 (Delegation) is the recommended default
- Update docstring to document both Tier 1 and Tier 2 support
- Add tier-specific logging (shows which tier is being used)
- Document permission requirements for Tier 1 impersonation
**tests/integration/auth/test_token_exchange_standard_v2.py**:
- Test delegation without impersonation (Tier 2)
- Verify sub claim remains unchanged (service account identity)
- Verify no special permissions required
- Test exchanged tokens work with Nextcloud APIs
- All tests PASS ✅
**tests/integration/auth/test_token_exchange_legacy_v1.py**:
- Test impersonation with `requested_subject` (Tier 1)
- Verify sub claim changes to target user
- Auto-skip if impersonation permissions not configured
- Document permission requirements in test docstrings
- Test exchanged tokens work with Nextcloud APIs
**tests/manual/test_impersonation.py**:
- Comprehensive impersonation validation script
- Tests both Standard V2 and Legacy V1 behavior
- Decodes JWT tokens to verify sub claim changes
- Validates tokens against Nextcloud APIs
**tests/manual/configure_impersonation.py**:
- Automated permission configuration helper
- Documents manual Keycloak CLI configuration steps
Both token exchange tiers are now fully implemented and tested:
- **Tier 2 (Delegation)** - ✅ RECOMMENDED
- Standard V2 (production-ready)
- No special permissions required
- Service account identity preserved
- **Tier 1 (Impersonation)** - ✅ Advanced use only
- Legacy V1 (--features=preview required)
- Requires manual permission grant via Keycloak CLI
- Subject claim changes to target user
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Service account tokens (client_credentials grant) violate OAuth "act on-behalf-of"
principles and have been moved to ADR-002's "Will Not Implement" section.
## Problem Discovery
Testing revealed that service account tokens create Nextcloud user accounts
(e.g., `service-account-nextcloud-mcp-server`) due to user_oidc's bearer
provisioning feature. This violates core OAuth principles:
- ❌ Creates stateful server identity in Nextcloud
- ❌ All actions attributed to service account, not real user
- ❌ Breaks audit trail and user attribution
- ❌ Service account becomes "admin by another name"
## Changes
### Documentation (ADR-002)
- Moved service account (old Tier 1) to "Will Not Implement" section
- Added "OAuth Act On-Behalf-Of Principle" section
- Renumbered tiers:
- Tier 1: Impersonation (NOT IMPLEMENTED)
- Tier 2: Delegation via token exchange (IMPLEMENTED)
- Updated status to reflect rejection of service accounts
### Code Warnings
- Added comprehensive warning to KeycloakOAuthClient.get_service_account_token()
- Clarified VALID use: only as subject_token for RFC 8693 token exchange
- Clarified INVALID use: direct API access with service account token
### Supporting Documentation
- CLAUDE.md: Removed outdated "Tier 1" references, added rejection note
- oauth-impersonation-findings.md: Added prominent update banner
- audience-validation-setup.md: Updated tier numbers, added rejection note
- tests/manual/test_token_exchange.py: Added warning comment
## Valid Patterns (ADR-002)
✅ Foreground operations: User's access token from MCP request
✅ Background operations: Token exchange (impersonation/delegation)
✅ Offline access: Refresh tokens with user consent
❌ Service accounts: Creates independent server identity (REJECTED)
## Alternative
If service account pattern is truly needed, use BasicAuth mode instead of
OAuth mode. OAuth mode MUST maintain "act on-behalf-of" semantics.
Related: c12df98 (revert of service account test)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive automated integration test for Keycloak service account
token acquisition via client_credentials grant, validating ADR-002 Tier 1
implementation for external IdP mode.
Changes:
- Add keycloak_oauth_client fixture in tests/conftest.py
- Creates KeycloakOAuthClient instance for service account operations
- Session-scoped fixture with automatic cleanup
- Discovers Keycloak endpoints automatically
- Add test_keycloak_service_account_token_acquisition test
- Tests client_credentials grant token acquisition
- Verifies token response structure (access_token, token_type, expires_in)
- Validates token works with Nextcloud APIs via capabilities endpoint
- Documents limitation for Nextcloud OIDC app (integrated mode)
- Update ADR-002 documentation
- Mark automated test as complete (✅)
- Document supported providers (Keycloak ✅, Nextcloud OIDC app ❌)
- Add note that KeycloakOAuthClient is provider-agnostic
- Clarify that Nextcloud OIDC app support requires config only
Test results:
- ✅ Service account token acquired successfully (300s expiry, Bearer type)
- ✅ Token validated by Nextcloud user_oidc app
- ✅ Token works with Nextcloud capabilities API
Note: Nextcloud OIDC app (integrated mode) service account token support
not yet implemented. See app.py:631-635 for current status.
Resolves: "TODO: Automated integration tests needed for both Keycloak and
Nextcloud OIDC app" from ADR-002
Major changes to ADR-002 (Vector Database Background Sync Authentication):
1. Reordered authentication tiers:
- Tier 1: Service Account Token (client_credentials) - most compatible
- Tier 2: Token Exchange with Impersonation - not implemented
- Tier 3: Token Exchange with Delegation - implemented
2. Removed admin credentials fallback:
- ADR now focuses exclusively on OAuth mode
- Background sync unavailable without proper OAuth configuration
- BasicAuth mode out of scope (credentials already available)
3. Clarified testing status:
- Tier 1: Implemented but only manual tests exist
- Tier 3: Implemented but only manual tests exist
- Added TODO for automated integration tests
4. Removed "Offline Access with Refresh Tokens":
- Documented as "Will Not Implement"
- MCP protocol architecture prevents server from accessing refresh tokens
- Violates OAuth security model (tokens must stay with client)
5. Simplified configuration:
- Removed all admin credential references
- OAuth-only environment variables
- Automatic tier detection based on provider capabilities
The ADR now accurately reflects that refresh tokens should never be shared
between MCP client and server, following OAuth best practices and the
FastMCP SDK architecture.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update oauth-upstream-status.md to clarify patch requirements and document
completed upstream work:
**Clarifications:**
- CORSMiddleware patch is for Nextcloud core server (not user_oidc app)
- Root cause: CORS middleware logs out sessions without CSRF tokens
- Solution: Allow Bearer tokens to bypass CORS/CSRF checks
- Updated all references with actual PR number: nextcloud/server#55878
**Completed oidc app PRs (now documented):**
- ✅H2CK/oidc#586: User consent management (v1.11.0+)
- ✅H2CK/oidc#585: JWT tokens, introspection, scope validation (v1.10.0+)
- ✅H2CK/oidc#584: PKCE support (RFC 7636) (v1.10.0+)
**Updated sections:**
- "What Works Without Patches" - Added JWT, scopes, consent features
- "Upstream PRs Status" - Added completed PRs table
- "Monitoring Upstream Progress" - Focus on remaining work
- Last updated date: 2025-11-02
All OAuth features except app-specific APIs now work out of the box
with oidc app v1.10.0+. Only CORSMiddleware patch remains pending.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Remove the NEXTCLOUD_OIDC_CLIENT_STORAGE environment variable from all
configuration files. OAuth client credentials are now always stored in the
SQLite database, with no option to use a custom JSON file path.
Changes:
- Remove NEXTCLOUD_OIDC_CLIENT_STORAGE from .env.keycloak.sample
- Remove NEXTCLOUD_OIDC_CLIENT_STORAGE from docker-compose.yml (mcp-oauth and mcp-keycloak services)
- Remove NEXTCLOUD_OIDC_CLIENT_STORAGE from Helm deployment template
- Remove NEXTCLOUD_OIDC_CLIENT_STORAGE from test_cli.py test assertions
- Remove --headed flag from pytest addopts (use CLI arg instead)
This simplifies configuration by enforcing a single storage mechanism
(SQLite database) for OAuth client credentials.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
Testing confirmed that the CORSMiddleware Bearer token patch (from upstream
commit 8fb5e77db82) alone is sufficient to enable Bearer token authentication
for all Nextcloud APIs, including app-specific endpoints like Notes and Calendar.
The user_oidc patch (which sets the app_api session flag) is not required when
the CORSMiddleware patch is applied, as it fixes the root cause by allowing
Bearer tokens to bypass CORS/CSRF checks at the framework level.
Validation:
- Restarted Nextcloud with user_oidc patch disabled
- Ran all 11 Keycloak integration tests
- All tests passed without the user_oidc patch
Updated documentation in 10-install-user_oidc-app.sh to explain why the patch
is no longer needed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The Nextcloud OIDC app has updated token_type parameter values:
- Changed from "Bearer" → "opaque" for opaque tokens
- Changed from "JWT" → "jwt" for JWT tokens
Updated test_dcr_token_type.py to use lowercase token_type values:
- token_type="jwt" for JWT-formatted tokens
- token_type="opaque" for opaque/bearer tokens
This fixes test failures where tests were using the old "Bearer" and
"JWT" (uppercase) values which are no longer recognized by the OIDC app.
Fixes test: test_dcr_respects_bearer_token_type
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Chris Coutinho