Repository navigation
hopin's client exchanges an agent's token for the speech audience, and Mozart and Leonardo join the speech service group #301
Description
hopin's client may exchange an agent's token for one the speech service admits, and Mozart and Leonardo may use the speech service.
Caller
overnightworks/hopin#630, slice S1 (the sponsor's agent hears): its only outside blocker on the realm side (hopin's head, 12.11.2026). The operator, 12.11.2026, platform chat, after Leonardo answered him in a hopin call in writing only, to the question whether to take up a voice for the agents: „ja klar! das solle schnell gehen!“.
Ruled
- Agents join a call as participants hopin#555, line 3 (the operator, 09.11.2026): the agent hears and speaks under its own account, which hopin's server exchanges at Keycloak for a token of its own client with the speech audience.
- Today's word covers both agents he runs, Mozart and Leonardo.
Decision of platform's head, open to the operator's no before landing
Keycloak's standard token exchange lets a client exchange only a token that names that client in its audience. So the scope mcp-hopin gains a second audience, hopin, beside the MCP URL. Consequence, named: every token asked with mcp-hopin then carries it, a person's own agent through the public client agents included, so hopin's client could exchange such a token too; the speech service still admits the result only for a subject in /services/speech-service and /apps/hopin. Alternative weighed: a separate scope only the two agent clients may ask for (a second scope to keep in step with hopin's MCP check, for a narrowing the speech group already gives).
The operator, 12.11.2026 (line 1 below, option B): the speech service alone decides on the group, by its own check of /services/speech-service in the token; Keycloak bounds only who may exchange (hopin alone, a token naming hopin, the realm's scopes, an expiry no later than the subject token's) and grants no role, scope mapping or other marker for the group, so a person's token at every client is unchanged.
What it builds
infrastructure/keycloak/realm.yaml: the clienthopincarriesstandard.token.exchange.enabled: "true", and no other client does;mcp-hopingains the audience mapper forhopin; the service accounts ofagent-mozartandagent-leonardojoin/services/speech-service(they hold/apps/hopinalready).- The cell, in
cluster's P2 part (extendtests/keycloak/agent_client_tokens_and_groups.shor a sibling named for what it proves), for both agents, printing names and outcomes only: hopin's client exchanges the agent'smcp-hopintoken withscope=speech-service-audienceand getsazphopin, the agent's ownsub,audspeech-service, the agent's groups with/apps/hopinand/services/speech-service, and an expiry no later than a second after the subject token's (never asserted equal); an agent token asked withoutmcp-hopinis refused; another confidential client's exchange of the same token (presentator's) is refused; a person's token is unchanged by this. - The P2 cell's audience assertion follows (the token's audiences are the MCP URL and
hopin), and it reads the scope's mappers by name, not by position;AGENT_GROUPSinci.ymlfollows; the cell runs for both agents. - For platform carries the fleet document set: AGENTS.md within its budget, an architecture overview and runbooks #134: the sentence that an agent's
mcp-hopintoken carries one audience becomes false.
Not in this item
hopin's hearing and voice (hopin#630), its settings in apps/hopin/hopin.yaml, the persona files' voice section and the privacy texts (the speech section, the paragraph on our own agents, hopin's own text), which change with the slice that lets an agent hear, on the operator's wording.
Risk
Material: who reaches the speech service, which processes voice. Until hopin ships its hearing nobody calls the exchange. A wrong mapper would break the agents' sign-in at hopin's MCP; the P2 cell proves it stays. Rollback: revert; config-cli's no-delete leaves a removed attribute or membership in Keycloak, so the revert's pull request names the kcadm step that takes them out.
Done when
cluster is green with the cell for both agents, config-cli's Job completed on the PC, and hopin's head confirms the exchange from hopin's side with its S1.
version = 1
now = "PR #505 is ready to land at 8986436 (option B): review and gate approve, cluster green with every part inside its cap (run 43310944668). hopin's main pins webauth 0.38.0; its latest release v2026.11.13.1 still carries 0.37.0."
next = "hopin releases with webauth 0.38.0 and the platform runs it; then land #505 at its tip and tell hopin's head and personas."
done_when = "cluster is green with the exchange cell for both agents, config-cli's Job completed on the PC, and hopin's head confirms the exchange from hopin's side with its S1."
scope = [".github/workflows/ci.yml", "infrastructure/keycloak/realm.yaml", "tests/keycloak"]
size = "M"
whole = "The realm change and the cells that pin its tokens change together, or the P2 part is red."
[[expectation]]
text = "Keycloak cannot keep both ruled sentences of this item at once: the group condition on the speech audience, and a person's token unchanged."
asked_on = 2026-11-12
ruling = "B"
ruled_on = 2026-11-12
card_hash = "sha256:197012d7ab4841f7a520e78ac60d1aacb8a1cd70a7e8275bab73d097e464b8f7"
via = "chat"
question = "Darf die Anmeldung von Mitgliedern der Sprachdienst-Gruppe ein Rollen-Kennzeichen mehr tragen, damit Keycloak die Gruppe prüft?"
problem = "Beide Regeln zusammen gehen in Keycloak nicht: Gruppenprüfung für die Stimme und unveränderte Anmeldung von Personen."
decision_kind = "access"
area = "Anmeldung"
topic = "Stimme der Agenten"
recommended = "A"
reason = "Auf einem Wegwerf-Keycloak 26.8.2 nachgestellt: Mit einer Realm-Rolle bleibt bei Mitgliedern die Liste der Empfänger unverändert, nur das Rollen-Kennzeichen kommt dazu. Wer nicht in der Gruppe ist, bekommt den Sprachdienst nicht. Jeder andere gefundene Weg schreibt die Anmeldung aller Personen um oder hebt die Gruppenprüfung auf. Deine Entscheidung vom 9.11. verlangt, dass Keycloak selbst die Gruppe prüft."
[[expectation.option]]
name = "Kennzeichen zulassen"
effect = "Die Gruppenprüfung bleibt in Keycloak. Wer in der Sprachdienst-Gruppe ist, trägt bei jeder App ein zusätzliches Rollen-Kennzeichen in seiner Anmeldung, keinen neuen Empfänger."
notice = "Du merkst nichts. Mozart und Leonardo sprechen, andere Programme bekommen die Stimme nicht."
cost = "Ein Satz der Regel wird gelockert: die Anmeldung von Gruppenmitgliedern ändert sich um ein Kennzeichen. Kein Mehraufwand."
undo = "reversible"
undo_how = "Die Rolle aus der Realm-Datei entfernen; eine neue Anmeldung trägt sie nicht mehr."
contract = "realm.yaml: realm role speech-service-user, granted to /services/speech-service, role scope mapping on speech-service-audience with Audience Resolve (tip e45f764). The ruled sentence 'a person's token is unchanged' becomes 'a person's token keeps its audiences and resource_access; a member of /services/speech-service carries the realm role speech-service-user'. The cell adds a member person and asserts that."
[[expectation.option]]
name = "Sprachdienst prüft Gruppe"
effect = "Keycloak tauscht für jeden Agenten von hopin. Ob jemand in der Gruppe ist, prüft der Sprachdienst selbst an der Gruppenliste im Token."
notice = "Du merkst nichts. Die Anmeldung von Personen bleibt Byte für Byte gleich."
cost = "Deine Entscheidung, dass Keycloak die Gruppe prüft, wird aufgehoben; die Sicherheit hängt dann am Sprachdienst allein."
undo = "reversible"
undo_how = "Die Gruppenprüfung später wieder in Keycloak einbauen."
contract = "Drop the role scope mapping; speech-service-audience keeps its fixed audience mapper; the ruled sentence 'an exchanged scope is granted only when ... the principal is in the service's group' is replaced by speech-runtime's own service_group check; webauth#736 line 2 is ruled again."
Activity
[-]hopin's client exchanges an agent's token for one with the speech audience, and Mozart joins the speech service group[/-][+]hopin's client exchanges an agent's token for the speech audience, and Mozart and Leonardo join the speech service group[/+]The exchange cell names the scope refusal shorter
FlexOr2 commentedon Nov 12, 2026
The lane stopped at the gate with an architectural verdict (Opus high, 12.11.2026); pull request 505 is not landed and stays a draft.
The conflict. This item gives every
mcp-hopintoken two audiences, the MCP URL andhopin, because Keycloak's standard token exchange lets hopin's client exchange only a token that nameshopinin its audience, and the ruled design (hopin#555 line 3, hopin#630) exchanges the very token the agent presents at hopin's MCP. hopin's MCP gate is webauth'sBearerGate, and webauth refuses a token whose audiences are not exactly the resource:src/webauth/oidc/_relying_party.pyline 570 at v0.37.0 (hopin's pin), the same at v0.37.1 and main, pinned by its tests (RESOURCE-15 to 18, 56, 70: two audiences are a 401invalid_token). So landing this would have turned Mozart, Leonardo and every person's own agent away at hopin's/mcpwith 401. The P2 cell would not have caught it: it only asserted the two audiences and never ran the token through hopin's gate.Why no fixer can settle it. One token cannot both name
hopin(Keycloak's exchange) and name the MCP URL alone (webauth's ruled resource contract). The ways out cross repositories: webauth admits the resource plus the resource server's own client id; or the agent brings a second token for the exchange; or hopin reaches the speech audience for an agent by another grant; or the design changes. That is hopin's and webauth's heads' to weigh with this one, and a plan review, not a build.Kept from the lane: the exchange attribute on
hopinalone, both agents' membership in/services/speech-service, and the exchange cell stand on the branch and are sound apart from the audience mapper; the cell that an agent'smcp-hopintoken is still admitted must drive hopin's own gate (or webauth's verifier), not restate the audiences.FlexOr2 commentedon Nov 12, 2026
webauth's head asked (for the plan review on overnightworks/webauth#736) whether the realm can exchange a token whose only audience is the resource URL, so that the gate's exact-audience rule could stay. Read from Keycloak's source at tag 26.8.2 (the platform pins 26.8.2-1) and its token-exchange documentation; no live exchange was run.
No, not with a setting. Standard token exchange requires the requesting client's client id in the subject token's
audunless the token was issued to that client itself:StandardTokenExchangeProvider.validateAudience()(lines 232-255) callsforbiddenIfClientIsNotWithinTokenAudience(AbstractTokenExchangeProvider.java244-250), an exact string match onaud(JsonWebToken.hasAudience). The agent's token hasazpof the agent's client, soaudmust hold hopin's client id. Theaudiencerequest parameter names the target, not the subject;resourceis never read; client policies can only reject; a subject token carryingmay_actoractis refused; the legacy exchange is a preview on deprecated fine-grained permissions and documented as going away; the delegation preview keeps the same audience check.Two shapes that keep the gate's rule, both the heads' to weigh, neither built:
aud= the URL alone. Either hopin's client is renamed to that URL, or, narrower, a second confidential client whose id is the URL exists only for the exchange; then the exchanged token'sazpis that client, which the speech service's caller table would have to name. Unverified: that Keycloak 26.8.2 takes a URL as an OIDC client id, and what hopin's and speech's checks make of it.mcp-hopin(aud the URL, for the gate) and a second with a scope whose audience ishopinalone (only ever a subject token). Cost: a second token request per agent and a new field in the agents contract, which hopin's head argued against (a bearer token as an argument).Against these stands webauth admitting the resource plus the app's own client id (hopin's head's preference): one token, but a loosened ruled sentence for every app that opts in.
FlexOr2 commentedon Nov 12, 2026
Proof with a real Keycloak (a throwaway container of the pinned image
quay.io/keycloak/keycloak:26.8.2-1,start-dev, loopback only, torn down; nothing of the platform touched), 12.11.2026: a confidential client whose client id is the resource URL can do the standard token exchange on a token whose audience is that URL.https://hopin.hallucinai.de/mcp(201) and the exchange attribute.client_secret_postand byclient_secret_basicwith the id percent-encoded; the raw id in Basic auth gets 401invalid_client.audthe speech client,azpthe URL verbatim,subthe agent's own service account, the requested scope, 300 seconds; it no longer carries the URL audience.hopinwith the exchange attribute gets 403 "Client is not within the token audience"; the URL-named client exchanging a token asked without the scope gets the same 403; with the attribute off, 400 "Standard token exchange is not enabled for the requested client".Not driven: a
realm.yamlimport of such an id through config-cli, and the admin console. For the heads to weigh: the exchanged token'sazpis then the URL-named client, while the speech service asks the person token'sazpto equal the workload token's app (hopin), so either the caller table names that client or the URL-named client also brings the workload token. The proof's script stays in this session's scratch directory and is no repository artefact.FlexOr2 commentedon Nov 12, 2026
speech's head, 12.11.2026, on the URL-named exchange client: the rule that the person token's
azpequals the workload token's client is webauth's (ServiceCallerCheck.person_caller), not speech's own code. Its preference: the URL-named client also brings the workload token, so both tokens shareazpand neither webauth nor the wire changes. For the realm that would mean: the URL-named client has a service account with the realm rolespeech-workloadand the speech audience; the speech service gets one caller-table entry (an app name of one path segment other thanhopin, with that client as its workload client) and a new image; and the agents' accounts sit in/apps/<that name>and exactly/services/speech-service, while/apps/hopinno longer decides for them at the speech service. hopin then holds two client credentials. To check in the realm lane: the workload token'sclient_idequals itsazp, and itssubdiffers from the agent's. All of it waits for the plan review on overnightworks/webauth#736.FlexOr2 commentedon Nov 12, 2026
For the slice that lets an agent hear (speech's head, 12.11.2026):
SPEECH_MAX_HEARING_SESSIONSdefaults to 1 and hopin and presentator share it; a second live hearing at the same time is refused as busy. Raising it is a setting ofapps/speech-runtime, but each session decodes on the same CPU (one recording about 1.5 s alone, 4 to 5 s while two voices speak, measured on the shared machine), so more sessions mean slower transcripts, not more capacity. To decide with numbers from the PC before agents hear in calls. Also: speech's caller table holds[apps.personas]with the workload clientpersonason its main (speech#306), shipping with its next image; the platform creates no such client until personas pulls a feature that needs it.FlexOr2 commentedon Nov 12, 2026
Ruled. webauth's head, 12.11.2026: the operator ruled on overnightworks/webauth#736 (line 3, option A) that the protected resource admits, as an opt-in per app, a token whose audiences are its URL alone or exactly its URL and the app's own client id; and (line 2) that the service's group decides who may use a service, apps exchange when acting for a principal, and a service's own door for agents is built at its first direct caller. So the realm carries what this item's body says (the client
hopinas second audience onmcp-hopin, the exchange attribute onhopinalone, both agents in/services/speech-service), not the URL-named second client; the proof with the real Keycloak decided the comparison.Conditions for this lane, which stays stopped until then (pull request 505 is a draft):
/mcp. First the hopin pin, then this. The mapper sits onmcp-hopinalone; skat's and every other MCP scope keep one audience.access_deniedfor a client outside the audience),expires_in, and that an exchanged scope is granted only when the realm offers it to the app's client and the principal is in the service's group.mcp-hopintoken carries one audience changes for the opted-in app.set_enabled,sorted_listand the file-groups derivation move intotests/keycloak/admin_api.sh; the exchanged token's missing MCP audience is checked against the mapper's value read from the realm file, not againsthttps://; the assertion that the exchanged token carries noagent_nameoragent_ownergoes unless a ruled sentence asks for it; the matrix rows not driven (an expired or tampered subject token, another requested scope) are driven.Waiting for: webauth's tagged version, then hopin's release with the flag on.
FlexOr2 commentedon Nov 12, 2026
The operator asked webauth's head (chat, 12.11.2026) why Keycloak's experimental resource-indicators feature is not used: „wenn sie experimentell ist, heißt sie ist ja da? warum nutzen wir sie dann nicht?“. Driven live on a throwaway container of the pinned image
quay.io/keycloak/keycloak:26.8.2-1with--features=resource-indicators, torn down, nothing of the platform touched: it does not help, and it makes the ruled shape impossible while a token is bound to a resource.Profile.java: experimental;ResourceIndicatorsPostProcessor.java; the MCP guide): it validates aresourcerequest parameter at the token endpoint and then replaces the token'saudwith that one URL. A client's attributeresource_urlmodels the MCP server. Nothing in it touches token exchange.hopincarryingresource_urland the exchange attribute, an agent's token whose only custom audience is the MCP URL (asked withresource, or through an audience mapper): hopin's exchange gets 403access_denied, "Client is not within the token audience", in every form tried (plain, withresource, withaudience): 12 of 12.resourceloses every other audience,hopinincluded, so a token that could be exchanged with the feature off (200) cannot with it on (403).hopininaud, asked withoutresource, is exchanged with 200, feature on or off.So the exchange needs the exchanging client's own client id in the subject token's
aud, with or without the feature; the ruling on overnightworks/webauth#736 (the gate's opt-in for the app's own client id) stands, and the platform does not enable the feature.FlexOr2 commentedon Nov 12, 2026
webauth 0.38.0 is released (https://github.com/overnightworks/webauth/releases/tag/v0.38.0). It lets a protected resource admit a token whose audiences are its url and the app's own client (
ProtectedResource(..., admits_client_audience=True)) and exchange it at the issuer (RFC 8693).Rollout order: add hopin's client as second audience in the realm only after hopin runs 0.38.0 with
admits_client_audience=True(overnightworks/hopin#630); before that, hopin's resource refuses such a token.FlexOr2 commentedon Nov 12, 2026
webauth v0.38.0 is released (webauth head, 12.11.2026). This lane still waits for hopin to run a release on 0.38.0 with admits_client_audience=True (hopin#630), then a platform bump of hopin, then it resumes with pr 505.
FlexOr2 commentedon Nov 12, 2026
From speech's head: image v2026.11.12.2 (released 12.11.2026) carries the caller-table entry for the personas runner (app
personas, workload clientpersonas, speech#306, PR #308) as platform's head named it. It takes effect once platform deploys that image tag.The exchange cell's three switch-off refusals run as one loop over th…
The exchange cell mints an already expired subject token with a negat…
Keycloak grants no role or scope for the speech group, so the speech …
State the group check as the service's alone in the token exchange se…
FlexOr2 commentedon Nov 13, 2026
For the slice that gives the agents a voice (not this lane): personas' head, 13.11.2026: once speech's image v2026.11.12.3 is out, Leonardo's runner entry takes [agents.voice] name = "de_DE-kerstin-medium" (speech v0.12.0, personas#61 line 1 A); Mozart stays on Thorsten; no personas code needed.
FlexOr2 commentedon Nov 13, 2026
hopin release v2026.11.13.2 is out (https://github.com/overnightworks/hopin/releases/tag/v2026.11.13.2). It is the release the operator asked for: an agent hears its sponsor (S1) and speaks in a call (S4). Please roll it out.
To turn voice on, hopin needs these settings (README, Configuration):
HOPIN_SPEECH__ORIGIN: the speech service's origin (already set if the game master speaks)HOPIN_SPEECH__AUDIENCE_SCOPE:speech-service-audienceHOPIN_SPEECH__HEARING=true: the agent hears its sponsor's microphoneHOPIN_SPEECH__SPEAKING=true: the agent'sspeakplays to every seatWithout origin and audience scope, hopin refuses to start with either switch on. hopin exchanges the token an agent's own MCP request presents for the speech audience, so this issue's item (Mozart and Leonardo in the speech service group) is what makes their
speakand hearing succeed. Without it,speakanswersunavailable(logged codeno_tokenor the speech refusal).hopin runs at its release 2026.11.13.2 with the agents' hearing and s…
FlexOr2 commentedon Nov 13, 2026
Landed as b8709b2 (PR 505, merged main at e8e1489, CI green). On the PC (read-only): Flux's
keycloakKustomization applied b8709b2 and is Ready; config-cli's Job, created 06:21Z after the landing, succeeded. hopin runs 2026.11.13.2 with its speech settings (#531).Open of
done_when: hopin's head confirms the exchange from hopin's side with its S1 (asked 13.11.2026). Only a live call proves an agent hearing and speaking.FlexOr2 commentedon Nov 13, 2026
Reopened: done_when still needs hopin's confirmation from hopin's side with S1; I close it once that arrives.
FlexOr2 commentedon Nov 13, 2026
Done: hopin's head confirms S1 live on 13.11.2026. Leonardo heard the operator in a real call, and hearing runs through this exchange. Speaking (hopin's S4) does not hold yet: hopin's log shows no speak call. That is followed up between hopin's and agents' heads and is not this item's.