Expose WebSocket HTTP headers / cookies to Auth Callout requests

[artyomb]

Proposed change

Description

I would like to request an enhancement to the NATS Server Auth Callout flow for WebSocket clients.

Currently, Auth Callout only receives information that the client provides inside the NATS CONNECT payload (connect_opts). However, in WebSocket scenarios the browser often authenticates using HttpOnly cookies, which are not accessible to JavaScript and therefore cannot be included in the CONNECT JSON (e.g. via auth_token).

This makes it impossible to reuse an existing web session (cookie-based auth) in Auth Callout without adding a proxy or changing the application’s security model.

Use case

For WebSocket connections, expose selected HTTP headers from the WebSocket upgrade request (especially Cookie, and optionally custom headers like Authorization or X-Auth-Token) to the Auth Callout request payload.

Possible implementations:

• Add a new field to the Auth Callout request, e.g.:
  • http_headers
  • websocket_headers
  • or cookies
• Or extend connect_opts to include an optional headers map (WebSocket only).
• Allow server-side filtering / allow-list of which headers are passed through for security.

---

Use Case

1. Browser app authenticates using standard HttpOnly session cookies
2. Browser connects to NATS over WebSocket
3. NATS performs Auth Callout
4. Auth Callout request contains the WebSocket cookies / headers
5. The Auth service validates the session and:
   • resolves the user / tenant / chat
   • generates a NATS User JWT
   • applies subject-level permissions (e.g. messages.<chat_id>.>)
6. NATS authorizes the connection and enforces permissions

This enables secure authentication without exposing any credentials in client-side JavaScript and without requiring a separate proxy.

---

This enhancement would significantly simplify secure browser → NATS integration while preserving best practices:

• No credentials in JS
• No proxy layer required
• No duplication of auth mechanisms
• Full support for dynamic per-user / per-tenant permissions with Auth Callout
• Works naturally with existing web authentication patterns (HttpOnly cookies)

Auth Callout already supports dynamic authorization, but today it can only use values explicitly provided in CONNECT. Applications relying on cookies cannot use it without workarounds.

---

Expose WebSocket HTTP headers/cookies in the Auth Callout request to enable seamless, cookie-based browser authentication for NATS WebSocket clients.

Contribution

No response

[caleblloyd]

This works today with the websocket.token_cookie config, it'll map a cookie to the token field

https://github.com/nats-io/nats-server/blob/714d46489b646fbf51be712f9e50139490cd7fa9/server/opts.go#L5401

websocket: {
  token_cookie: "my-cookie-name"
}