# JWT Authentication Implementation

> **Implementation:** JWT authentication is provided by [oauth-mcp-proxy](https://github.com/tuannvm/oauth-mcp-proxy).
>
> **For JWT configuration, validation logic, and security details**, see the [oauth-mcp-proxy documentation](https://github.com/tuannvm/oauth-mcp-proxy#readme).

This document describes the JWT-based authentication architecture for mcp-trino server, providing secure access control at the server level.

## Overview

The mcp-trino server implements JWT Bearer token authentication with server-level request interception, ensuring **complete API protection** for all MCP methods. This approach provides security for the entire API surface, not just individual tools.

## Architecture

### Authentication Flow

{% @mermaid/diagram content="sequenceDiagram
participant Client
participant HTTPServer as HTTP Server
participant AuthHook as Auth Hook
participant MCPServer as MCP Server
participant TrinoClient as Trino Client

```
Client->>HTTPServer: POST /mcp<br/>Authorization: Bearer <jwt-token>
HTTPServer->>HTTPServer: Extract token from headers
HTTPServer->>AuthHook: OnRequestInitialization(ctx, id, message)
AuthHook->>AuthHook: Validate JWT token

alt Valid Token
    AuthHook->>AuthHook: Extract user claims<br/>(sub, preferred_username, email)
    AuthHook-->>HTTPServer: ✅ Authentication Success
    HTTPServer->>MCPServer: Process MCP Request
    MCPServer->>TrinoClient: Execute operations
    TrinoClient-->>Client: Results
else Invalid/Missing Token
    AuthHook-->>HTTPServer: ❌ Authentication Failed
    HTTPServer-->>Client: 400 Bad Request<br/>{"error": "authentication required"}
end" %}
```

**Key Flow Steps:**

1. **HTTP Request**: Client sends request with `Authorization: Bearer <jwt-token>` header
2. **Token Extraction**: Server extracts token from headers into request context
3. **Server-Level Authentication**: Authentication hook validates token before any processing
4. **Request Processing**: If authenticated, request proceeds to appropriate MCP handler

## Security Model

### Complete API Protection

* **All MCP Methods Protected**: Every API endpoint requires authentication
* **Server-Level Enforcement**: Authentication applied before method-specific processing
* **Early Termination**: Invalid requests rejected immediately
* **Context Propagation**: User information available throughout request lifecycle

### JWT Validation Features

* **Signature Verification**: Proper HMAC-SHA256 signature validation
* **Claims Validation**: Required claims checking (sub, exp, iat)
* **Token Caching**: Performance optimization with secure secret caching
* **Secure Token Logging**: JWT tokens logged as SHA256 hashes to prevent exposure
* **Mandatory JWT\_SECRET**: Server fails to start without JWT\_SECRET in HMAC mode

## Configuration

### Environment Variables

```bash
# Authentication Configuration
OAUTH_ENABLED=true        # Default: true (secure by default)
JWT_SECRET=your-secret-key      # JWT signing secret (REQUIRED - server fails without it)

# Transport Configuration
MCP_TRANSPORT=http              # Enable HTTP transport
MCP_PORT=8080                   # Server port
```

### Required JWT Claims

JWT tokens must include the following claims:

* **sub** (subject): Required user identifier
* **preferred\_username**: Username for logging and display
* **email**: User email address
* **exp** (expiration): Token expiration timestamp
* **iat** (issued at): Token issuance timestamp

## Protected API Surface

With server-level authentication, **ALL MCP methods** are protected:

* ✅ `initialize` - Session establishment
* ✅ `tools/list` - List available tools
* ✅ `tools/call` - Execute tools
* ✅ `resources/list` - List available resources
* ✅ `resources/read` - Read resources
* ✅ `prompts/list` - List available prompts
* ✅ `prompts/get` - Get prompt templates
* ✅ **All other MCP methods**

## Transport Endpoints

### Dual Endpoint Support

The server supports both modern and legacy endpoints for backward compatibility:

| Endpoint | Status               | Description                                 |
| -------- | -------------------- | ------------------------------------------- |
| `/mcp`   | ✅ **Recommended**    | Modern StreamableHTTP endpoint              |
| `/sse`   | ✅ **Legacy Support** | Backward compatibility for existing clients |

### Client Configuration

**Modern Endpoint (Recommended):**

```json
{
  "mcpServers": {
    "trino-jwt": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
      }
    }
  }
}
```

**Legacy Endpoint (Backward Compatibility):**

```json
{
  "mcpServers": {
    "trino-jwt": {
      "url": "https://your-server.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
      }
    }
  }
}
```

## Security Features

### Authentication Enforcement

* **Server-Level Security**: Authentication applied before any request processing
* **No Bypass Routes**: Every MCP method requires authentication
* **Proper Error Handling**: Clear error messages for authentication failures
* **Debug Logging**: Comprehensive logging for troubleshooting

### Token Security

* **Hash-Based Logging**: JWT tokens logged as SHA256 hashes to prevent sensitive data exposure
* **Secret Enforcement**: Server startup blocked without proper JWT\_SECRET configuration
* **Secret Caching**: Efficient JWT secret management with sync.Once pattern
* **Signature Verification**: Proper HMAC-SHA256 validation
* **Claims Validation**: Required claims verification
* **Context Management**: Secure token and user information storage

## Testing and Validation

### Authentication Testing

* **Valid Token Test**: Authenticated requests should succeed
* **Invalid Token Test**: Unauthenticated requests should be blocked
* **Missing Token Test**: Requests without tokens should be rejected
* **Malformed Token Test**: Corrupted tokens should be handled gracefully

### Expected Behavior

* ❌ **Unauthenticated requests**: Blocked with "authentication required"
* ✅ **Authenticated requests**: Allowed with proper JWT token
* 🔒 **All API methods**: Protected uniformly across the entire surface

## Migration Considerations

### From Tool-Only Middleware

If migrating from tool-specific middleware:

1. Remove tool-specific middleware configuration
2. Add server-level hooks for complete API protection
3. Test all MCP methods for proper authentication
4. Update client configurations to include authentication headers

### From SSE Transport

If migrating from Server-Sent Events:

1. Replace SSE server with StreamableHTTP server
2. Update client endpoints from `/sse` to `/mcp` (optional)
3. Maintain backward compatibility if needed
4. Test session management compatibility

## Production Considerations

### Security Requirements

* **HTTPS Required**: JWT authentication should always use HTTPS in production
* **Strong Secrets**: Use cryptographically strong JWT secrets (minimum 256 bits)
* **Mandatory Configuration**: JWT\_SECRET required for HMAC mode (server fails without it)
* **Secure Logging**: JWT tokens logged as hashes to prevent sensitive data exposure
* **Token Expiration**: Implement appropriate token lifetimes
* **Rate Limiting**: Consider adding rate limiting middleware
* **Audit Logging**: Log authentication attempts and failures

### Performance Optimizations

* **Secret Caching**: JWT secret cached for performance
* **Context Efficiency**: Minimal overhead for token validation
* **Early Termination**: Invalid requests rejected quickly
* **Session Management**: Proper MCP session handling

## Troubleshooting

### Common Issues

* **"authentication required"**: Missing or malformed Authorization header
* **"failed to parse token"**: JWT token corrupted or invalid format
* **"missing subject in token"**: JWT missing required `sub` claim
* **"unexpected signing method"**: Token signed with unsupported algorithm

### Debug Information

Enable detailed logging to see:

* Token extraction from headers
* JWT validation results (tokens logged as secure hashes)
* User authentication status
* Request processing flow
* SHA256 token hashes for debugging without exposing sensitive data

## Implementation Status

✅ **Complete JWT Implementation**

* Server-level authentication with complete API protection
* Secure JWT validation with proper signature verification
* Modern StreamableHTTP transport with backward compatibility
* Comprehensive testing framework and client integration
* Production-ready security features and error handling

The JWT authentication implementation provides robust, server-level security for the mcp-trino server with modern transport protocols and comprehensive API protection.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tuannvm.com/mcp-trino/docs/jwt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.