🔐 Epic: Streamlined Authentication Model & Secure Defaults

Goal

Deliver a clear, consistent authentication model across the gateway with:

• Unified authentication for Admin UI and API endpoints
• Granular controls for different authentication methods
• Secure-by-default token validation requirements
• Session management with proper access controls

The authentication model should be intuitive for operators and provide flexibility for different deployment scenarios.

Why Now?

Authentication clarity is essential for production deployments:

1. Operator clarity: Clear separation between Admin UI login and API authentication
2. Deployment flexibility: Different environments need different auth configurations
3. Secure defaults: Production-ready settings out of the box
4. Token lifecycle: Support for token revocation and expiration requirements
5. Session management: Proper access controls for multi-user environments

📖 User Stories

Given a fresh gateway deployment
When I use default configuration
Then REQUIRE_TOKEN_EXPIRATION=true (tokens must expire)
And REQUIRE_JTI=true (tokens must have ID for revocation)
And API_ALLOW_BASIC_AUTH=false (JWT required for API)

Given API_ALLOW_BASIC_AUTH is configurable
When I set API_ALLOW_BASIC_AUTH=true in development
Then Basic auth is accepted for API endpoints

When I leave default (false) in production
Then only JWT tokens are accepted

Given Admin UI at /admin
When I access the login page
Then I use PLATFORM_ADMIN_EMAIL and PASSWORD

Given API endpoints
When I make authenticated requests
Then I use JWT Bearer tokens

Given REQUIRE_TOKEN_EXPIRATION=true (default)
When a token without exp claim is presented
Then the request is rejected

Given REQUIRE_JTI=true (default)
When a token without jti claim is presented
Then the request is rejected

Given I am a regular user
When I query /reverse-proxy/sessions
Then I see only sessions I created

Given I am an admin
When I query /reverse-proxy/sessions
Then I see all active sessions

✅ Acceptance Criteria (Epic)

• Secure defaults enabled out of the box
• Admin UI uses session-based email/password authentication
• API endpoints use JWT Bearer token authentication
• API_ALLOW_BASIC_AUTH setting controls Basic auth for API (default: false)
• REQUIRE_TOKEN_EXPIRATION enforces exp claim (default: true)
• REQUIRE_JTI enforces jti claim for revocation (default: true)
• Token revocation checks in admin middleware
• Session listings filtered by user ownership
• Proxy authentication support for reverse proxy deployments
• Documentation updated across all guides
• Test coverage for all auth scenarios

🧠 Design Notes

Authentication Methods by Endpoint

Key Configuration

# Secure defaults (all enabled by default)
REQUIRE_TOKEN_EXPIRATION=true
REQUIRE_JTI=true
API_ALLOW_BASIC_AUTH=false

# Admin UI credentials
PLATFORM_ADMIN_EMAIL=admin@example.com
PLATFORM_ADMIN_PASSWORD=changeme

# Proxy authentication (for reverse proxy deployments)
TRUST_PROXY_AUTH=false
PROXY_USER_HEADER=X-Forwarded-User

Migration Notes

Tokens: Existing tokens without jti or exp claims will be rejected. Generate new tokens:

python -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret $JWT_SECRET_KEY

Basic Auth: If you use Basic auth for API access:

1. (Recommended) Migrate to JWT tokens
2. Set API_ALLOW_BASIC_AUTH=true to restore previous behavior

🧰 Implementation Checklist

• AdminAuthMiddleware with token revocation checks
• Proxy authentication support (TRUST_PROXY_AUTH)
• Session ownership filtering
• API_ALLOW_BASIC_AUTH setting
• Token validation defaults updated
• SSO redirect validation (server-side allowlist)
• Gateway credentials scoped to local auth
• Documentation updated (25+ files)
• Test coverage added

🔗 Related

• PR feat(auth): add token revocation and proxy auth to middleware #2548: Implementation
• ADR-004: JWT and Basic Auth combination