# Auth & Security (/connectors/reference/auth-and-security)



Every gateway on the [shared HTTP server](/connectors/concepts/shared-http-server) sits
behind the same security middleware. CloudEvents is documented here under Connectors;
the AI gateways — [A2A and MCP](/aiway) — 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 [#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.

<Mermaid
  chart="`
graph LR
CALLER[&#x22;HTTP / JSON-RPC client&#x22;]
TLS[&#x22;TLS / mTLS&#x22;]
CORS[&#x22;CORS + origin check&#x22;]
AUTH[&#x22;JWT auth middleware&#x22;]
GW[&#x22;Connector gateway&#x22;]
BROKER[&#x22;Message Broker&#x22;]

CALLER --> TLS
TLS --> CORS
CORS --> AUTH
AUTH --> GW
GW --> BROKER

class CALLER client
class TLS,CORS,AUTH,GW broker
class BROKER broker
`"
/>

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

## Authentication [#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.

```bash
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 [#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.

| Endpoint                          | On auth failure                            |
| --------------------------------- | ------------------------------------------ |
| JSON-RPC (`/mcp`, `/a2a/*`)       | JSON-RPC error with code &#x2A;*`-32010`** |
| HTTP / REST (`/ce/*`, management) | **HTTP 401 Unauthorized**                  |

### Public routes [#public-routes]

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

| Route                           | Purpose                                       |
| ------------------------------- | --------------------------------------------- |
| `/ping`                         | Liveness probe                                |
| `/health`                       | Health check                                  |
| `/ready`                        | Readiness probe                               |
| `*/.well-known/agent-card.json` | Agent card discovery (platform and per-agent) |

<Callout type="info">
  The platform card `GET /.well-known/agent-card.json` and any per-agent card path
  ending in `/.well-known/agent-card.json` are public by design — A2A discovery must be
  reachable before a caller has a token.
</Callout>

## CORS [#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.

| Setting            | Default                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `AllowOrigins`     | `["*"]`                                                                                    |
| `AllowMethods`     | `GET, POST, DELETE, OPTIONS`                                                               |
| `AllowHeaders`     | `Authorization, Content-Type, MCP-Protocol-Version, MCP-Session-Id, Last-Event-ID, Accept` |
| `ExposeHeaders`    | `MCP-Session-Id, MCP-Protocol-Version`                                                     |
| `AllowCredentials` | `false`                                                                                    |
| `MaxAge`           | `86400` (preflight cache, seconds)                                                         |

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

```bash
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 [#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.

| `TrustedOrigins` value | Behavior                                                                                                                         |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `auto` (default)       | Matches localhost variants (`localhost`, `127.0.0.1`, and for MCP also `::1`, `[::1]`, `0.0.0.0`) plus the server's bind address |
| `*`                    | Allows all origins                                                                                                               |
| *(custom list)*        | Allows exactly the listed origins                                                                                                |

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 [#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:

| Mode               | Behavior                                                 |
| ------------------ | -------------------------------------------------------- |
| `SecurityModeNone` | Plain TCP listener (no TLS)                              |
| `SecurityModeTLS`  | TLS with a server certificate                            |
| `SecurityModeMTLS` | Mutual TLS — clients must present a verified certificate |

<Callout type="info">
  TLS here secures the **inbound** connection from callers to the connectors. The A2A
  gateway's **outbound** calls to agent URLs are a separate concern, controlled by
  `AgentTLSSkipVerify` — see the [A2A configuration](/aiway/a2a/configuration).
</Callout>

## Reserved channel prefix [#reserved-channel-prefix]

Channel-name validation rejects any user channel beginning with the reserved
&#x2A;*`_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 [#related]

<Cards>
  <Card title="Shared HTTP server" href="/connectors/concepts/shared-http-server" description="Port 9090, the middleware chain, and the enable model." />

  <Card title="Observability" href="/connectors/concepts/observability" description="Prometheus metrics, OpenTelemetry tracing, and the AI dashboard." />

  <Card title="A2A authentication" href="/aiway/a2a/guides/authentication" description="JWT auth, agent ownership, and caller identity for A2A." />

  <Card title="MCP authentication" href="/aiway/mcp/guides/authentication" description="JWT auth and origin validation for MCP tools." />
</Cards>