Improve UX and documentation of M2M / OBO / human auth flows

[QuentinBisson]

Context

mcp-kubernetes PR #498 introduces the pure-projector M2M design (impersonateUser + impersonateGroups). As the config surface has grown across muster, mcp-oauth, and mcp-kubernetes, the three-way auth flow setup has become hard to discover and document coherently.

Problem

Operators configuring the full M2M or OBO flow need to wire:

1. muster — trusted issuer entry: issuer, jwksURL, allowedClaims, allowedActors (OBO) or impersonateUser / impersonateGroups (M2M)
2. mcp-oauth — ActorDelegationPolicy, GrantedSubject, audience enforcement
3. mcp-kubernetes — ImpersonateUser, ImpersonateGroups, routing vs gate semantics

The relationship between these three layers is not obvious. Specifically:

• Why AllowedClaims.sub (routing glob) exists alongside ImpersonateUser (exact gate) on the same entry
• When to use M2M vs OBO vs SSO passthrough
• What the cluster RBAC prerequisites are (prompt 04 in the M2M plan binds the group)

Proposed improvements

• Add a dedicated section to muster docs / README covering the three auth paths with a worked example per path
• Consider whether AllowedClaims.sub can be derived from ImpersonateUser for M2M entries, eliminating the redundant field (see mcp-kubernetes#498 discussion)
• Reference the mcp-oauth and mcp-kubernetes config fields by name so the connection is traceable
• Add a validation warning (or error) when an M2M entry sets both AllowedClaims.sub and ImpersonateUser to different values

Related

• mcp-kubernetes#498 (M2M projector, this branch)
• mcp-oauth (ActorDelegationPolicy, GrantedSubject)