nextcloud-mcp-server/docs/oauth-impersonation-findings.md

# OAuth Impersonation Investigation Findings

**Date**: 2025-11-02
**Last Updated**: 2025-11-02 (Token Exchange Resolution)
**Status**: Implementation Complete - Token Exchange Working
**Conclusion**: Keycloak Standard Token Exchange (RFC 8693) working for internal-to-internal token exchange. User impersonation requires Legacy V1.

---

## ⚠️ IMPORTANT UPDATE (2025-11-02)

**This document contains outdated information regarding service account tokens.**

After implementation and testing, we discovered that service account tokens (`client_credentials` grant) **violate OAuth "act on-behalf-of" principles** by creating Nextcloud user accounts (e.g., `service-account-nextcloud-mcp-server`). This approach has been **REJECTED** and moved to ADR-002's "Will Not Implement" section.

**Key Changes:**
- ❌ **Service account tokens (client_credentials) are INVALID** - Creates user accounts, breaks audit trail
- ✅ **Token exchange (RFC 8693) is the correct approach** - Implemented and working (ADR-002 Tier 2)
- ✅ **Offline access with refresh tokens** - Still valid for background operations (ADR-002 primary approach)

**For current architecture, see**: `docs/ADR-002-vector-sync-authentication.md`

---

## Summary

We investigated options for implementing user impersonation to enable background operations without requiring admin credentials (ADR-002 Tier 2). Here are the findings:

## 1. Keycloak Token Exchange (RFC 8693)

### What We Implemented
- ✅ Service account token acquisition (`client_credentials` grant)
- ✅ `get_service_account_token()` method in `KeycloakOAuthClient`
- ✅ `exchange_token_for_user()` method implementing RFC 8693
- ✅ Token exchange configuration in Keycloak realm

### What Works ✅
**Keycloak Standard V2 Token Exchange (RFC 8693) is WORKING**:
- ✅ Service account token acquisition via `client_credentials` grant
- ✅ Token exchange for internal-to-internal tokens
- ✅ Audience and scope modifications
- ✅ Integration with Nextcloud APIs using exchanged tokens

**Configuration Requirements**:
To enable Standard Token Exchange in Keycloak 26.2+, add to client attributes in `realm-export.json`:
```json
"attributes": {
  "token.exchange.grant.enabled": "true",
  "client.token.exchange.standard.enabled": "true"
}
```

### Limitations
Keycloak Standard V2 does NOT support:
- ❌ User impersonation (`requested_subject` parameter)
- ❌ Cross-client delegation (limited to same realm)

These features require Legacy V1 with `--features=preview`

### Alternative: Keycloak Legacy V1
Keycloak Legacy Token Exchange (V1) WOULD support user impersonation, but:
- ❌ Requires `--features=preview --features=token-exchange` flag
- ❌ Not suitable for production
- ❌ Deprecated and being phased out

**Decision**: Not viable for production use.

---

## 2. Nextcloud OIDC App Token Exchange

### Discovery Endpoint Analysis
```json
{
  "grant_types_supported": [
    "authorization_code",
    "implicit"
  ]
}
```

### Findings
❌ **Nextcloud OIDC app does NOT support**:
- RFC 8693 token exchange
- `client_credentials` grant
- `refresh_token` grant (refresh tokens not issued)
- User impersonation APIs

The Nextcloud OIDC app is a basic OAuth 2.0 provider focused on:
- Authorization code flow for user login
- JWT tokens for API access
- Scope-based authorization

It is NOT designed for:
- Service accounts
- Token delegation
- Background operations

**Decision**: Not viable - missing required grant types.

---

## 3. Nextcloud Impersonate App

### What It Provides
✅ Admin users can impersonate other users via:
- UI: Settings → Users → Impersonate button
- API: `POST /apps/impersonate/user` with `userId` parameter

### How It Works
```php
// From SettingsController.php
public function impersonate(string $userId): JSONResponse {
    // 1. Verify admin/delegated admin permissions
    // 2. Check target user has logged in before
    // 3. Set session: $this->userSession->setUser($impersonatee)
    // 4. Return success
}
```

### Requirements
- ✅ Admin credentials
- ✅ Session-based authentication (cookies)
- ✅ CSRF token
- ✅ Target user must have logged in at least once
- ❌ Not compatible with encryption-enabled instances

### Limitations for Background Workers
❌ **Session-based, not stateless**:
- Requires maintaining HTTP session/cookies
- Not suitable for distributed workers
- Can't use with bearer tokens
- Requires re-authentication periodically

❌ **Security concerns**:
- Requires admin credentials stored on server
- All impersonated actions logged as target user
- Violates principle of least privilege

**Decision**: Not suitable for background operations - session-based architecture incompatible with stateless OAuth/bearer token model.

---

## 4. What Actually Works

### Option A: Admin Credentials (Current Implementation)
✅ **BasicAuth mode with admin account**:
```python
client = NextcloudClient.from_env()  # Uses NEXTCLOUD_USERNAME/PASSWORD
# Can access all APIs with admin permissions
```

**Pros**:
- Simple, works immediately
- Full access to all APIs

**Cons**:
- Requires admin credentials stored on server
- No per-user permission scoping
- Security risk if credentials leaked
- Violates ADR-002 goals

**Status**: Available but not recommended for production.

### Option B: Service Account with Scoped Permissions
✅ **Create dedicated service account**:
1. Create `mcp-sync` user in Nextcloud
2. Grant specific permissions (group memberships, shares)
3. Use those credentials for background operations

**Pros**:
- Dedicated account, easier to audit
- Can limit permissions via Nextcloud groups
- Works with current BasicAuth implementation

**Cons**:
- Still requires credentials storage
- Can't truly act "as" individual users
- Limited by Nextcloud's permission model

**Status**: Best available option without OAuth delegation.

---

## 5. Recommendations

### Short Term (Immediate)
**Use Service Account Pattern**:
```python
# Background worker configuration
SYNC_ACCOUNT_USERNAME=mcp-sync
SYNC_ACCOUNT_PASSWORD=<secure-password>

# Create service account with limited permissions
docker compose exec app php occ user:add mcp-sync
docker compose exec app php occ group:adduser <appropriate-group> mcp-sync
```

**Benefits**:
- Works with existing implementation
- Better than admin credentials
- Auditable

### Medium Term (If OAuth Delegation Required)
**Wait for proper standards support**:
- Monitor Keycloak for Standard V2 improvements
- Contribute to/request Nextcloud OIDC app enhancements
- Consider alternative identity providers (e.g., Authelia, Authentik)

### Long Term (Ideal Solution)
**Implement proper OAuth delegation**:
1. Use identity provider that supports RFC 8693 properly (e.g., Auth0, Okta)
2. Or implement custom delegation endpoint in Nextcloud
3. Or propose MCP protocol extension for refresh token sharing

---

## 6. Updated ADR-002 Status

| Tier | Solution | Status | Viability |
|------|----------|--------|-----------|
| **Tier 0** | Admin BasicAuth | ✅ Implemented | ⚠️ Works but not recommended |
| **Tier 1** | Offline Access (Refresh Tokens) | ⚠️ Infrastructure ready | ❌ MCP protocol limitation |
| **Tier 2** | Token Exchange (RFC 8693) | ✅ **WORKING** | ✅ **Internal token exchange functional** |
| **Tier 3** | Service Account (NEW) | ✅ Available | ✅ **RECOMMENDED for background ops** |

---

## 7. Implementation Status

### What Was Built
1. ✅ `RefreshTokenStorage` - SQLite + encryption (ready for future use)
2. ✅ `KeycloakOAuthClient.get_service_account_token()` - Works
3. ✅ `KeycloakOAuthClient.exchange_token_for_user()` - Implemented but non-functional
4. ✅ Token exchange configuration - Keycloak realm updated
5. ✅ Test scripts - Comprehensive testing completed

### What to Use
**For Background Operations**:
```python
# Use service account with BasicAuth
from nextcloud_mcp_server.client import NextcloudClient

# In background worker
sync_client = NextcloudClient(
    base_url=os.getenv("NEXTCLOUD_HOST"),
    username=os.getenv("SYNC_ACCOUNT_USERNAME"),
    password=os.getenv("SYNC_ACCOUNT_PASSWORD"),
)

# Perform operations
notes = await sync_client.notes.search_notes("important")
# Index to vector database, etc.
```

**For User Requests**:
```python
# Continue using OAuth bearer tokens
# Per-request client creation as currently implemented
client = get_client_from_context(ctx, nextcloud_host)
```

---

## 8. Files Modified/Created

### Implementation
- `nextcloud_mcp_server/auth/keycloak_oauth.py` - Token exchange methods
- `nextcloud_mcp_server/auth/refresh_token_storage.py` - Token storage (ready for future)
- `nextcloud_mcp_server/app.py` - OAuth configuration updates
- `keycloak/realm-export.json` - Token exchange enabled
- `pyproject.toml` - Added aiosqlite dependency

### Documentation
- `docs/oauth-impersonation-findings.md` - This document
- `docs/ADR-002-vector-sync-authentication.md` - Original architecture decision

### Tests
- `tests/manual/test_token_exchange.py` - Keycloak RFC 8693 testing
- `tests/manual/test_nextcloud_impersonate.py` - Nextcloud impersonate API testing

---

## 9. Conclusion

**Neither Keycloak nor Nextcloud currently provide viable OAuth-based user impersonation for background operations.**

The infrastructure is ready (token storage, exchange methods), but provider limitations prevent use.

**Recommended approach**: Use dedicated service account with appropriate Nextcloud permissions for background operations until proper OAuth delegation becomes available.

The implemented code remains valuable:
- Ready for future when providers add support
- Demonstrates proper OAuth patterns
- Test infrastructure for validation

---

## Appendix: Technical Details

### Keycloak Configuration Applied
```json
{
  "clientId": "nextcloud-mcp-server",
  "serviceAccountsEnabled": true,
  "attributes": {
    "token.exchange.grant.enabled": "true"
  }
}
```

### Test Results - UPDATED (2025-11-02)
```
✅ Service account token acquisition: WORKS
✅ Token exchange discovery: SUPPORTED
✅ Token exchange configuration: ENABLED
✅ Actual token exchange: WORKS (after adding client.token.exchange.standard.enabled)
✅ Nextcloud API access: WORKS with exchanged tokens
```

**Resolution**: The realm-export.json was missing the `client.token.exchange.standard.enabled` attribute. After adding this attribute to keycloak/realm-export.json:128, token exchange works correctly on fresh Keycloak imports.

### Nextcloud Impersonate Results
```
✓ App installation: SUCCESS
✓ Admin can impersonate: YES (session-based)
✗ Bearer token impersonate: NO (requires session cookies)
✗ Stateless impersonate: NOT AVAILABLE
```

---

## 10. Token Exchange Resolution (2025-11-02)

### Problem
Initial token exchange implementation was failing with:
```
"Standard token exchange is not enabled for the requested client"
```

### Root Cause
The `realm-export.json` was missing a critical attribute for Keycloak 26.2+ Standard Token Exchange:
- Had: `"token.exchange.grant.enabled": "true"` ✓
- Missing: `"client.token.exchange.standard.enabled": "true"` ❌

### Fix Applied
Updated `keycloak/realm-export.json` at line 128 to include both attributes:
```json
"attributes": {
  "pkce.code.challenge.method": "S256",
  "use.refresh.tokens": "true",
  "backchannel.logout.session.required": "true",
  "backchannel.logout.url": "http://app:80/index.php/apps/user_oidc/backchannel-logout/keycloak",
  "oauth2.device.authorization.grant.enabled": "false",
  "oidc.ciba.grant.enabled": "false",
  "client_credentials.use_refresh_token": "false",
  "display.on.consent.screen": "false",
  "token.exchange.grant.enabled": "true",
  "client.token.exchange.standard.enabled": "true"  // ADDED
}
```

### Verification
After recreating Keycloak with fresh realm import:
```bash
$ docker compose down -v keycloak && docker compose up -d keycloak
$ uv run python tests/manual/test_token_exchange.py
✅ Token Exchange Test PASSED
```

### Current Status
- ✅ RFC 8693 Token Exchange fully functional
- ✅ Service account token acquisition works
- ✅ Token exchange for internal tokens works
- ✅ Exchanged tokens validate with Nextcloud APIs
- ✅ Realm import automatically applies correct configuration
- ⚠️ User impersonation still requires Keycloak Legacy V1

### Files Modified
- `keycloak/realm-export.json` - Added `client.token.exchange.standard.enabled` attribute
- `docs/oauth-impersonation-findings.md` - Updated with resolution

### Testing
Run the complete token exchange flow:
```bash
uv run python tests/manual/test_token_exchange.py
```