Deliver k8s groups via a scoped optional scope, not a blanket mapper

Date: 2026-07-03 Status: Accepted Decision: hl-ndh5 Deciders: Sean Brandt

Context

DCR-issued tokens carry no groups claim because the groups client scope is only a per-client default on static clients, leaving k8s RBAC unusable for DCR sessions (which the hosted k8s MCP uses via identity passthrough). The precedent for a similar DCR claim gap — engram’s email/email_verified (hl-9az6) — was solved with a blanket mapper on the basic scope. This decision goes the opposite way for groups.

Decision

Promote groups to a realm optional client scope and bundle it into the k8s route’s scopesSupported advertisement, so a DCR client requesting the k8s scopes also receives groups — only on k8s connections. groups is NOT added to the blanket basic default scope.

Rationale

• Solves the DCR RBAC gap via the same per-resource mechanism as the audience, delivering groups only when a k8s connection is made.
• Establishes the pattern Phase C (hl-05xz) reuses to re-home the blanket email mapper off the basic scope.
• Avoids widening an already-flagged least-privilege concern (the blanket basic-scope mappers apply to every realm token).

Alternatives Considered

• Bundle groups into the k8s-specific advertised optional scope (chosen): groups delivered only on k8s connections; reuses the audience mechanism; sets the Phase C pattern for re-homing email.
• Add groups to the blanket basic default scope, mirroring the email/hl-9az6 precedent (rejected): simpler and matches prior art, but every realm token would gain a groups claim regardless of resource, widening the least-privilege concern this design is narrowing.

Consequences

• Positive: k8s RBAC works for DCR sessions without widening groups exposure on unrelated tokens.
• Negative: a second claim (after the audience) now depends on the client correctly forwarding advertised scopes.
• Neutral: static clients keep groups as a per-client default and are unaffected.