Comprehensive guides and references for the OpenFrame platform
The Gateway Core Security And Websocket Proxy module is the reactive edge layer of the OpenFrame platform. It is responsible for:
Built on Spring Cloud Gateway and Spring WebFlux Security, this module acts as a policy enforcement point (PEP) and protocol-aware reverse proxy for both HTTP and WebSocket traffic.
flowchart LR
Client["Browser / Agent / External Client"] --> Gateway["Gateway Core Security And Websocket Proxy"]
subgraph security_layer["Security & Filters"]
Origin["OriginSanitizerFilter"]
AddAuth["AddAuthorizationHeaderFilter"]
JwtConfig["JWT Authentication & Issuer Resolver"]
ApiKey["ApiKeyAuthenticationFilter"]
end
subgraph ws_layer["WebSocket Routing"]
AgentWs["ToolAgentWebSocketProxyUrlFilter"]
ApiWs["ToolApiWebSocketProxyUrlFilter"]
WsService["WebSocketServiceSecurityDecorator"]
end
Gateway --> security_layer
Gateway --> ws_layer
security_layer --> Downstream["API / Tool / Stream / External Services"]
ws_layer --> Tools["Integrated Tools / NATS"]
The module is logically divided into:
flowchart TD
Start["Incoming HTTP Request"] --> OriginCheck["OriginSanitizerFilter"]
OriginCheck --> AddAuth["AddAuthorizationHeaderFilter"]
AddAuth --> ApiKeyCheck{{"Path starts with /external-api/?"}}
ApiKeyCheck -->|"Yes"| ApiKeyFilter["ApiKeyAuthenticationFilter"]
ApiKeyCheck -->|"No"| JwtAuth["JWT Resource Server"]
ApiKeyFilter --> JwtAuth
JwtAuth --> Authz["Role & Scope Authorization"]
Authz --> Forward["Forward to Downstream Service"]
WebClientConfigProvides a preconfigured WebClient.Builder with:
This ensures:
WebSocketGatewayConfigDefines WebSocket routes using Spring Cloud Gateway:
/ws/tools/agent/{toolId}/** → Agent tool WebSocket proxy/ws/tools/{toolId}/** → Tool API WebSocket proxy/ws/nats → NATS WebSocket endpointIt also decorates the default WebSocketService with a security-aware wrapper that injects JWT claim awareness into WebSocket sessions.
flowchart LR
ClientWs["Client WebSocket"] --> RouteMatch["RouteLocator"]
RouteMatch -->|"/ws/tools/agent/{toolId}"| AgentFilter["ToolAgentWebSocketProxyUrlFilter"]
RouteMatch -->|"/ws/tools/{toolId}"| ApiFilter["ToolApiWebSocketProxyUrlFilter"]
RouteMatch -->|"/ws/nats"| Nats["NATS WS URL"]
AgentFilter --> Resolver["ProxyUrlResolver"]
ApiFilter --> Resolver
Resolver --> ToolService["ToolUrlService"]
ToolService --> ToolTarget["Resolved Tool WS Endpoint"]
ToolAgentWebSocketProxyUrlFiltertoolId from /ws/tools/agent/{toolId}/...ToolApiWebSocketProxyUrlFiltertoolId from /ws/tools/{toolId}/...These filters enable dynamic, per-tool routing without hardcoding endpoints.
GatewaySecurityConfigConfigures the reactive security filter chain:
AddAuthorizationHeaderFilterROLE_ADMINROLE_AGENTSCOPE_* authorities| Path Prefix | Required Role |
|---|---|
/api/** |
ADMIN |
/tools/agent/** |
AGENT |
/ws/tools/agent/** |
AGENT |
/chat/** |
ADMIN or AGENT |
/clients/** |
AGENT |
Public paths (e.g., metrics, registration endpoints) are explicitly permitted.
JwtAuthConfigImplements dynamic issuer-based authentication:
JwtIssuerReactiveAuthenticationManagerResolverReactiveAuthenticationManager instances per issuerflowchart TD
JwtToken["Incoming JWT"] --> ExtractIssuer["Extract iss claim"]
ExtractIssuer --> CacheCheck["Issuer Managers Cache"]
CacheCheck -->|"Hit"| AuthManager["ReactiveAuthenticationManager"]
CacheCheck -->|"Miss"| BuildManager["Create Decoder & Validator"]
BuildManager --> AuthManager
AuthManager --> Validate["Signature + Claims Validation"]
IssuerUrlProviderThis enables secure multi-tenant token validation without restarting the gateway.
ApiKeyAuthenticationFilterGlobal filter applied to /external-api/**.
flowchart TD
Request["External API Request"] --> CheckHeader["X-API-Key Present?"]
CheckHeader -->|"No"| Reject401["401 UNAUTHORIZED"]
CheckHeader -->|"Yes"| Validate["ApiKeyValidationService"]
Validate -->|"Invalid"| Reject401
Validate -->|"Valid"| RateLimitCheck["RateLimitService.isAllowed"]
RateLimitCheck -->|"Denied"| Reject429["429 RATE_LIMIT_EXCEEDED"]
RateLimitCheck -->|"Allowed"| AddHeaders["Inject Rate Limit Headers"]
AddHeaders --> AddContext["Add X-API-Key-Id & X-User-Id"]
AddContext --> Forward["Forward to External API Service"]
RateLimitConstantsDefines structured log message templates for:
AddAuthorizationHeaderFilterEnsures a Bearer token is available for secured endpoints by resolving it from:
Access-Token headerauthorization query parameterIf found, it injects:
Authorization: Bearer <token>
This enables consistent JWT processing by the resource server.
OriginSanitizerFilterOrigin: null headerCorsConfigspring.cloud.gateway.globalcors.cors-configurations.[/**]CorsWebFilterProvides centralized cross-origin configuration at the gateway layer.
The gateway decorates the default WebSocketService to:
This ensures parity between HTTP and WebSocket security enforcement.
The Gateway Core Security And Websocket Proxy module sits in front of:
It ensures:
The Gateway Core Security And Websocket Proxy module is the security backbone of the OpenFrame edge layer. It combines:
By centralizing these concerns, the gateway enables downstream services to focus purely on business logic while inheriting a consistent, scalable, and secure access model.