- 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>
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>
Chris Coutinho