Broker authentication

JWT_ENABLED defaults to false: off, the middleware stamps an empty identity into every request. On, it verifies the signature, checks the temporal claims, and compares the token’s roles against the level the route requires. One middleware, one route table: no per-queue authorization, no tenant binding, no session state.

Turn it on

Generate the secret and keep it, because minting a token needs the same bytes. Paths per Deploy a broker:

JWT_SECRET="$(openssl rand -hex 32)"; echo "$JWT_SECRET"

JWT_ENABLED=true JWT_ALGORITHM=HS256 JWT_SECRET="$JWT_SECRET" server/target/release/queen

Then read the boot log: JWT auth ENABLED carries the resolved algorithm and the skip list, and a JWKS URL adds JWKS pre-fetch OK with a key count. In the published container the binary is /app/bin/queen (the image’s default command), so the same variables travel as docker run -e flags. Configuration is read once at boot; there is no reload.

Key material matches the algorithm family: JWT_SECRET for symmetric HS256/HS384/HS512 (the default), JWT_PUBLIC_KEY (a PEM) or JWT_JWKS_URL for RS256/RS384/RS512/EdDSA, which let an identity provider hold the private key. If they disagree, the broker does not start: boot-time validation.

Algorithms and auto-detection

JWT_ALGORITHM (default HS256) does not name the algorithm the broker uses. It names the set a token may declare in its header; the broker dispatches on the token’s own alg.

RS256 is the widest RSA setting (RS384 and RS512 are exact), and auto accepts both families at once, so a deployment holding both an HS secret and an RSA public key verifies a token signed with either. Pin the algorithm unless the token really must choose. Anything outside the set is a 401 Unsupported token algorithm before any key lookup.

Where the verification key comes from

The key is chosen per token, from the token’s alg:

A static PEM always wins over JWKS, and there is no fallback from a bad PEM to the JWKS endpoint: fix the PEM or unset it.

A JWKS endpoint

Set JWT_JWKS_URL and leave JWT_PUBLIC_KEY empty: the broker pre-fetches the document at boot and caches the keys by kid.

Behaviour that matters in production:

Claim validation

Signature verification is the JWT library’s; every other check is the broker’s own, matching the older implementation exactly. The skew is JWT_CLOCK_SKEW, default 30 seconds, applied to all three temporal checks.

Access levels are a role set, not a ladder

Five levels exist and they are not ordered: the checks are role-set membership tests.

So a producer holding only write-only passes POST /api/v1/push and collects 403 Insufficient permissions on every read and consume route: pop, ack, transaction, listings, all of it. That is the intended shape for a pure producer, and the first thing to check when a client starts seeing 403s.

The route classification is prefix-based:

The last row is the important one: an unrecognised path defaults to read-write, not to public. The per-route table is the route table.

Remapping claims for an external identity provider

The role names and the claims they live in are configurable, so a token minted by an existing IdP usually needs a mapping, not custom claims. An IdP that emits {"scope":"queen.write"} needs two variables and no custom mint:

JWT_ROLES_CLAIM=scope

JWT_ROLE_WRITE_ONLY=queen.write

Both claims are read on every token, and a role counts as held if it matches the single-value claim or appears in the array claim. Both claim names are literal top-level keys, not JSON paths: a role buried in a nested object (the realm_access.roles shape, for instance) is invisible, and the issuer has to lift it into a top-level claim.

Skipping paths

JWT_SKIP_PATHS defaults to /health,/metrics/prometheus,/metrics,/. An entry matches a request path exactly; an entry longer than one character that ends in / also matches as a prefix, so /assets/ skips everything below it while / skips only the root document. Skips are evaluated before the route’s access level, so an entry here overrides the table above.

The token on the wire

The credential is read from Authorization: a Bearer prefix is stripped case-insensitively, and a bare token with no prefix is also accepted. Errors are the broker’s standard {"error":"…"} JSON shape:

Boot-time validation is fatal

When JWT_ENABLED=true, the configuration is validated before the listener binds and a failure exits the process, naming what is missing:

• HS256 or auto with none of JWT_SECRET, JWT_PUBLIC_KEY, JWT_JWKS_URL set.
• RS256, RS384, RS512 or EdDSA with neither JWT_PUBLIC_KEY nor JWT_JWKS_URL set.
• Any JWT_ALGORITHM value outside the supported list.

This is the one authentication mistake the broker refuses to start with. Everything else (a wrong secret, an unreachable JWKS endpoint, a role mapping that matches nothing) starts cleanly and fails per request, so verify with a real token against a real route before you cut traffic over.

What sits outside JWT

JWT gives one broker a per-route access level for each caller. Four properties come from elsewhere:

• Tenant separation. A valid admin token sees every queue in the broker. Separation is the tenancy header plus a gateway: multi-tenant hosting.
• Per-queue permissions. The access level is per route, not per resource.
• Revocation. No deny-list; a token is valid until exp. Keep lifetimes short, and remember exp is optional to the validator.
• Transport security. The token travels over the listener’s plaintext HTTP. See Trust boundaries.