Auth & Security

Every gateway on the shared HTTP server sits behind the same security middleware. CloudEvents is documented here under Connectors; the AI gateways — A2A and MCP — are documented under Aiway, but they run on the same server and inherit this identical security model. The authentication, CORS, origin-validation, and TLS rules described here apply uniformly to /a2a/*, /mcp, and /ce/*; each gateway's own auth guide simply points back to this page.

How requests are secured

A request crosses three security stages before it reaches the broker: TLS terminates the transport, CORS and origin validation screen browser callers, and the auth middleware verifies the Bearer token and attaches identity claims. Public routes skip authentication entirely.

Transport security, browser screening, and JWT auth guard every connector request.

Authentication

The auth middleware extracts a Bearer token from the Authorization header and verifies it against KubeMQ's authentication singleton. On success it attaches the caller's claims (including ClientID) to the request context, where the connector and the broker use them for authorization and identity propagation.

When server authentication is disabled, the middleware injects synthetic anonymous claims (ClientID: "anonymous") so requests still carry an identity. When it is enabled, an unverified or missing token is rejected.

curl -X POST http://localhost:9090/mcp \
  -H 'Authorization: Bearer <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'

How auth failures are reported

The error shape depends on the endpoint family. JSON-RPC connectors return a protocol error object; the REST-style CloudEvents endpoints return a standard HTTP status.

Public routes

A small set of routes bypass authentication entirely so health probes and agent discovery work without credentials:

CORS

Browser-based callers are governed by the connectors' CORS configuration on Connectors.Http.Cors. The defaults are permissive on origin but explicit about the headers connectors need — in particular the MCP session/protocol headers and the CloudEvents replay header.

A browser preflight is answered by the CORS middleware before the request reaches the connector:

curl -i -X OPTIONS http://localhost:9090/mcp \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: Authorization, MCP-Session-Id'

Origin validation

In addition to CORS, browser requests are checked by origin validation against a list of trusted origins. This is independent of CORS and guards against cross-site request forgery from untrusted pages.

An empty Origin header — which non-browser clients such as curl, SDKs, and server-to-server calls send — is always allowed. MCP applies its own origin check (McpConfig.TrustedOrigins) in addition to the shared HTTP origin middleware; A2A uses A2aConfig.TrustedOrigins. Both default to ["auto"].

TLS and mTLS

Transport security is read from the server's SecurityConfig and applies to the shared HTTP listener that fronts every connector. Three modes are supported:

Reserved channel prefix

Channel-name validation rejects any user channel beginning with the reserved _AGENTS_. prefix. This prefix is owned by the agent platform's internal channels (registry, streaming, discovery); rejecting it prevents user operations from colliding with platform traffic. Attempting to send to or subscribe on such a channel through any connector is refused.

Related