Merge pull request #254 from cbcoutinho/feature/keycloak

feat: Complete Keycloak external IdP integration with ADR-002 implementation

Author: cbcoutinho

.env.keycloak.sample

@@ -0,0 +1,138 @@
+# Keycloak OAuth Configuration for Nextcloud MCP Server
+#
+# This configuration uses Keycloak as the OAuth/OIDC identity provider
+# while still accessing Nextcloud APIs. Nextcloud's user_oidc app validates
+# Keycloak bearer tokens and provisions users automatically.
+#
+# Architecture: Client → Keycloak (OAuth) → MCP Server → Nextcloud (user_oidc validates) → APIs
+#
+# This enables ADR-002 authentication patterns without admin credentials!
+
+# ==============================================================================
+# OAUTH PROVIDER SELECTION
+# ==============================================================================
+
+# OAuth provider: "keycloak" or "nextcloud" (default)
+OAUTH_PROVIDER=keycloak
+
+# ==============================================================================
+# KEYCLOAK CONFIGURATION
+# ==============================================================================
+
+# Keycloak base URL (accessible from MCP server container)
+KEYCLOAK_URL=http://keycloak:8080
+
+# Keycloak realm name
+KEYCLOAK_REALM=nextcloud-mcp
+
+# OAuth client credentials (from Keycloak realm export or manual configuration)
+KEYCLOAK_CLIENT_ID=nextcloud-mcp-server
+KEYCLOAK_CLIENT_SECRET=mcp-secret-change-in-production
+
+# OIDC discovery URL (auto-constructed from URL + realm, or specify explicitly)
+KEYCLOAK_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+
+# ==============================================================================
+# NEXTCLOUD CONFIGURATION
+# ==============================================================================
+
+# Nextcloud URL (accessible from MCP server container)
+# Used for API access - Keycloak tokens are validated by user_oidc app
+NEXTCLOUD_HOST=http://app:80
+
+# MCP server URL (for OAuth redirect URIs)
+# This is the publicly accessible URL that OAuth clients connect to
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
+
+# Public Keycloak issuer URL (accessible from OAuth clients)
+# If clients access Keycloak via a different URL than the internal one,
+# set this to the public URL for OAuth flows
+NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888
+
+# ==============================================================================
+# REFRESH TOKEN STORAGE (ADR-002 Tier 1: Offline Access)
+# ==============================================================================
+
+# Enable offline_access scope to get refresh tokens
+ENABLE_OFFLINE_ACCESS=true
+
+# Encryption key for storing refresh tokens (generate with instructions below)
+# IMPORTANT: Keep this secret! Tokens are encrypted at rest using this key.
+#
+# Generate a key:
+#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#
+# Example (DO NOT use this in production!):
+# TOKEN_ENCRYPTION_KEY=your-base64-encoded-fernet-key-here
+
+# Path to SQLite database for token storage
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ==============================================================================
+# DOCKER COMPOSE NOTES
+# ==============================================================================
+
+# When running via docker-compose, the mcp-keycloak service is pre-configured
+# with these environment variables. See docker-compose.yml for the full config.
+#
+# Start services:
+#   docker-compose up -d keycloak app mcp-keycloak
+#
+# View logs:
+#   docker-compose logs -f mcp-keycloak
+#
+# Check Keycloak realm:
+#   curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# Check user_oidc provider:
+#   docker compose exec app php occ user_oidc:provider keycloak
+
+# ==============================================================================
+# KEYCLOAK SETUP VERIFICATION
+# ==============================================================================
+
+# 1. Verify Keycloak is running and realm is imported:
+#    curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# 2. Verify Nextcloud user_oidc provider is configured:
+#    docker compose exec app php occ user_oidc:provider keycloak
+#
+# 3. Test OAuth flow manually:
+#    - Get token from Keycloak:
+#      curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+#        -d "grant_type=password" \
+#        -d "client_id=nextcloud-mcp-server" \
+#        -d "client_secret=mcp-secret-change-in-production" \
+#        -d "username=admin" \
+#        -d "password=admin" \
+#        -d "scope=openid profile email offline_access"
+#
+#    - Use token with Nextcloud API:
+#      curl -H "Authorization: Bearer <access_token>" \
+#        http://localhost:8080/ocs/v2.php/cloud/capabilities
+#
+# 4. Connect MCP client to server:
+#    - Point your MCP client to http://localhost:8002
+#    - Complete OAuth flow via Keycloak (credentials: admin/admin)
+#    - Client should receive access token and be able to call MCP tools
+
+# ==============================================================================
+# TROUBLESHOOTING
+# ==============================================================================
+
+# If OAuth flow fails:
+# - Check that Keycloak is accessible: curl http://localhost:8888
+# - Check that user_oidc provider is configured: docker compose exec app php occ user_oidc:provider keycloak
+# - Check MCP server logs: docker-compose logs mcp-keycloak
+# - Verify redirect URIs match in Keycloak client configuration
+#
+# If token validation fails:
+# - Verify user_oidc has bearer validation enabled (--check-bearer=1)
+# - Check Nextcloud logs: docker compose exec app tail -f /var/www/html/data/nextcloud.log
+# - Verify Keycloak discovery URL is accessible from Nextcloud container:
+#   docker compose exec app curl http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# If offline_access/refresh tokens not working:
+# - Verify TOKEN_ENCRYPTION_KEY is set and valid
+# - Check token storage database: ls -lah /app/data/tokens.db (inside container)
+# - Check that offline_access scope is requested in realm configuration

CLAUDE.md

@@ -395,6 +395,137 @@ uv run pytest -m oauth -v
 - Playwright tests run in CI/CD environments
 - Use Firefox browser in CI: `--browser firefox` (Chromium may have issues with localhost redirects)
 
+#### Keycloak OAuth/OIDC Testing (ADR-002 Integration)
+
+The MCP server supports using **Keycloak as an external OAuth/OIDC identity provider** instead of Nextcloud's built-in OIDC app. This validates the ADR-002 architecture for background jobs and external identity providers.
+
+**Architecture:**
+```
+MCP Client → Keycloak (OAuth) → MCP Server → Nextcloud user_oidc (validates token) → APIs
+```
+
+**Key Benefits:**
+- ✅ **No admin credentials needed** - All API access uses user's Keycloak token
+- ✅ **External identity provider** - Demonstrates integration with enterprise IdPs
+- ✅ **ADR-002 validation** - Tests offline_access and refresh token patterns
+- ✅ **User provisioning** - Nextcloud automatically provisions users from Keycloak
+
+**Setup and Testing:**
+```bash
+# 1. Start Keycloak and MCP server with Keycloak OAuth
+docker-compose up -d keycloak app mcp-keycloak
+
+# 2. Verify Keycloak realm is available
+curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+
+# 3. Verify user_oidc provider is configured
+docker compose exec app php occ user_oidc:provider keycloak
+
+# 4. Generate encryption key for refresh token storage (optional, for offline access)
+python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+# Set in environment: export TOKEN_ENCRYPTION_KEY='<key>'
+
+# 5. Test OAuth flow manually
+# Get token from Keycloak:
+TOKEN=$(curl -s -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=mcp-client" \
+  -d "client_secret=mcp-secret-change-in-production" \
+  -d "username=admin" \
+  -d "password=admin" \
+  -d "scope=openid profile email offline_access" | jq -r .access_token)
+
+# Use token with Nextcloud API (validated by user_oidc):
+curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/ocs/v2.php/cloud/capabilities
+
+# 6. Connect MCP client
+# Point client to: http://localhost:8002
+# Complete OAuth flow using Keycloak credentials: admin/admin
+```
+
+**Three MCP Server Containers:**
+- **`mcp`** (port 8000): Basic auth with admin credentials
+- **`mcp-oauth`** (port 8001): Nextcloud OIDC provider (JWT tokens)
+- **`mcp-keycloak`** (port 8002): Keycloak OIDC provider (external IdP)
+
+**Keycloak Configuration:**
+- **Realm**: `nextcloud-mcp` (auto-imported from `keycloak/realm-export.json`)
+- **Client**: `mcp-client` (pre-configured with PKCE, offline_access)
+- **Admin user**: `admin/admin` (created in realm export)
+- **Redirect URIs**: `http://localhost:*/callback`, `http://127.0.0.1:*/callback`
+
+**Environment Variables** (Generic OIDC - works with any provider):
+```bash
+# Generic OIDC configuration (provider-agnostic)
+OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+OIDC_CLIENT_ID=nextcloud-mcp-server        # OAuth client ID
+OIDC_CLIENT_SECRET=mcp-secret-...          # OAuth client secret
+
+# Nextcloud API configuration
+NEXTCLOUD_HOST=http://app:80               # Nextcloud API (token validation in external IdP mode)
+
+# Refresh tokens and token exchange (ADR-002)
+ENABLE_OFFLINE_ACCESS=true                 # Enable refresh tokens
+TOKEN_ENCRYPTION_KEY=<fernet-key>          # Encrypt refresh tokens
+TOKEN_STORAGE_DB=/app/data/tokens.db       # Token storage path
+
+# OAuth scopes (optional - uses defaults if not specified)
+NEXTCLOUD_OIDC_SCOPES=openid profile email offline_access notes:read notes:write ...
+```
+
+**Provider Mode Detection:**
+- **External IdP mode**: If `OIDC_DISCOVERY_URL` issuer ≠ `NEXTCLOUD_HOST` → Uses external provider (Keycloak, Auth0, Okta, etc.)
+- **Integrated mode**: If `OIDC_DISCOVERY_URL` not set or issuer = `NEXTCLOUD_HOST` → Uses Nextcloud OIDC app
+
+**Nextcloud user_oidc Configuration:**
+The `user_oidc` app is automatically configured by `app-hooks/post-installation/15-setup-keycloak-provider.sh`:
+```bash
+# Configured with:
+--check-bearer=1          # Validate bearer tokens
+--bearer-provisioning=1   # Auto-provision users
+--unique-uid=1            # Hash user IDs
+--scope="openid profile email offline_access"
+```
+
+**Troubleshooting:**
+```bash
+# Check Keycloak is running
+docker-compose ps keycloak
+docker-compose logs keycloak
+
+# Check user_oidc provider configuration
+docker compose exec app php occ user_oidc:provider keycloak
+
+# Check MCP server logs
+docker-compose logs -f mcp-keycloak
+
+# Check Nextcloud logs for token validation
+docker compose exec app tail -f /var/www/html/data/nextcloud.log
+
+# Verify Keycloak is accessible from Nextcloud container
+docker compose exec app curl http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+```
+
+**ADR-002 Offline Access Testing:**
+The Keycloak integration enables testing ADR-002's primary authentication pattern (offline access with refresh tokens):
+
+1. **Refresh token storage**: Tokens stored encrypted in SQLite (`/app/data/tokens.db`)
+2. **Token refresh**: Access tokens refreshed automatically when expired
+3. **Background workers**: Can access APIs using stored refresh tokens
+4. **No admin credentials**: All operations use user's OAuth tokens
+
+**Note**: Service account tokens (client_credentials grant) were considered but rejected as they create Nextcloud user accounts and violate OAuth "act on-behalf-of" principles. See ADR-002 "Will Not Implement" section.
+
+See `docs/ADR-002-vector-sync-authentication.md` for architectural details.
+
+**Audience Validation:**
+Tokens include `aud: ["mcp-server", "nextcloud"]` claims for proper security:
+- MCP server validates tokens are intended for it
+- Nextcloud validates tokens include it as audience
+- Prevents token misuse across services
+
+See `docs/audience-validation-setup.md` for configuration details and `docs/keycloak-multi-client-validation.md` for realm-level validation behavior.
+
 ### Configuration Files
 
 - **`pyproject.toml`** - Python project configuration using uv for dependency management

app-hooks/post-installation/0001-Fix-Bearer-token-authentication-causing-session-logo.patch renamed to app-hooks/patches/0001-Fix-Bearer-token-authentication-causing-session-logo.patch

@@ -0,0 +1,18 @@
+diff --git a/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php b/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
+index 4453f5a7d4b..f1ca9b48d21 100644
+--- a/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
++++ b/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
+@@ -73,6 +73,13 @@ class CORSMiddleware extends Middleware {
+ 			$user = array_key_exists('PHP_AUTH_USER', $this->request->server) ? $this->request->server['PHP_AUTH_USER'] : null;
+ 			$pass = array_key_exists('PHP_AUTH_PW', $this->request->server) ? $this->request->server['PHP_AUTH_PW'] : null;
+ 
++			// Allow Bearer token authentication for CORS requests
++			// Bearer tokens are stateless and don't require CSRF protection
++			$authorizationHeader = $this->request->getHeader('Authorization');
++			if (!empty($authorizationHeader) && str_starts_with($authorizationHeader, 'Bearer ')) {
++				return;
++			}
++
+ 			// Allow to use the current session if a CSRF token is provided
+ 			if ($this->request->passesCSRFCheck()) {
+ 				return;

app-hooks/patches/cors-bearer-token.patch

@@ -9,5 +9,13 @@ php /var/www/html/occ app:enable user_oidc
 
 # Configure user_oidc to validate bearer tokens from the OIDC Identity Provider
 php /var/www/html/occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+php /var/www/html/occ config:system:set user_oidc httpclient.allowselfsigned --value=true --type=boolean
 
-patch -u /var/www/html/custom_apps/user_oidc/lib/User/Backend.php -i /docker-entrypoint-hooks.d/post-installation/0001-Fix-Bearer-token-authentication-causing-session-logo.patch
+# Allow Nextcloud to connect to local/internal servers (required for external IdP mode)
+# This enables user_oidc to fetch JWKS from internal Keycloak container
+php /var/www/html/occ config:system:set allow_local_remote_servers --value=true --type=boolean
+
+# Note: The user_oidc app_api session flag patch is NOT required when using the
+# CORSMiddleware Bearer token patch (20-apply-cors-bearer-token-patch.sh).
+# The CORSMiddleware patch fixes the root cause by allowing Bearer tokens to bypass
+# CORS/CSRF checks at the framework level.