Summary

Add JTI (JWT ID) claims to all token generation paths and introduce configuration options for stricter token validation. This enhancement improves token revocation capabilities and provides operators with more control over authentication behavior in different deployment scenarios.

Motivation

Currently, tokens generated via different paths have inconsistent properties:

Tokens without JTI cannot be individually revoked, which limits operational flexibility. This enhancement standardizes JTI inclusion across all token paths.

Proposed Changes

Phase 1: Add JTI to Token Generation Helper

Modify _create_jwt_token() in mcpgateway/utils/create_jwt_token.py to always include a JTI claim:

import uuid

# In _create_jwt_token(), add after standard claims:
payload["jti"] = payload.get("jti") or str(uuid.uuid4())

Scope: This change affects all callers of the helper (CLI, SSO, etc.), providing consistent JTI support.

Phase 2: Add REQUIRE_JTI Configuration Option

Add a new setting to enforce JTI presence for stricter deployments:

# mcpgateway/config.py
require_jti: bool = Field(
    default=False,
    description="Require JTI claim in all JWT tokens for revocation support"
)

When enabled, tokens without JTI will be rejected with a clear error message.

Phase 3: Add Warning Logs for Bootstrap Authentication

Add informational logging when the platform admin bootstrap mechanism is used:

# mcpgateway/auth.py (around line 847)
if email == getattr(settings, "platform_admin_email", "admin@example.com"):
    logger.info(
        f"Platform admin bootstrap authentication for {email}. "
        "User authenticated via platform admin configuration.",
        extra={"security_event": "platform_admin_auth", "user_id": email}
    )

This provides visibility into authentication patterns without changing behavior.

Implementation Checklist

• Add import uuid to create_jwt_token.py imports
• Add JTI generation to _create_jwt_token() (covers all callers)
• Add REQUIRE_JTI setting to config.py
• Add JTI validation to verify_credentials.py when REQUIRE_JTI=true
• Add warning log when JTI is missing (when REQUIRE_JTI=false)
• Add info log for platform admin bootstrap authentication
• Write unit tests for new behavior
• Update API documentation
• Update .env.example with new configuration option

Configuration

New environment variables:

Backwards Compatibility

• Default behavior unchanged: REQUIRE_JTI=false by default, so existing tokens without JTI continue to work
• Gradual adoption: Operators can enable strict mode when ready
• No breaking changes: All existing authentication flows continue to function

Documentation Updates

• Add section on token lifecycle management
• Document REQUIRE_JTI option in configuration reference
• Add guidance on token revocation procedures

Future Enhancements (Out of Scope)

The following are noted for future consideration but not part of this issue:

• REQUIRE_USER_IN_DB setting for stricter user validation
• JTI-based revocation API endpoint
• Startup warnings for ephemeral storage configurations