OpenMetadata MCP OAuth Implementation

OAuth 2.0 authentication server for Model Context Protocol (MCP) integration with OpenMetadata, enabling secure access to metadata through Claude Desktop and other MCP clients.

Overview

This module implements a complete OAuth 2.0 Authorization Code Flow with PKCE for MCP clients, enabling user authentication via OpenMetadata's existing SSO providers (Google, Okta, Azure AD, Auth0, AWS Cognito, Custom OIDC, LDAP, SAML) or Basic Auth. The implementation provides secure, standards-compliant access to OpenMetadata's metadata management capabilities through MCP tools.

Important: This is user SSO authentication for MCP clients, not connector-based OAuth for data sources. Users authenticate with their OpenMetadata credentials (SSO or username/password), and MCP tools execute with that user's permissions.

Features

OAuth 2.0 Implementation

• Authorization Code Flow with PKCE - RFC 7636 compliant, preventing authorization code interception attacks
• Refresh Token Rotation - Automatic token refresh with rotation for enhanced security
• Token Encryption - Fernet symmetric encryption for tokens at rest
• CSRF Protection - State parameter validation across the OAuth flow
• Session Fixation Prevention - Session regeneration after successful authentication

Authentication Methods

• SSO Integration - OAuth 2.0 integration with Google, Okta, Azure AD, Auth0, AWS Cognito, Custom OIDC, LDAP, and SAML providers via pac4j
• Basic Auth - Username/password authentication with OpenMetadata credentials
• User Impersonation - Support for impersonated user contexts in MCP tools
• Auto-Detection - Automatically selects SSO or Basic Auth based on OpenMetadata configuration

Security Features

• PKCE Validation - SHA-256 code challenge/verifier validation
• Token Expiry Management - Configurable access token (1 hour) and refresh token (7 days) lifetimes
• Rate Limiting - Registration (10/hour per IP) and token (30/minute per IP) endpoint protection
• Thread-Safe Concurrent Processing - ThreadLocal storage for request isolation
• Audit Logging - OAuth operations logged via SLF4J (oauth_audit_log table available for future use)

Database-Driven Configuration

• Runtime Configuration - Update MCP settings without server restart via REST API
• Cluster Synchronization - Database polling (10-second interval) ensures all cluster instances have consistent configuration
• Configuration Change Listeners - Dynamic CORS origin updates when configuration changes
• Persistent Storage - Configuration changes persist across server restarts (database-first, YAML fallback)
• HTTP Timeout Configuration - Configurable connection and read timeouts for SSO provider metadata fetching

MCP Integration

• Claude Desktop Support - First-class integration with Claude Desktop MCP client
• OAuth Discovery Endpoints - Standard .well-known endpoints for client configuration
• Dynamic Client Registration - RFC 7591 compliant client registration
• JWKS Support - Public key endpoint for JWT validation

Architecture

Core Components

UserSSOOAuthProvider

• Main OAuth provider implementing authorization code flow
• Handles both Google SSO and Basic Auth flows
• Token generation, validation, and refresh logic
• PKCE challenge/verifier validation with timing-safe comparison

OAuthHttpStatelessServerTransportProvider

• HTTP transport layer for OAuth endpoints
• Routes authorization, token, and discovery requests
• Servlet-based stateless request handling
• Provider-aware OAuth scope configuration

SecurityConfigurationManager

• Singleton manager for runtime security configuration (authentication, authorization, MCP settings)
• Database-first configuration loading with YAML fallback
• Configuration change listener pattern for reactive updates
• Cluster-aware polling mechanism (10-second interval) to detect changes across instances
• Rollback mechanism for failed configuration updates
• Thread-safe synchronized getters for consistent configuration reads

OAuth Repositories

• OAuthClientRepository - Client management and validation
• OAuthAuthorizationCodeRepository - Authorization code CRUD operations
• OAuthAccessTokenRepository - Access token lifecycle management
• OAuthRefreshTokenRepository - Refresh token rotation and cleanup
• McpPendingAuthRequestRepository - Database-backed OAuth state persistence
• OAuthAuditLogRepository - Comprehensive audit trail

Database Schema

Five core OAuth tables with audit logging:

• oauth_clients - Dynamically registered MCP clients via RFC 7591
• oauth_authorization_codes - Short-lived codes (10 min TTL) with PKCE challenge
• oauth_access_tokens - JWT access tokens (1 hour TTL) with encryption
• oauth_refresh_tokens - Refresh tokens (7 days TTL) with automatic rotation
• mcp_pending_auth_requests - OAuth state parameters for cross-domain redirects (10 min TTL)
• oauth_audit_log - Comprehensive audit trail of all OAuth operations

Cleanup Job: OAuthTokenCleanupJob runs every 10 minutes to purge expired tokens and pending requests.

OAuth Flow

Authorization Code Flow with PKCE

┌─────────────┐                                                    ┌──────────────┐
│   Claude    │                                                    │ OpenMetadata │
│   Desktop   │                                                    │     MCP      │
│ (MCP Client)│                                                    │    Server    │
└──────┬──────┘                                                    └──────┬───────┘
       │                                                                  │
       │  1. Generate PKCE code_verifier (random 43-128 chars)           │
       │     Calculate code_challenge = BASE64URL(SHA256(verifier))      │
       │                                                                  │
       │  2. GET /api/v1/mcp/authorize                                   │
       │     ?client_id={registered_client_id}                          │
       │     &redirect_uri=http://127.0.0.1:XXXXX/callback              │
       │     &code_challenge={challenge}                                 │
       │     &code_challenge_method=S256                                 │
       │     &state={client_state}                                       │
       │─────────────────────────────────────────────────────────────────>│
       │                                                                  │
       │                        3. Store OAuth state in database:        │
       │                           - client_id, redirect_uri             │
       │                           - code_challenge, method              │
       │                           - state, scopes, TTL (10 min)         │
       │                           Generate authRequestId                │
       │                                                                  │
       │  4. 302 Redirect to Auth Page                                   │
       │     /api/v1/mcp/authorize?state=mcp:{authRequestId}            │
       │<─────────────────────────────────────────────────────────────────│
       │                                                                  │
       │  5. User authenticates via:                                     │
       │     ┌──────────────────────────────────────┐                    │
       │     │  Option A: SSO Provider              │                    │
       │     │  - Redirect to SSO provider:         │                    │
       │     │    • Google OAuth                    │                    │
       │     │    • Okta                            │                    │
       │     │    • Azure AD                        │                    │
       │     │    • Auth0                           │                    │
       │     │    • AWS Cognito                     │                    │
       │     │    • Custom OIDC                     │                    │
       │     │    • LDAP                            │                    │
       │     │    • SAML                            │                    │
       │     │  - User grants consent               │                    │
       │     │  - SSO callback with ID token (pac4j)│                    │
       │     └──────────────────────────────────────┘                    │
       │                  OR                                              │
       │     ┌─────────────────────────────┐                             │
       │     │  Option B: Basic Auth       │                             │
       │     │  - Username/password form   │                             │
       │     │  - Validate with            │                             │
       │     │    OpenMetadata             │                             │