Expand description
§MCP Authentication and Authorization Framework
A comprehensive, drop-in security framework for Model Context Protocol (MCP) servers providing enterprise-grade authentication, authorization, session management, and security monitoring.
§Quick Start
§Simple Development Setup
ⓘ
use pulseengine_mcp_auth::integration::McpIntegrationHelper;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Quick development setup - minimal security, maximum convenience
let framework = McpIntegrationHelper::setup_development("my-server".to_string()).await?;
// Process authenticated MCP requests
let (processed_request, auth_context) = framework
.process_request(request, Some(&headers))
.await?;
Ok(())
}
§Production Setup with Admin Key
ⓘ
use pulseengine_mcp_auth::integration::McpIntegrationHelper;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Production setup with admin API key creation
let (framework, admin_key) = McpIntegrationHelper::setup_production(
"prod-server".to_string(),
Some("admin-key".to_string()),
).await?;
if let Some(key) = admin_key {
println!("Admin API Key: {}", key.secret);
// Store this key securely for initial access
}
Ok(())
}
§Environment-Based Configuration
ⓘ
use pulseengine_mcp_auth::integration::AuthFramework;
// Auto-selects appropriate security profile for environment
let framework = AuthFramework::for_environment(
"my-server".to_string(),
std::env::var("ENVIRONMENT").unwrap_or("production".to_string()),
).await?;
§Core Features
§🔐 Multi-Layer Authentication
- API Keys: Secure token-based authentication with role-based permissions
- JWT Tokens: Stateless session tokens with configurable expiration
- Session Management: Server-side session tracking with automatic cleanup
- Transport Agnostic: HTTP, WebSocket, Stdio, and custom transport support
§🛡️ Authorization & Permissions
- Role-Based Access Control (RBAC): Admin, Operator, Monitor, Device, Custom roles
- Fine-Grained Permissions: Resource and tool-level access control
- Permission Inheritance: Hierarchical permission systems
- Dynamic Permission Checking: Runtime permission validation
§🔒 Request Security
- Input Validation: Request size limits, parameter validation
- Injection Prevention: SQL, XSS, Command, and Path Traversal detection
- Request Sanitization: Automatic content cleaning and escaping
- Rate Limiting: Per-method and per-user rate controls
§🗝️ Credential Management
- Encrypted Storage: AES-GCM encryption for host credentials
- Vault Integration: Enterprise secret management (Infisical)
- Credential Rotation: Automatic credential lifecycle management
- Host Connection Data: Secure storage of IP, username, password combinations
§📊 Security Monitoring
- Real-Time Events: Authentication, authorization, and security events
- Metrics Collection: Performance and security metrics
- Alerting System: Configurable security alerts and thresholds
- Security Dashboard: Web-based monitoring interface
§Security Profiles
The framework includes 8 predefined security profiles optimized for different environments:
ⓘ
use pulseengine_mcp_auth::integration::{AuthFramework, SecurityProfile};
// Development: Minimal security, maximum convenience
let dev = AuthFramework::with_security_profile(
"dev-server".to_string(),
SecurityProfile::Development,
).await?;
// Production: Maximum security and reliability
let prod = AuthFramework::with_security_profile(
"prod-server".to_string(),
SecurityProfile::Production,
).await?;
// High Security: Compliance-ready with strict controls
let secure = AuthFramework::with_security_profile(
"secure-server".to_string(),
SecurityProfile::HighSecurity,
).await?;
// IoT Device: Lightweight for resource-constrained environments
let iot = AuthFramework::with_security_profile(
"iot-device".to_string(),
SecurityProfile::IoTDevice,
).await?;
§Authentication Examples
§Creating API Keys
ⓘ
use pulseengine_mcp_auth::models::Role;
// Create API key with specific permissions
let api_key = framework.create_api_key(
"client-app".to_string(), // Key name
Role::Operator, // Role
Some(vec![ // Custom permissions
"auth:read".to_string(),
"session:create".to_string(),
"credential:read".to_string(),
]),
Some(chrono::Utc::now() + chrono::Duration::days(30)), // Expiration
Some(vec!["192.168.1.0/24".to_string()]), // IP whitelist
).await?;
println!("API Key: {}", api_key.secret);
§Processing Authenticated Requests
ⓘ
use std::collections::HashMap;
use pulseengine_mcp_auth::integration::RequestHelper;
// Extract API key from request headers
let mut headers = HashMap::new();
headers.insert("Authorization".to_string(), format!("Bearer {}", api_key));
// Process request with authentication and security validation
match RequestHelper::process_authenticated_request(&framework, request, Some(&headers)).await {
Ok((processed_request, Some(auth_context))) => {
// Request is authenticated and validated
println!("Authenticated user: {:?}", auth_context.user_id);
// Check specific permissions
RequestHelper::validate_request_permissions(&auth_context, "tools:use")?;
// Process the request...
},
Ok((_, None)) => {
// Request is not authenticated
return Err("Authentication required".into());
},
Err(e) => {
// Security validation failed
return Err(format!("Security violation: {}", e).into());
}
}
§Credential Management Examples
§Storing Host Credentials
ⓘ
use pulseengine_mcp_auth::integration::CredentialHelper;
// Store host credentials securely (e.g., for Loxone Miniserver)
let credential_id = CredentialHelper::store_validated_credentials(
&framework,
"Loxone Miniserver".to_string(), // Credential name
"192.168.1.100".to_string(), // Host IP
Some(80), // Port
"admin".to_string(), // Username
"secure_password123".to_string(), // Password
&auth_context, // Authentication context
).await?;
println!("Stored credential: {}", credential_id);
§Retrieving Host Credentials
ⓘ
// Retrieve host credentials for connection
let (host_ip, username, password) = CredentialHelper::get_validated_credentials(
&framework,
&credential_id,
&auth_context,
).await?;
// Use credentials to connect to host system
println!("Connecting to {}@{}", username, host_ip);
// establish_connection(host_ip, username, password).await?;
§Session Management
ⓘ
use pulseengine_mcp_auth::integration::SessionHelper;
// Create session with custom duration
let session = SessionHelper::create_validated_session(
&framework,
&auth_context,
Some(chrono::Duration::hours(4))
).await?;
println!("Session ID: {}", session.session_id);
println!("JWT Token: {}", session.jwt_token.unwrap_or_default());
// Validate and refresh session if needed
let refreshed_session = SessionHelper::validate_and_refresh_session(
&framework,
&session.session_id
).await?;
§Security Monitoring
ⓘ
use pulseengine_mcp_auth::integration::MonitoringHelper;
use pulseengine_mcp_auth::monitoring::SecurityEventType;
use pulseengine_mcp_auth::security::SecuritySeverity;
// Log security events
MonitoringHelper::log_security_event(
&framework,
SecurityEventType::AuthSuccess,
SecuritySeverity::Low,
"User logged in successfully".to_string(),
Some(&auth_context),
Some({
let mut data = std::collections::HashMap::new();
data.insert("client_ip".to_string(), "192.168.1.100".to_string());
data
}),
).await;
// Get framework health status
let health = MonitoringHelper::get_health_summary(&framework).await;
for (component, status) in health {
println!("{}: {}", component, status);
}
Re-exports§
pub use config::AuthConfig;
pub use consent::manager::ConsentConfig;
pub use consent::manager::ConsentManager;
pub use consent::manager::ConsentStorage;
pub use consent::manager::MemoryConsentStorage;
pub use consent::ConsentAuditEntry;
pub use consent::ConsentError;
pub use consent::ConsentRecord;
pub use consent::ConsentStatus;
pub use consent::ConsentSummary;
pub use consent::ConsentType;
pub use consent::LegalBasis;
pub use manager::AuthenticationManager;
pub use manager::RateLimitStats;
pub use manager::RoleRateLimitConfig;
pub use manager::RoleRateLimitStats;
pub use manager::ValidationConfig;
pub use manager_vault::VaultAuthManagerError;
pub use manager_vault::VaultAuthenticationManager;
pub use manager_vault::VaultStatus;
pub use middleware::AuthExtractionError;
pub use middleware::McpAuthConfig;
pub use middleware::McpAuthMiddleware;
pub use middleware::SessionMiddleware;
pub use middleware::SessionMiddlewareConfig;
pub use middleware::SessionMiddlewareError;
pub use middleware::SessionRequestContext;
pub use models::ApiCompletenessCheck;
pub use models::ApiKey;
pub use models::AuthContext;
pub use models::AuthResult;
pub use models::KeyCreationRequest;
pub use models::KeyUsageStats;
pub use models::Role;
pub use models::SecureApiKey;
pub use monitoring::create_default_alert_rules;
pub use monitoring::AlertAction;
pub use monitoring::AlertRule;
pub use monitoring::AlertThreshold;
pub use monitoring::MonitoringError;
pub use monitoring::SecurityAlert;
pub use monitoring::SecurityDashboard;
pub use monitoring::SecurityEvent;
pub use monitoring::SecurityEventType;
pub use monitoring::SecurityMetrics;
pub use monitoring::SecurityMonitor;
pub use monitoring::SecurityMonitorConfig;
pub use monitoring::SystemHealth;
pub use performance::PerformanceConfig;
pub use performance::PerformanceResults;
pub use performance::PerformanceTest;
pub use performance::TestOperation;
pub use permissions::McpPermission;
pub use permissions::McpPermissionChecker;
pub use permissions::PermissionAction;
pub use permissions::PermissionConfig;
pub use permissions::PermissionError;
pub use permissions::PermissionRule;
pub use permissions::ResourcePermissionConfig;
pub use permissions::ToolPermissionConfig;
pub use security::InputSanitizer;
pub use security::RequestLimitsConfig;
pub use security::RequestSecurityConfig;
pub use security::RequestSecurityValidator;
pub use security::SecurityValidationError;
pub use security::SecurityViolation;
pub use session::MemorySessionStorage;
pub use session::Session;
pub use session::SessionConfig;
pub use session::SessionError;
pub use session::SessionManager;
pub use session::SessionStats;
pub use session::SessionStorage;
pub use storage::EnvironmentStorage;
pub use storage::FileStorage;
pub use storage::StorageBackend;
pub use transport::AuthExtractionResult;
pub use transport::AuthExtractor;
pub use transport::HttpAuthConfig;
pub use transport::HttpAuthExtractor;
pub use transport::StdioAuthConfig;
pub use transport::StdioAuthExtractor;
pub use transport::TransportAuthContext;
pub use transport::WebSocketAuthConfig;
pub use transport::WebSocketAuthExtractor;
pub use vault::VaultClientInfo;
pub use vault::VaultConfig;
pub use vault::VaultError;
pub use vault::VaultIntegration;
pub use vault::VaultType;
Modules§
- audit
- Comprehensive audit logging for authentication events
- config
- Authentication configuration
- consent
- Consent management system for privacy compliance
- crypto
- Cryptographic utilities for secure authentication
- jwt
- JWT token-based authentication
- manager
- Authentication manager implementation
- manager_
vault - Vault-integrated authentication manager
- middleware
- Middleware components for MCP request/response processing
- models
- Authentication models
- monitoring
- Security Monitoring and Dashboard Module
- performance
- Performance testing and benchmarking utilities
- permissions
- Permission system for MCP tools and resources
- security
- Security features for MCP request/response processing
- session
- Session Management Module
- setup
- Setup and initialization utilities
- storage
- Storage backend for authentication data
- transport
- Transport authentication integration
- validation
- Authentication validation utilities
- vault
- Vault integration for centralized secret management
Functions§
- create_
auth_ manager - Create an authentication manager with default configuration
- default_
config - Initialize default authentication configuration