User identity headers
Send the caller's email, ID, name and groups as plain headers to a server that can't verify a signed token
Some MCP servers, and the proxies in front of them, can read a header but can't verify a signed token.
User identity headers send the same person as the user identity assertion, as plain X-SecureAuth- headers without a signature.
Because nothing signs them, use them only where your network guarantees the request came from the gateway.
Turn them on
User identity headers build on the assertion, so turn that on first:
- On the custom server's Settings tab, switch on Send user identity under User identity.
- Under Plain headers, switch on Also send plain headers.
They're off by default, and they follow the same rules for when identity is sent: only when a person calls through an agent and has an email address on file.
The headers
| Header | Value |
|---|---|
X-SecureAuth-User-Email | The user's email address |
X-SecureAuth-User-Id | The user's ID |
X-SecureAuth-User-Name | The user's display name |
X-SecureAuth-User-Groups | The user's group names, as a JSON array such as ["eng"] |
Trust them only behind a channel check
Anyone who can reach your server directly can forge these headers.
Trust them only on requests that pass a channel check, such as a network allowlist or mutual TLS.
For example, with Cloudflare Access, check for a service token whose common_name claim is the client ID of the service token you configured on this resource.
If your server also verifies the token, compare the headers with its claims and reject a request where they differ.
A secret request header that your proxy checks is another way to make sure only the gateway's requests reach the server.
Values the gateway leaves out
The gateway leaves out a plain header whose value has control characters or exceeds 4096 bytes.
It also leaves out an email or name with non-ASCII characters, such as Józef, because many servers misread them.
Read those values from the signed token instead.
The groups header escapes non-ASCII characters as JSON \u escapes, so any JSON parser returns the exact names.
Assertion or headers
| User identity assertion | User identity headers | |
|---|---|---|
| Header | X-SecureAuth-Jwt-Assertion | X-SecureAuth-User-Email, -Id, -Name, -Groups |
| Signed | Yes, ES256 | No |
| Server needs to | Verify a JWT | Read a header |
| Safe without a channel check | Yes | No |
| Non-ASCII names | Exact | Left out (groups are escaped) |
Prefer the assertion, and add the headers only for a server or proxy that can't verify it.
Next steps
Your server or proxy can now read who each call is for from plain headers, behind a channel check that keeps them trustworthy. Next, check that only the gateway can reach the server.
- User identity assertion – the signed token, and how to verify it
- Propagate request headers – a shared secret header your proxy can require