Feat/860 enterprise multitenancy, role-based access control, JWT revocation and SSO

.dockerignore

@@ -20,6 +20,7 @@ test/
 attic/
 *.md
 .benchmarks/
+.claude
 
 # Development environment directories
 .devcontainer/

.env.example

@@ -3,16 +3,27 @@
 #####################################
 
 # Basic Server Configuration
+APP_NAME=MCP_Gateway
 HOST=0.0.0.0
 PORT=4444
 ENVIRONMENT=development
 APP_DOMAIN=localhost
+APP_ROOT_PATH=""
+
+# Enable basic auth for docs endpoints
+DOCS_ALLOW_BASIC_AUTH=false
 
 # Database Configuration
 DATABASE_URL=sqlite:///./mcp.db
 # DATABASE_URL=postgresql://postgres:mysecretpassword@localhost:5432/mcp
 # DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp
 
+# Database Connection Pool Configuration (for performance optimization)
+# DB_POOL_SIZE=50              # Maximum number of persistent connections (default: 200, SQLite capped at 50)
+# DB_MAX_OVERFLOW=20           # Additional connections beyond pool_size (default: 10, SQLite capped at 20)
+# DB_POOL_TIMEOUT=30           # Seconds to wait for connection before timeout (default: 30)
+# DB_POOL_RECYCLE=3600         # Seconds before recreating connection (default: 3600)
+
 # Cache Configuration
 CACHE_TYPE=database
 # CACHE_TYPE=redis
@@ -39,8 +50,6 @@ PROTOCOL_VERSION=2025-03-26
 # Admin UI basic-auth credentials
 # PRODUCTION: Change these to strong, unique values!
 # Authentication Configuration
-JWT_SECRET_KEY=my-test-key
-JWT_ALGORITHM=HS256
 BASIC_AUTH_USER=admin
 BASIC_AUTH_PASSWORD=changeme
 AUTH_REQUIRED=true
@@ -52,10 +61,49 @@ JWT_SECRET_KEY=my-test-key
 # Algorithm used to sign JWTs (e.g., HS256)
 JWT_ALGORITHM=HS256
 
+# JWT Audience and Issuer claims for token validation
+# PRODUCTION: Set these to your service-specific values
+JWT_AUDIENCE=mcpgateway-api
+JWT_ISSUER=mcpgateway
+
 # Expiry time for generated JWT tokens (in minutes; e.g. 7 days)
 TOKEN_EXPIRY=10080
 REQUIRE_TOKEN_EXPIRATION=false
 
+#####################################
+# Email-Based Authentication
+#####################################
+
+# Enable email-based authentication system
+EMAIL_AUTH_ENABLED=true
+
+# Platform admin user (bootstrap from environment)
+# PRODUCTION: Change these to your actual admin credentials!
+PLATFORM_ADMIN_EMAIL=[email protected]
+PLATFORM_ADMIN_PASSWORD=changeme
+PLATFORM_ADMIN_FULL_NAME=Platform Administrator
+
+# Argon2id Password Hashing Configuration
+# Time cost (iterations) - higher = more secure but slower
+ARGON2ID_TIME_COST=3
+# Memory cost (KB) - higher = more secure but uses more RAM
+ARGON2ID_MEMORY_COST=65536
+# Parallelism (threads) - typically 1 for web apps
+ARGON2ID_PARALLELISM=1
+
+# Password Policy Configuration
+PASSWORD_MIN_LENGTH=8
+PASSWORD_REQUIRE_UPPERCASE=false
+PASSWORD_REQUIRE_LOWERCASE=false
+PASSWORD_REQUIRE_NUMBERS=false
+PASSWORD_REQUIRE_SPECIAL=false
+
+# Account Security Configuration
+# Maximum failed login attempts before account lockout
+MAX_FAILED_LOGIN_ATTEMPTS=5
+# Account lockout duration in minutes
+ACCOUNT_LOCKOUT_DURATION_MINUTES=30
+
 # MCP Client Authentication
 MCP_CLIENT_AUTH_ENABLED=true
 TRUST_PROXY_AUTH=false
@@ -65,16 +113,80 @@ PROXY_USER_HEADER=X-Authenticated-User
 # Must be a non-empty string (e.g. passphrase or random secret)
 AUTH_ENCRYPTION_SECRET=my-test-salt
 
+# OAuth Configuration
+OAUTH_REQUEST_TIMEOUT=30
+OAUTH_MAX_RETRIES=3
+
+# ==============================================================================
+# SSO (Single Sign-On) Configuration
+# ==============================================================================
+
+# Master SSO switch - enable Single Sign-On authentication
+SSO_ENABLED=false
+
+# GitHub OAuth Configuration
+SSO_GITHUB_ENABLED=false
+# SSO_GITHUB_CLIENT_ID=your-github-client-id
+# SSO_GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# Google OAuth Configuration
+SSO_GOOGLE_ENABLED=false
+# SSO_GOOGLE_CLIENT_ID=your-google-client-id.googleusercontent.com
+# SSO_GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# IBM Security Verify OIDC Configuration
+SSO_IBM_VERIFY_ENABLED=false
+# SSO_IBM_VERIFY_CLIENT_ID=your-ibm-verify-client-id
+# SSO_IBM_VERIFY_CLIENT_SECRET=your-ibm-verify-client-secret
+# SSO_IBM_VERIFY_ISSUER=https://your-tenant.verify.ibm.com/oidc/endpoint/default
+
+# Okta OIDC Configuration
+SSO_OKTA_ENABLED=false
+# SSO_OKTA_CLIENT_ID=your-okta-client-id
+# SSO_OKTA_CLIENT_SECRET=your-okta-client-secret
+# SSO_OKTA_ISSUER=https://your-okta-domain.okta.com
+
+# SSO General Settings
+SSO_AUTO_CREATE_USERS=true
+# JSON array of trusted email domains, e.g., ["example.com", "company.org"]
+SSO_TRUSTED_DOMAINS=[]
+# Keep local admin authentication when SSO is enabled
+SSO_PRESERVE_ADMIN_AUTH=true
+
+# SSO Admin Assignment Settings
+# Email domains that automatically get admin privileges, e.g., ["yourcompany.com"]
+SSO_AUTO_ADMIN_DOMAINS=[]
+# GitHub organizations whose members get admin privileges, e.g., ["your-org", "partner-org"]
+SSO_GITHUB_ADMIN_ORGS=[]
+# Google Workspace domains that get admin privileges, e.g., ["company.com"]
+SSO_GOOGLE_ADMIN_DOMAINS=[]
+# Require admin approval for new SSO registrations
+SSO_REQUIRE_ADMIN_APPROVAL=false
+
+#####################################
+# Personal Teams Configuration
+#####################################
+
+# Enable automatic personal team creation for new users
+AUTO_CREATE_PERSONAL_TEAMS=true
+
+# Personal team naming prefix
+PERSONAL_TEAM_PREFIX=personal
+
+# Team Limits
+MAX_TEAMS_PER_USER=50
+MAX_MEMBERS_PER_TEAM=100
+
+# Team Invitation Settings
+INVITATION_EXPIRY_DAYS=7
+REQUIRE_EMAIL_VERIFICATION_FOR_INVITES=true
+
 #####################################
 # Admin UI and API Toggles
 #####################################
 
 # Enable the visual Admin UI (true/false)
 # PRODUCTION: Set to false for security
-MCPGATEWAY_UI_ENABLED=true
-
-# Enable the Admin API endpoints (true/false)
-# PRODUCTION: Set to false for security
 
 # UI/Admin Feature Flags
 MCPGATEWAY_UI_ENABLED=true
@@ -143,12 +255,12 @@ CORS_ALLOW_CREDENTIALS=true
 # Environment setting (development/production) - affects security defaults
 # development: Auto-configures CORS for localhost:3000, localhost:8080, etc.
 # production: Uses APP_DOMAIN for HTTPS origins, enforces secure cookies
-ENVIRONMENT=development
+# ENVIRONMENT is already defined in Basic Server Configuration section
 
 # Domain configuration for production CORS origins
 # In production, automatically creates origins: https://APP_DOMAIN, https://app.APP_DOMAIN, https://admin.APP_DOMAIN
 # For production: set to your actual domain (e.g., mycompany.com)
-APP_DOMAIN=localhost
+# APP_DOMAIN is already defined in Basic Server Configuration section
 
 # Security settings for cookies
 # production: Automatically enables secure cookies regardless of this setting
@@ -190,7 +302,7 @@ REMOVE_SERVER_HEADERS=true
 
 # Enable HTTP Basic Auth for docs endpoints (in addition to Bearer token auth)
 # Uses the same credentials as BASIC_AUTH_USER and BASIC_AUTH_PASSWORD
-DOCS_ALLOW_BASIC_AUTH=false
+# DOCS_ALLOW_BASIC_AUTH is already defined in Basic Server Configuration section
 
 #####################################
 # Retry Config for HTTP Requests
@@ -209,32 +321,18 @@ RETRY_JITTER_MAX=0.5
 #####################################
 
 # Logging verbosity level: DEBUG, INFO, WARNING, ERROR, CRITICAL
-MCPGATEWAY_BULK_IMPORT_MAX_TOOLS=200
-MCPGATEWAY_BULK_IMPORT_RATE_LIMIT=10
-
-# Security Configuration
-SECURITY_HEADERS_ENABLED=true
-CORS_ALLOW_CREDENTIALS=true
-SECURE_COOKIES=true
-COOKIE_SAMESITE=lax
-X_FRAME_OPTIONS=DENY
-HSTS_ENABLED=true
-HSTS_MAX_AGE=31536000
-HSTS_INCLUDE_SUBDOMAINS=true
-REMOVE_SERVER_HEADERS=true
-
-# CORS Configuration
-ALLOWED_ORIGINS=["http://localhost", "http://localhost:4444"]
 
 # Logging Configuration
 LOG_LEVEL=INFO
 LOG_FORMAT=json
 LOG_TO_FILE=false
+LOG_FILEMODE=a+
+LOG_FILE=mcpgateway.log
+LOG_FOLDER=logs
 LOG_ROTATION_ENABLED=false
 LOG_MAX_SIZE_MB=1
 LOG_BACKUP_COUNT=5
-LOG_FILE=mcpgateway.log
-LOG_FOLDER=logs
+LOG_BUFFER_SIZE_MB=1.0
 
 # Transport Configuration
 TRANSPORT_TYPE=all
@@ -243,6 +341,10 @@ SSE_RETRY_TIMEOUT=5000
 SSE_KEEPALIVE_ENABLED=true
 SSE_KEEPALIVE_INTERVAL=30
 
+# Streaming HTTP Configuration
+USE_STATEFUL_SESSIONS=false
+JSON_RESPONSE_ENABLED=true
+
 # Federation Configuration
 FEDERATION_ENABLED=true
 FEDERATION_DISCOVERY=false
@@ -260,6 +362,7 @@ TOOL_TIMEOUT=60
 MAX_TOOL_RETRIES=3
 TOOL_RATE_LIMIT=100
 TOOL_CONCURRENT_LIMIT=10
+GATEWAY_TOOL_NAME_SEPARATOR=-
 
 # Prompt Configuration
 PROMPT_CACHE_SIZE=100
@@ -270,14 +373,22 @@ PROMPT_RENDER_TIMEOUT=10
 HEALTH_CHECK_INTERVAL=60
 HEALTH_CHECK_TIMEOUT=10
 UNHEALTHY_THRESHOLD=5
+GATEWAY_VALIDATION_TIMEOUT=5
 
 # OpenTelemetry Configuration
 OTEL_ENABLE_OBSERVABILITY=true
 OTEL_TRACES_EXPORTER=otlp
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 OTEL_EXPORTER_OTLP_INSECURE=true
+# OTEL_EXPORTER_OTLP_HEADERS=key1=value1,key2=value2
+# OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces
+# OTEL_EXPORTER_ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans
 OTEL_SERVICE_NAME=mcp-gateway
+# OTEL_RESOURCE_ATTRIBUTES=service.version=1.0.0,environment=production
+OTEL_BSP_MAX_QUEUE_SIZE=2048
+OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512
+OTEL_BSP_SCHEDULE_DELAY=5000
 
 # Plugin Configuration
 PLUGINS_ENABLED=false
@@ -331,7 +442,7 @@ WELL_KNOWN_CACHE_MAX_AGE=3600
 DEV_MODE=false
 RELOAD=false
 DEBUG=false
-SKIP_SSL_VERIFY=false
+# SKIP_SSL_VERIFY is already defined in Security and CORS section
 
 # Header Passthrough (WARNING: Security implications)
 ENABLE_HEADER_PASSTHROUGH=false

.github/workflows/lint.yml

@@ -70,7 +70,7 @@ jobs:
               vulture mcpgateway --min-confidence 80
 
           - id: pylint
-            setup: pip install pylint
+            setup: pip install pylint pylint-pydantic
             cmd: pylint mcpgateway --errors-only --fail-under=10
 
           - id: interrogate

.github/workflows/pytest.yml

@@ -84,7 +84,7 @@ jobs:
             --cov-fail-under=70
 
       # -----------------------------------------------------------
-      # 4️⃣  Run doctests (fail under 545 coverage)
+      # 4️⃣  Run doctests (fail under 40% coverage)
       # -----------------------------------------------------------
       - name: 📊  Doctest coverage with threshold
         run: |
@@ -93,7 +93,7 @@ jobs:
             --cov=mcpgateway \
             --cov-report=term \
             --cov-report=json:doctest-coverage.json \
-            --cov-fail-under=45 \
+            --cov-fail-under=40 \
             --tb=short
 
       # -----------------------------------------------------------

.gitignore

@@ -1,3 +1,6 @@
+*cookies*txt
+cookies*
+cookies.txt
 .claude
 mcpgateway-export*
 mutants

.pre-commit-config.yaml

@@ -368,7 +368,7 @@ repos:
         description: Verifies test files in tests/ directories start with `test_`.
         language: python
         files: (^|/)tests/.+\.py$
-        exclude: ^tests/(.*/)?(pages|helpers|fuzzers|scripts|fixtures|migration)/.*\.py$|^tests/migration/.*\.py$  # Exclude page object, helper, fuzzer, script, fixture, and migration files
+        exclude: ^tests/(.*/)?(pages|helpers|fuzzers|scripts|fixtures|migration|utils|manual)/.*\.py$|^tests/migration/.*\.py$  # Exclude page object, helper, fuzzer, script, fixture, util, manual, and migration files
         args: [--pytest-test-first] # `test_.*\.py`
 
   # - repo: https://github.com/pycqa/flake8

.pylintrc

@@ -446,9 +446,10 @@ disable=raw-checker-failed,
         too-many-lines,
         too-many-branches,
         too-many-statements,
-        too-many-public-methods
+        too-many-public-methods,
+        unsubscriptable-object
 
-# TODO: remove most of the disabled onews above
+# TODO: remove most of the disabled items above
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option

AGENTS.md

@@ -29,7 +29,7 @@
 - `make clean`: Remove caches, build artefacts, venv, coverage, docs, certs.
 
 MCP helpers
-- JWT token: `python -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret KEY`.
+- JWT token: `python -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret KEY`.
 - Expose stdio server: `python -m mcpgateway.translate --stdio "uvx mcp-server-git" --port 9000`.
 
 ## Coding Style & Naming Conventions