Skip to content

hopin's client exchanges an agent's token for the speech audience, and Mozart and Leonardo join the speech service group #301

Closed

Description

@FlexOr2

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 client hopin carries standard.token.exchange.enabled: "true", and no other client does; mcp-hopin gains the audience mapper for hopin; the service accounts of agent-mozart and agent-leonardo join /services/speech-service (they hold /apps/hopin already).
  • The cell, in cluster's P2 part (extend tests/keycloak/agent_client_tokens_and_groups.sh or a sibling named for what it proves), for both agents, printing names and outcomes only: hopin's client exchanges the agent's mcp-hopin token with scope=speech-service-audience and gets azp hopin, the agent's own sub, aud speech-service, the agent's groups with /apps/hopin and /services/speech-service, and an expiry no later than a second after the subject token's (never asserted equal); an agent token asked without mcp-hopin is 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_GROUPS in ci.yml follows; 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-hopin token 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

  1. added theissue type on Nov 9, 2026
  2. changed the title [-]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[/+] on Nov 12, 2026
  3. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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-hopin token two audiences, the MCP URL and hopin, because Keycloak's standard token exchange lets hopin's client exchange only a token that names hopin in 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's BearerGate, and webauth refuses a token whose audiences are not exactly the resource: src/webauth/oidc/_relying_party.py line 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 401 invalid_token). So landing this would have turned Mozart, Leonardo and every person's own agent away at hopin's /mcp with 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 hopin alone, 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's mcp-hopin token is still admitted must drive hopin's own gate (or webauth's verifier), not restate the audiences.

  4. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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 aud unless the token was issued to that client itself: StandardTokenExchangeProvider.validateAudience() (lines 232-255) calls forbiddenIfClientIsNotWithinTokenAudience (AbstractTokenExchangeProvider.java 244-250), an exact string match on aud (JsonWebToken.hasAudience). The agent's token has azp of the agent's client, so aud must hold hopin's client id. The audience request parameter names the target, not the subject; resource is never read; client policies can only reject; a subject token carrying may_act or act is 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:

    • The client id is the resource URL. The exact match then passes with 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's azp is 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.
    • Two tokens. The agent asks one token with mcp-hopin (aud the URL, for the gate) and a second with a scope whose audience is hopin alone (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.

  5. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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.

    • Keycloak's admin API created the client with the id https://hopin.hallucinai.de/mcp (201) and the exchange attribute.
    • An agent client's service-account token asked with a scope whose audience mapper adds only that URL was exchanged by the URL-named client with status 200, by client_secret_post and by client_secret_basic with the id percent-encoded; the raw id in Basic auth gets 401 invalid_client.
    • The exchanged token: aud the speech client, azp the URL verbatim, sub the agent's own service account, the requested scope, 300 seconds; it no longer carries the URL audience.
    • Controls: a client named hopin with 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.yaml import of such an id through config-cli, and the admin console. For the heads to weigh: the exchanged token's azp is then the URL-named client, while the speech service asks the person token's azp to 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.

  6. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    speech's head, 12.11.2026, on the URL-named exchange client: the rule that the person token's azp equals 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 share azp and neither webauth nor the wire changes. For the realm that would mean: the URL-named client has a service account with the realm role speech-workload and the speech audience; the speech service gets one caller-table entry (an app name of one path segment other than hopin, 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/hopin no longer decides for them at the speech service. hopin then holds two client credentials. To check in the realm lane: the workload token's client_id equals its azp, and its sub differs from the agent's. All of it waits for the plan review on overnightworks/webauth#736.

  7. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    For the slice that lets an agent hear (speech's head, 12.11.2026): SPEECH_MAX_HEARING_SESSIONS defaults 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 of apps/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 client personas on its main (speech#306), shipping with its next image; the platform creates no such client until personas pulls a feature that needs it.

  8. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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 hopin as second audience on mcp-hopin, the exchange attribute on hopin alone, 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):

    1. Order. The second audience lands only after hopin on the platform runs a release whose webauth has the flag on; webauth's default stays exact single audience, so the mapper earlier would turn the agents away at hopin's /mcp. First the hopin pin, then this. The mapper sits on mcp-hopin alone; skat's and every other MCP scope keep one audience.
    2. The real-issuer cell stays here: the issuer's statuses (403 access_denied for 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.
    3. 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-hopin token carries one audience changes for the opted-in app.
    4. From the stopped lane, to fix when it resumes: the helpers set_enabled, sorted_list and the file-groups derivation move into tests/keycloak/admin_api.sh; the exchanged token's missing MCP audience is checked against the mapper's value read from the realm file, not against https://; the assertion that the exchanged token carries no agent_name or agent_owner goes 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.

  9. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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-1 with --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.

    • What the feature is at this version (Profile.java: experimental; ResourceIndicatorsPostProcessor.java; the MCP guide): it validates a resource request parameter at the token endpoint and then replaces the token's aud with that one URL. A client's attribute resource_url models the MCP server. Nothing in it touches token exchange.
    • Feature on, the client hopin carrying resource_url and the exchange attribute, an agent's token whose only custom audience is the MCP URL (asked with resource, or through an audience mapper): hopin's exchange gets 403 access_denied, "Client is not within the token audience", in every form tried (plain, with resource, with audience): 12 of 12.
    • The feature narrows: a token asked with resource loses every other audience, hopin included, so a token that could be exchanged with the feature off (200) cannot with it on (403).
    • Control: a subject token that names hopin in aud, asked without resource, 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.

  10. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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.

  11. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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.

  12. FlexOr2 commented on Nov 12, 2026

    @FlexOr2
    MemberAuthor

    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 client personas, speech#306, PR #308) as platform's head named it. It takes effect once platform deploys that image tag.

  13. FlexOr2 commented on Nov 13, 2026

    @FlexOr2
    MemberAuthor

    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.

  14. FlexOr2 commented on Nov 13, 2026

    @FlexOr2
    MemberAuthor

    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-audience
    • HOPIN_SPEECH__HEARING=true: the agent hears its sponsor's microphone
    • HOPIN_SPEECH__SPEAKING=true: the agent's speak plays to every seat

    Without 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 speak and hearing succeed. Without it, speak answers unavailable (logged code no_token or the speech refusal).

  15. FlexOr2 commented on Nov 13, 2026

    @FlexOr2
    MemberAuthor

    Landed as b8709b2 (PR 505, merged main at e8e1489, CI green). On the PC (read-only): Flux's keycloak Kustomization 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.

  16. FlexOr2 commented on Nov 13, 2026

    @FlexOr2
    MemberAuthor

    Reopened: done_when still needs hopin's confirmation from hopin's side with S1; I close it once that arrives.

  17. FlexOr2 commented on Nov 13, 2026

    @FlexOr2
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions