doris-mcp-server/.env.example

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
# ===================================================================
# Doris MCP Server Environment Configuration Example
# ===================================================================
# Copy this file to .env and modify the configuration values as needed

# ===================================================================
# Database Connection Configuration
# ===================================================================

# Doris FE (Frontend) connection settings
DORIS_HOST=localhost
DORIS_PORT=9030
DORIS_USER=root
DORIS_PASSWORD=
DORIS_DATABASE=information_schema

# Doris FE HTTP API port (for Profile and other HTTP APIs)
DORIS_FE_HTTP_PORT=8030

# Doris BE (Backend) nodes configuration (optional, for external access)
# Format: host1,host2,host3 (if empty, will use "show backends" to get BE nodes)
DORIS_BE_HOSTS=
DORIS_BE_WEBSERVER_PORT=8040

# Connection pool configuration
DORIS_MAX_CONNECTIONS=20
DORIS_CONNECTION_TIMEOUT=30
DORIS_HEALTH_CHECK_INTERVAL=60
DORIS_MAX_CONNECTION_AGE=3600

# Arrow Flight SQL Configuration (Required for ADBC tools)
# FE_ARROW_FLIGHT_SQL_PORT=
# BE_ARROW_FLIGHT_SQL_PORT=

# ===================================================================
# Security Configuration
# ===================================================================

# Independent Authentication Switches - NEW DESIGN!
# Each authentication method can be enabled/disabled independently
# Any enabled method that succeeds will allow access
# If all methods are disabled, anonymous access is allowed

# Legacy configuration - kept for backward compatibility
# AUTH_TYPE is now deprecated - use individual switches above
AUTH_TYPE=token

# Token Authentication (Default method - simple and effective)
ENABLE_TOKEN_AUTH=false

# JWT Authentication (For stateless applications)
ENABLE_JWT_AUTH=false

# OAuth 2.0/OIDC Authentication (For enterprise integration)
ENABLE_OAUTH_AUTH=false

# ===================================================================
# Token Authentication Configuration (Enable with ENABLE_TOKEN_AUTH=true)
# ===================================================================

# Basic token authentication settings
TOKEN_FILE_PATH=tokens.json
ENABLE_TOKEN_EXPIRY=true
DEFAULT_TOKEN_EXPIRY_HOURS=720
TOKEN_HASH_ALGORITHM=sha256

# ===================================================================
# Token Management Security Configuration (NEW in v0.6.0) - CRITICAL SECURITY SETTINGS
# ===================================================================

# HTTP Token Management Endpoints (DISABLED BY DEFAULT FOR SECURITY)
# WARNING: These endpoints allow creation, deletion, and management of authentication tokens
# Only enable if you need HTTP-based token management and understand the security implications
ENABLE_HTTP_TOKEN_MANAGEMENT=true

# Admin Authentication Token (REQUIRED if HTTP token management is enabled)
# This token is required to access HTTP token management endpoints
# SECURITY: Generate a secure random token in production - NEVER use default values
TOKEN_MANAGEMENT_ADMIN_TOKEN=

# IP Address Restrictions for Token Management (CRITICAL SECURITY CONTROL)
# Only these IP addresses/networks can access token management endpoints
# DEFAULT: localhost only (most secure) - add other IPs/networks only if necessary
# Format: comma-separated list of IPs and CIDR networks
# Examples:
#   - Localhost only: 127.0.0.1,::1
#   - Private network: 127.0.0.1,192.168.1.0/24,10.0.0.0/8
#   - Specific IPs: 127.0.0.1,192.168.1.10,192.168.1.11
TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

# Require Admin Authentication (ENABLED BY DEFAULT FOR SECURITY)
# When true, all token management operations require valid admin token
# When false, only IP restrictions apply (NOT RECOMMENDED for production)
REQUIRE_ADMIN_AUTH=true

# ===================================================================
# JWT Authentication Configuration (Enable with ENABLE_JWT_AUTH=true)
# ===================================================================

# JWT token settings (when ENABLE_JWT_AUTH=true)
JWT_SECRET_KEY=your_jwt_secret_key_here_change_in_production
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24
JWT_ISSUER=doris-mcp-server
JWT_AUDIENCE=doris-mcp-client

# JWT token validation settings
JWT_VERIFY_SIGNATURE=true
JWT_VERIFY_EXPIRATION=true
JWT_VERIFY_AUDIENCE=true
JWT_VERIFY_ISSUER=true

# JWT refresh token settings
ENABLE_JWT_REFRESH=true
JWT_REFRESH_EXPIRATION_DAYS=30
JWT_REFRESH_SECRET_KEY=your_jwt_refresh_secret_key_here

# JWT user claims configuration
JWT_USER_ID_CLAIM=user_id
JWT_ROLES_CLAIM=roles
JWT_PERMISSIONS_CLAIM=permissions
JWT_SECURITY_LEVEL_CLAIM=security_level

# ===================================================================
# OAuth 2.0 / OpenID Connect Configuration (Enable with ENABLE_OAUTH_AUTH=true)
# ===================================================================

# OAuth provider settings (when ENABLE_OAUTH_AUTH=true)
OAUTH_PROVIDER_TYPE=generic
OAUTH_CLIENT_ID=your_oauth_client_id
OAUTH_CLIENT_SECRET=your_oauth_client_secret
OAUTH_REDIRECT_URI=http://localhost:3000/auth/callback

# OAuth endpoints (for generic provider)
OAUTH_AUTHORIZATION_URL=https://your-provider.com/auth
OAUTH_TOKEN_URL=https://your-provider.com/token
OAUTH_USERINFO_URL=https://your-provider.com/userinfo
OAUTH_JWKS_URL=https://your-provider.com/.well-known/jwks.json

# OAuth scope and claims
OAUTH_SCOPE=openid profile email
OAUTH_USER_ID_CLAIM=sub
OAUTH_USERNAME_CLAIM=preferred_username
OAUTH_EMAIL_CLAIM=email
OAUTH_ROLES_CLAIM=roles
OAUTH_GROUPS_CLAIM=groups

# OAuth session settings
OAUTH_SESSION_SECRET=your_oauth_session_secret_here
OAUTH_SESSION_EXPIRY=3600
OAUTH_STATE_EXPIRY=300

# Popular OAuth providers presets (uncomment and configure as needed)

# Google OAuth Configuration
# OAUTH_PROVIDER_TYPE=google
# OAUTH_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
# OAUTH_CLIENT_SECRET=your_google_client_secret
# OAUTH_AUTHORIZATION_URL=https://accounts.google.com/o/oauth2/auth
# OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
# OAUTH_USERINFO_URL=https://www.googleapis.com/oauth2/v1/userinfo
# OAUTH_JWKS_URL=https://www.googleapis.com/oauth2/v3/certs
# OAUTH_SCOPE=openid profile email

# Microsoft Azure AD Configuration
# OAUTH_PROVIDER_TYPE=azure
# OAUTH_CLIENT_ID=your_azure_client_id
# OAUTH_CLIENT_SECRET=your_azure_client_secret
# OAUTH_TENANT_ID=your_tenant_id
# OAUTH_AUTHORIZATION_URL=https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
# OAUTH_TOKEN_URL=https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
# OAUTH_USERINFO_URL=https://graph.microsoft.com/v1.0/me
# OAUTH_JWKS_URL=https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys
# OAUTH_SCOPE=openid profile email

# GitHub OAuth Configuration
# OAUTH_PROVIDER_TYPE=github
# OAUTH_CLIENT_ID=your_github_client_id
# OAUTH_CLIENT_SECRET=your_github_client_secret
# OAUTH_AUTHORIZATION_URL=https://github.com/login/oauth/authorize
# OAUTH_TOKEN_URL=https://github.com/login/oauth/access_token
# OAUTH_USERINFO_URL=https://api.github.com/user
# OAUTH_SCOPE=user:email

# GitLab OAuth Configuration
# OAUTH_PROVIDER_TYPE=gitlab
# OAUTH_CLIENT_ID=your_gitlab_client_id  
# OAUTH_CLIENT_SECRET=your_gitlab_client_secret
# OAUTH_AUTHORIZATION_URL=https://gitlab.com/oauth/authorize
# OAUTH_TOKEN_URL=https://gitlab.com/oauth/token
# OAUTH_USERINFO_URL=https://gitlab.com/api/v4/user
# OAUTH_SCOPE=read_user

# Keycloak OAuth Configuration
# OAUTH_PROVIDER_TYPE=keycloak
# OAUTH_CLIENT_ID=your_keycloak_client_id
# OAUTH_CLIENT_SECRET=your_keycloak_client_secret
# OAUTH_REALM=your_realm
# OAUTH_SERVER_URL=https://your-keycloak-server.com
# OAUTH_AUTHORIZATION_URL=https://your-keycloak-server.com/auth/realms/{realm}/protocol/openid-connect/auth
# OAUTH_TOKEN_URL=https://your-keycloak-server.com/auth/realms/{realm}/protocol/openid-connect/token
# OAUTH_USERINFO_URL=https://your-keycloak-server.com/auth/realms/{realm}/protocol/openid-connect/userinfo
# OAUTH_JWKS_URL=https://your-keycloak-server.com/auth/realms/{realm}/protocol/openid-connect/certs
# OAUTH_SCOPE=openid profile email

# Legacy token settings (for backward compatibility)
TOKEN_SECRET=your_secret_key_here
TOKEN_EXPIRY=3600

# SQL security check
ENABLE_SECURITY_CHECK=true

# Blocked keywords (comma separated)
BLOCKED_KEYWORDS=DROP,CREATE,ALTER,TRUNCATE,DELETE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL

# Query limits
MAX_QUERY_COMPLEXITY=100
MAX_RESULT_ROWS=10000

# Data masking
ENABLE_MASKING=true

# ===================================================================
# Performance Configuration
# ===================================================================

# Query cache
ENABLE_QUERY_CACHE=true
CACHE_TTL=300
MAX_CACHE_SIZE=1000

# Concurrency control
MAX_CONCURRENT_QUERIES=50
QUERY_TIMEOUT=300

# Response content size limit (characters)
MAX_RESPONSE_CONTENT_SIZE=4096

# ===================================================================
# ADBC (Arrow Flight SQL) Configuration
# ===================================================================
# Enable/disable ADBC tools
ADBC_ENABLED=true

# Default ADBC query parameters
ADBC_DEFAULT_MAX_ROWS=100000
ADBC_DEFAULT_TIMEOUT=60
# Format: "arrow", "pandas", "dict"
ADBC_DEFAULT_RETURN_FORMAT=arrow

# ADBC connection timeout
ADBC_CONNECTION_TIMEOUT=300

# ===================================================================
# Logging Configuration
# ===================================================================

# Basic logging configuration
LOG_LEVEL=INFO
LOG_FILE_PATH=

# Audit logging
ENABLE_AUDIT=true
AUDIT_FILE_PATH=

# Log file rotation configuration
LOG_MAX_FILE_SIZE=10485760
LOG_BACKUP_COUNT=5

# ===================================================================
# Log Cleanup Configuration - NEW!
# ===================================================================

# Enable automatic log cleanup
ENABLE_LOG_CLEANUP=true

# Maximum age of log files in days (files older than this will be deleted)
LOG_MAX_AGE_DAYS=30

# Cleanup check interval in hours
LOG_CLEANUP_INTERVAL_HOURS=24

# ===================================================================
# Monitoring Configuration
# ===================================================================

# Metrics collection
ENABLE_METRICS=true
METRICS_PORT=3001
HEALTH_CHECK_PORT=3002

# Alert configuration
ENABLE_ALERTS=false
ALERT_WEBHOOK_URL=

# ===================================================================
# Server Configuration
# ===================================================================

# Basic server information
SERVER_NAME=doris-mcp-server
SERVER_VERSION=0.6.0
SERVER_PORT=3000

# Temporary files directory
TEMP_FILES_DIR=tmp

# ===================================================================
# Configuration Examples for Different Environments
# ===================================================================

# Development Environment Example:
# LOG_LEVEL=DEBUG
# LOG_MAX_AGE_DAYS=7
# LOG_CLEANUP_INTERVAL_HOURS=6
# ENABLE_SECURITY_CHECK=false

# Production Environment Example:
# LOG_LEVEL=INFO
# LOG_MAX_AGE_DAYS=30
# LOG_CLEANUP_INTERVAL_HOURS=24
# ENABLE_SECURITY_CHECK=true
# ENABLE_LOG_CLEANUP=true

# Testing Environment Example:
# LOG_LEVEL=WARNING
# LOG_MAX_AGE_DAYS=3
# LOG_CLEANUP_INTERVAL_HOURS=1
# MAX_RESULT_ROWS=1000

# ===================================================================
# Advanced Configuration Notes
# ===================================================================

# 1. Log Cleanup Feature:
#    - ENABLE_LOG_CLEANUP: Controls whether to enable automatic cleanup
#    - LOG_MAX_AGE_DAYS: File retention days, recommended 30 days for production, 7 days for development
#    - LOG_CLEANUP_INTERVAL_HOURS: Check frequency, recommended 24 hours

# 2. Security Best Practices:
#    - NEW: Enable individual authentication methods using ENABLE_TOKEN_AUTH, ENABLE_JWT_AUTH, ENABLE_OAUTH_AUTH
#    - When all methods are disabled, ALL requests are allowed with anonymous access
#    - Authentication methods work independently - any one succeeding allows access
#    - Token Auth: Change default tokens (DEFAULT_ADMIN_TOKEN, etc.) in production
#    - JWT Auth: Change JWT_SECRET_KEY and JWT_REFRESH_SECRET_KEY in production
#    - OAuth Auth: Configure OAuth provider settings and secure client secrets
#    - Must change TOKEN_SECRET in production environment (legacy compatibility)
#    - Adjust BLOCKED_KEYWORDS according to business needs
#    - Enable ENABLE_SECURITY_CHECK and ENABLE_MASKING
#    - NEW v0.6.0: Token Management Security (CRITICAL):
#      * ENABLE_HTTP_TOKEN_MANAGEMENT=false by default (SECURE BY DEFAULT)
#      * Only enable if you need HTTP token management endpoints
#      * TOKEN_MANAGEMENT_ADMIN_TOKEN: Use secure random token in production
#      * TOKEN_MANAGEMENT_ALLOWED_IPS: Restrict to localhost (127.0.0.1,::1) only
#      * REQUIRE_ADMIN_AUTH=true: Always require admin authentication
#      * Never expose token management endpoints to external networks

# 3. Performance Tuning:
#    - Adjust MAX_CONCURRENT_QUERIES based on hardware resources
#    - Adjust QUERY_TIMEOUT based on query complexity
#    - Adjust MAX_CACHE_SIZE based on memory size

# 4. Connection Pool Optimization:
#    - DORIS_MAX_CONNECTIONS recommended to be 2-4 times the number of CPU cores
#    - DORIS_CONNECTION_TIMEOUT adjust based on network latency
#    - DORIS_MAX_CONNECTION_AGE recommended 1 hour to avoid long connection issues

# 5. ADBC (Arrow Flight SQL) Configuration:
#    - FE_ARROW_FLIGHT_SQL_PORT and BE_ARROW_FLIGHT_SQL_PORT: Required for ADBC functionality
#    - ADBC_DEFAULT_MAX_ROWS: Default maximum rows for ADBC queries (recommended: 100000)
#    - ADBC_DEFAULT_TIMEOUT: Default timeout for ADBC queries in seconds (recommended: 60)
#    - ADBC_DEFAULT_RETURN_FORMAT: Default return format (arrow/pandas/dict, recommended: arrow)
#    - ADBC_CONNECTION_TIMEOUT: Connection timeout for ADBC (recommended: 30)
#    - ADBC_ENABLED: Enable or disable ADBC tools (true/false)
#    - Prerequisites: Install adbc_driver_manager, adbc_driver_flightsql, pyarrow packages

# 6. Authentication Configuration Guide - UPDATED DESIGN!
#    
#    Independent Authentication Control (NEW):
#    - ENABLE_TOKEN_AUTH=false (default): Disable token authentication
#    - ENABLE_JWT_AUTH=false (default): Disable JWT authentication  
#    - ENABLE_OAUTH_AUTH=false (default): Disable OAuth authentication
#    - When all methods are disabled, no authentication is required (anonymous access)
#    - When multiple methods are enabled, any one succeeding allows access
#    - Recommended for development/testing: all false, production: enable needed methods
#    
#    Token Authentication (ENABLE_TOKEN_AUTH=true) - Recommended for most use cases:
#    - Simple and secure token-based authentication
#    - Configurable default tokens via environment variables
#    - Support for custom tokens via TOKEN_* environment variables
#    - Token file configuration via tokens.json
#    - Built-in token management HTTP endpoints
#    - No user management complexity - pure API access control
#    
#    JWT Authentication (ENABLE_JWT_AUTH=true) - For stateless applications:
#    - JSON Web Token based authentication
#    - Configurable token expiration and refresh
#    - Support for standard JWT claims
#    - RSA/ECDSA/HS256 algorithm support
#    - Suitable for microservices and distributed systems
#    
#    OAuth 2.0/OIDC (ENABLE_OAUTH_AUTH=true) - For enterprise integration:
#    - Integration with external identity providers
#    - Support for popular providers (Google, Microsoft, GitHub, GitLab, Keycloak)
#    - OpenID Connect compatibility
#    - Automatic user provisioning from provider
#    - Secure authorization code flow
#    
#    Authentication Method Selection Guide:
#    - No Auth (all switches false): Development, testing, trusted networks
#    - Token Auth only: Small teams, simple deployment, direct API access
#    - JWT Auth only: Stateless apps, microservices, mobile clients
#    - OAuth Auth only: Enterprise SSO, large teams, external identity providers
#    - Multiple methods: Flexible access, different client types, migration scenarios 

# 7. Token Management Security Configuration Guide (NEW in v0.6.0) - CRITICAL!
#    
#    ⚠️ SECURITY WARNING: Token management endpoints are POWERFUL and DANGEROUS
#    They allow creation, revocation, and management of authentication tokens.
#    Improper configuration can lead to complete system compromise.
#    
#    🔒 SECURE BY DEFAULT:
#    - ENABLE_HTTP_TOKEN_MANAGEMENT=false (disabled by default)
#    - REQUIRE_ADMIN_AUTH=true (admin auth required by default)  
#    - TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1 (localhost only by default)
#    
#    🛡️ SECURITY LAYERS (Applied in order):
#    1. Configuration Check: HTTP token management must be explicitly enabled
#    2. IP Restrictions: Only allowed IP addresses/networks can access endpoints
#    3. Admin Authentication: Valid admin token required for all operations
#    
#    📋 CONFIGURATION OPTIONS:
#    
#    Disable Token Management (RECOMMENDED for most deployments):
#    ENABLE_HTTP_TOKEN_MANAGEMENT=false
#    # All token management endpoints will return 403 Forbidden
#    
#    Enable with Maximum Security (Production):
#    ENABLE_HTTP_TOKEN_MANAGEMENT=true
#    TOKEN_MANAGEMENT_ADMIN_TOKEN=<secure-random-token-256-bit>
#    TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1
#    REQUIRE_ADMIN_AUTH=true
#    
#    Enable for Private Network (Advanced):
#    ENABLE_HTTP_TOKEN_MANAGEMENT=true
#    TOKEN_MANAGEMENT_ADMIN_TOKEN=<secure-random-token-256-bit>
#    TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,192.168.1.0/24,10.0.0.0/8
#    REQUIRE_ADMIN_AUTH=true
#    
#    🔑 ADMIN TOKEN GENERATION:
#    # Generate secure admin token (Linux/macOS):
#    openssl rand -hex 32
#    
#    # Generate secure admin token (Python):
#    python -c "import secrets; print(secrets.token_urlsafe(32))"
#    
#    🌐 IP CONFIGURATION EXAMPLES:
#    # Localhost only (most secure):
#    TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1
#    
#    # Private network + localhost:
#    TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1,192.168.1.0/24,10.0.0.0/8
#    
#    # Specific servers only:
#    TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,192.168.1.10,192.168.1.11
#    
#    # Corporate network (be careful):
#    TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,172.16.0.0/12,192.168.0.0/16
#    
#    🚫 NEVER DO THIS (Security Anti-Patterns):
#    # NEVER allow all IPs:
#    # TOKEN_MANAGEMENT_ALLOWED_IPS=0.0.0.0/0  # DANGEROUS!
#    
#    # NEVER disable admin auth in production:
#    # REQUIRE_ADMIN_AUTH=false  # DANGEROUS!
#    
#    # NEVER use weak admin tokens:
#    # TOKEN_MANAGEMENT_ADMIN_TOKEN=admin  # DANGEROUS!
#    # TOKEN_MANAGEMENT_ADMIN_TOKEN=123456  # DANGEROUS!
#    
#    📊 ENDPOINT SECURITY TESTING:
#    # Test security (should fail):
#    curl -X POST http://external-ip:3000/token/create
#    # Expected: 403 Forbidden (IP not allowed)
#    
#    # Test without auth (should fail):
#    curl -X POST http://127.0.0.1:3000/token/create
#    # Expected: 401 Unauthorized (missing admin token)
#    
#    # Test with valid auth (should succeed if enabled):
#    curl -H "Authorization: Bearer your-admin-token" http://127.0.0.1:3000/token/stats
#    # Expected: 200 OK with token statistics
#    
#    🔍 MONITORING & AUDITING:
#    # All token management access attempts are logged:
#    tail -f logs/doris_mcp_server_audit.log | grep "token management"
#    
#    # Monitor security events:
#    tail -f logs/doris_mcp_server_info.log | grep -E "(access denied|token management)"
#    
#    ✅ SECURITY BEST PRACTICES:
#    - Keep ENABLE_HTTP_TOKEN_MANAGEMENT=false unless absolutely necessary
#    - Use file-based token management (tokens.json) instead of HTTP endpoints
#    - Generate strong admin tokens using cryptographically secure methods
#    - Restrict access to localhost (127.0.0.1,::1) whenever possible
#    - Never expose token management endpoints to public internet
#    - Regularly audit token management access logs
#    - Use firewall rules as additional protection layer
#    - Consider VPN access for remote token management needs