Summary

Add a configuration option that requires all authenticated users to exist in the database, providing operators with stricter control over authentication behavior in high-security deployments.

Related Issues

• Depends on: [SECURITY]: Enhanced JWT Token Lifecycle Management #2127 (Enhanced JWT Token Lifecycle Management)

Motivation

The gateway includes a platform admin bootstrap mechanism that allows authentication when the user doesn't exist in the database (if the token's sub claim matches PLATFORM_ADMIN_EMAIL). This is useful for:

• Fresh deployments before any users are created
• Disaster recovery scenarios
• Development and testing

However, some production environments with established user bases may prefer to disable this mechanism entirely, requiring all users to exist in the database.

Proposed Changes

Add REQUIRE_USER_IN_DB Setting

File: mcpgateway/config.py

require_user_in_db: bool = Field(
    default=False,
    description=(
        "Require all authenticated users to exist in the database. "
        "When true, disables the platform admin bootstrap mechanism. "
        "WARNING: Enabling this on a fresh deployment will lock you out."
    )
)

Modify Authentication Logic

File: mcpgateway/auth.py (around line 844)

if user is None:
    # Check if strict user-in-DB mode is enabled
    if settings.require_user_in_db:
        logger.warning(
            f"Authentication rejected for {email}: user not found in database. "
            "REQUIRE_USER_IN_DB is enabled.",
            extra={"security_event": "user_not_in_db_rejected", "user_id": email}
        )
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="User not found in database",
            headers={"WWW-Authenticate": "Bearer"},
        )

    # Platform admin bootstrap (only when REQUIRE_USER_IN_DB=false)
    if email == getattr(settings, "platform_admin_email", "admin@example.com"):
        logger.info(
            f"Platform admin bootstrap authentication for {email}.",
            extra={"security_event": "platform_admin_bootstrap", "user_id": email}
        )
        user = EmailUser(...)

Add Startup Warning

File: mcpgateway/main.py (in validate_security_configuration())

# Warn about ephemeral storage without strict mode
if not getattr(settings, "require_user_in_db", False):
    is_ephemeral = (
        ":memory:" in settings.database_url or
        settings.database_url == "sqlite:///./mcp.db"
    )
    if is_ephemeral:
        logger.warning(
            "Using potentially ephemeral storage with platform admin bootstrap enabled. "
            "Consider using persistent storage or setting REQUIRE_USER_IN_DB=true for production."
        )

Implementation Checklist

• Add require_user_in_db setting to config.py
• Modify get_current_user() in auth.py to check the setting
• Add startup warning for ephemeral storage configurations
• Write unit tests for new behavior
• Update API documentation
• Update .env.example with new configuration option
• Add documentation section on deployment security considerations

Configuration

New environment variable:

Backwards Compatibility

• Default behavior unchanged: REQUIRE_USER_IN_DB=false by default
• Opt-in strict mode: Operators explicitly enable when ready
• Clear warning: Documentation emphasizes this will lock out platform admin on fresh deployments

Use Cases

Documentation Updates

• Add section on deployment security modes
• Document REQUIRE_USER_IN_DB in configuration reference
• Add migration guide for enabling strict mode
• Update deployment checklist with security considerations

Labels

enhancement, authentication, configuration