feat: Add Keycloak OAuth provider support with refresh token storage
Implements Keycloak as an external OIDC provider following ADR-002 architecture for background job authentication using offline_access. ## Features - Keycloak OAuth provider with PKCE and offline_access support - Refresh token storage with Fernet encryption - Token verifier for both JWT and opaque tokens - Multi-client validation (realm-level trust) - Sample configuration for Keycloak integration ## Implementation ### OAuth Provider (keycloak_oauth.py) - Authorization Code Flow with PKCE - Refresh token exchange - OIDC discovery endpoint support - Token validation with JWKS ### Token Storage (refresh_token_storage.py) - Encrypted storage using Fernet symmetric encryption - SQLite backend for persistence - Token rotation support - Per-user token management ### Token Verifier Updates - Support both JWT (self-encoded) and opaque tokens - JWKS-based JWT signature verification - Introspection endpoint fallback for opaque tokens - Scope extraction from both token types ### Configuration - .env.keycloak.sample: Example configuration with Keycloak URLs - docs/keycloak-multi-client-validation.md: Realm-level validation documentation - app-hooks/post-installation/10-install-user_oidc-app.sh: Updated dependencies ## Architecture Notes - MCP Server is a protected resource (requires OAuth) - MCP Client initiates OAuth flow and shares refresh tokens - Refresh tokens enable background operations without admin credentials - Supports future token exchange delegation when Keycloak implements it ## References - ADR-002: Vector Database Background Sync Authentication - RFC 6749: OAuth 2.0 (offline_access, refresh tokens) - RFC 7517: JSON Web Key (JWK) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
@@ -0,0 +1,141 @@
|
||||
# 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
|
||||
|
||||
# OAuth client storage (for MCP internal use)
|
||||
NEXTCLOUD_OIDC_CLIENT_STORAGE=/app/.oauth/keycloak_oauth_client.json
|
||||
|
||||
# ==============================================================================
|
||||
# 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
|
||||
Reference in New Issue
Block a user