A worker's client assertion names its certificate as both x5t#S256 and kid, its iss and sub are the identity's optional subject (the client id when absent), its jti is a random UUID, and its token is renewed five minutes before it runs out¶
Decision 978 · accepted · 2026-11-13
Decision 747 shaped a worker's private key JWT after Entra: the header named the
certificate in x5t#S256 alone, and iss and sub were the client id. Both were proven
insufficient against a live Authentik instance, which picks the signing certificate by the
header's kid and does not read x5t#S256, and which knows the system by one subject
(sys-<profile>) while each server it fronts is an application of its own with its own
client id. An assertion whose iss was the per-server client id was refused there.
- Both key headers, one value. The header carries
x5t#S256andkid, each the certificate's thumbprint (base64url of the SHA-256 of the DER certificate). Entra reads the first and Authentik the second, and each tolerates the other, so one shape serves both and no field says which provider is in use. Akidother than the thumbprint (a provider-assigned key id) is not offered: no provider in use needs one, and the thumbprint is already on the profile. - A subject distinct from the client.
spec.mcpIdentities[].subject, optional, is the assertion'sissandsub; absent, they are theclientId, so every profile written before it signs exactly as before. Theclient_idin the token request's form stays the per-server client. A subject is a non-empty string of at most 255 bytes: the resource's schema refuses one that is not, andMCPIdentity.problems/1reports it, as other broken identity fields are reported (747). It is kept as written byfrom_spec/1, so that a malformed one is reported rather than quietly replaced by the client id. Considered and not taken: derivingsys-<profile>from the profile's name, which would bind Troupe to one provider's naming and leave an installation that names its systems otherwise with no way to say so. - The console shows a subject beside the client on a profile's page; its editor has no identity fields and carries
mcpIdentities,subjectwith it, through a save as loaded. jtia random UUID, version 4, in place of 16 random bytes base64url: the shape identity providers that keepjtis for replay checks expect, and as unpredictable.- Renewed five minutes before expiry, or at three quarters of the token's life when that is sooner, in place of one minute: an hour-long token's provider asks for about five minutes' notice, and a quarter of a short life still leaves most of it used.
- Unchanged:
audthe token endpoint exactly (a provider compares it as a string, sotokenUrlis written as the provider spells it), five minutes toexp(providers refuse more than ten), signing through OpenBao transit, the transit key's naming and policy, the ConfigMap and its in-place rotation.
Proof: Troupe.Worker.ClientCredentialsTest against a fake identity provider that can
check a client as Entra does (x5t#S256, iss = sub = client) or as Authentik does
(kid, iss = sub = a subject of the client's own): the kid equals the thumbprint, a
rotation moves both, iss/sub are the client without a subject and the subject with one,
jti is a UUID v4; failing on the tip, where the header had no kid and the Authentik-style
client was refused with "iss is not the client". worker_profile_identity_test.exs for
parsing, round-trip, the default and the refusal; the operator's resources_test.exs for
the subject reaching the pod's file; the plane's admin_test.exs for the schema.
Governs: apps/troupe_worker/lib/troupe/worker/client_credentials.ex, apps/troupe_protocol/lib/troupe/worker_profile.ex, charts/troupe/crds/workerprofile.yaml, clients/gui/apps/console/src/views/Profiles.tsx