Add MCPExternalAuthConfig CRD and controller

Implement external authentication configuration for MCP servers via a new
MCPExternalAuthConfig custom resource. This enables MCP servers to exchange
incoming authentication tokens for tokens that can be used with external
services via RFC-8693 OAuth 2.0 Token Exchange.

The MCPExternalAuthConfig is namespace-scoped and can only be referenced by
MCPServers in the same namespace. The controller implements a finalizer to
prevent deletion while referenced, and uses hash-based change detection to
efficiently trigger MCPServer reconciliation when configuration changes.

Configuration is injected into MCPServer deployments via RunConfig ConfigMap
with the OAuth client secret provided through a TOOLHIVE_TOKEN_EXCHANGE_CLIENT_SECRET
environment variable that references a Kubernetes Secret, following security
best practices.

Includes comprehensive unit tests (83% coverage), integration tests, E2E
Chainsaw tests, and example manifests.

Co-Authored-By: Jakub Hrozek <[email protected]>
Co-authored-by: Claude <[email protected]>
Co-authored-by: Juan Antonio Osorio <[email protected]>
Signed-off-by: Juan Antonio Osorio <[email protected]>

Author: 3 people

cmd/thv-operator/api/v1alpha1/mcpexternalauthconfig_types.go

@@ -0,0 +1,112 @@
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// External auth configuration types
+const (
+	// ExternalAuthTypeTokenExchange is the type for RFC-8693 token exchange
+	ExternalAuthTypeTokenExchange = "tokenExchange"
+)
+
+// MCPExternalAuthConfigSpec defines the desired state of MCPExternalAuthConfig.
+// MCPExternalAuthConfig resources are namespace-scoped and can only be referenced by
+// MCPServer resources in the same namespace.
+type MCPExternalAuthConfigSpec struct {
+	// Type is the type of external authentication to configure
+	// +kubebuilder:validation:Enum=tokenExchange
+	// +kubebuilder:validation:Required
+	Type string `json:"type"`
+
+	// TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange
+	// Only used when Type is "tokenExchange"
+	// +optional
+	TokenExchange *TokenExchangeConfig `json:"tokenExchange,omitempty"`
+}
+
+// TokenExchangeConfig holds configuration for RFC-8693 OAuth 2.0 Token Exchange.
+// This configuration is used to exchange incoming authentication tokens for tokens
+// that can be used with external services.
+// The structure matches the tokenexchange.Config from pkg/auth/tokenexchange/middleware.go
+type TokenExchangeConfig struct {
+	// TokenURL is the OAuth 2.0 token endpoint URL for token exchange
+	// +kubebuilder:validation:Required
+	TokenURL string `json:"token_url"`
+
+	// ClientID is the OAuth 2.0 client identifier
+	// +kubebuilder:validation:Required
+	ClientID string `json:"client_id"`
+
+	// ClientSecretRef is a reference to a secret containing the OAuth 2.0 client secret
+	// +kubebuilder:validation:Required
+	ClientSecretRef SecretKeyRef `json:"client_secret_ref"`
+
+	// Audience is the target audience for the exchanged token
+	// +kubebuilder:validation:Required
+	Audience string `json:"audience"`
+
+	// Scope is the scope to request for the exchanged token (space-separated string)
+	// +optional
+	Scope string `json:"scope,omitempty"`
+
+	// ExternalTokenHeaderName is the name of the custom header to use for the exchanged token.
+	// If set, the exchanged token will be added to this custom header (e.g., "X-Upstream-Token").
+	// If empty or not set, the exchanged token will replace the Authorization header (default behavior).
+	// +optional
+	ExternalTokenHeaderName string `json:"external_token_header_name,omitempty"`
+}
+
+// SecretKeyRef is a reference to a key within a Secret
+type SecretKeyRef struct {
+	// Name is the name of the secret
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+
+	// Key is the key within the secret
+	// +kubebuilder:validation:Required
+	Key string `json:"key"`
+}
+
+// MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig
+type MCPExternalAuthConfigStatus struct {
+	// ObservedGeneration is the most recent generation observed for this MCPExternalAuthConfig.
+	// It corresponds to the MCPExternalAuthConfig's generation, which is updated on mutation by the API Server.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// ConfigHash is a hash of the current configuration for change detection
+	// +optional
+	ConfigHash string `json:"configHash,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:shortName=extauth;mcpextauth
+// +kubebuilder:printcolumn:name="Type",type=string,JSONPath=`.spec.type`
+// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// MCPExternalAuthConfig is the Schema for the mcpexternalauthconfigs API.
+// MCPExternalAuthConfig resources are namespace-scoped and can only be referenced by
+// MCPServer resources within the same namespace. Cross-namespace references
+// are not supported for security and isolation reasons.
+type MCPExternalAuthConfig struct {
+	metav1.TypeMeta   `json:",inline"` // nolint:revive
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   MCPExternalAuthConfigSpec   `json:"spec,omitempty"`
+	Status MCPExternalAuthConfigStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// MCPExternalAuthConfigList contains a list of MCPExternalAuthConfig
+type MCPExternalAuthConfigList struct {
+	metav1.TypeMeta `json:",inline"` // nolint:revive
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []MCPExternalAuthConfig `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&MCPExternalAuthConfig{}, &MCPExternalAuthConfigList{})
+}

cmd/thv-operator/api/v1alpha1/mcpserver_types.go

@@ -116,6 +116,11 @@ type MCPServerSpec struct {
 	// +optional
 	ToolConfigRef *ToolConfigRef `json:"toolConfigRef,omitempty"`
 
+	// ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication.
+	// The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer.
+	// +optional
+	ExternalAuthConfigRef *ExternalAuthConfigRef `json:"externalAuthConfigRef,omitempty"`
+
 	// Telemetry defines observability configuration for the MCP server
 	// +optional
 	Telemetry *TelemetryConfig `json:"telemetry,omitempty"`
@@ -480,6 +485,14 @@ type ToolConfigRef struct {
 	Name string `json:"name"`
 }
 
+// ExternalAuthConfigRef defines a reference to a MCPExternalAuthConfig resource.
+// The referenced MCPExternalAuthConfig must be in the same namespace as the MCPServer.
+type ExternalAuthConfigRef struct {
+	// Name is the name of the MCPExternalAuthConfig resource
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+}
+
 // InlineAuthzConfig contains direct authorization configuration
 type InlineAuthzConfig struct {
 	// Policies is a list of Cedar policy strings
@@ -587,6 +600,10 @@ type MCPServerStatus struct {
 	// +optional
 	ToolConfigHash string `json:"toolConfigHash,omitempty"`
 
+	// ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec
+	// +optional
+	ExternalAuthConfigHash string `json:"externalAuthConfigHash,omitempty"`
+
 	// URL is the URL where the MCP server can be accessed
 	// +optional
 	URL string `json:"url,omitempty"`