Integrate SPIFFE principals with OAuth grants and discovery

[jhrozek]

Description

Make both SPIFFE authentication methods produce equivalent OAuth behaviour:
client_credentials tokens whose subject is the workload, RFC 8693 delegation
with the workload as actor, and discovery metadata that advertises exactly the
methods actually available.

This is where the epic's central guarantee is either enforced or quietly lost.
Two credentials for the same SPIFFE ID must yield the same sub, the same
act, the same scopes, audiences, expiry and Cedar inputs. The authentication
method is an audit fact, not an authorization input.

Scope

• Make client_credentials issue tokens whose subject is the associated SPIFFE
  ID.
• Make RFC 8693 token exchange use the authenticated SPIFFE principal as
  act.sub.
• Bind an optional actor token to that same principal.
• Require explicit client authorization for both client_credentials and token
  exchange.
• Require and authorize the target MCP resource.
• Constrain requested scopes and resources by both workload policy and
  source-token authority, whichever is narrower.
• Add spiffe_x509 and spiffe_jwt to the dynamic discovery-metadata
  mechanism.
• Record the authentication method for audit without letting it change
  authorization semantics.

What belongs to other issues

This sub-issue has more external dependencies than any other, and its scope is
easy to over-draw. Three pieces are explicitly not to be built here:

• Actor-token parsing and the id_token subject type belong to Support explicit actor_token and id_token subject type in token exchange #5815.
  Require the binding to the authenticated workload principal here; do not
  re-specify the mechanism.
• Making discovery metadata dynamic at all is Token-exchange grant is unreachable: no way to provision a confidential client #6082's second blocker:
  discovery currently publishes grant_types_supported: [authorization_code, refresh_token] and token_endpoint_auth_methods_supported: ["none"], so any
  metadata-driven client refuses to attempt the grant regardless of what is
  configured. That fix is shared with the pre-provisioned-client option. Extend
  it with two method names; do not fork it.
• The external-issuer delegation-consent policy is Add a consent model for external OIDC subject tokens #6149 / Consent model for external OIDC subject tokens in multi-issuer token exchange #5989. Note that
  its allowed_delegate_clients field is optional today only because no stable
  confidential client ID can be created. SPIFFE makes the client ID equal to the
  SPIFFE ID, so this work is part of what lets that field become required — or
  better, lets the invariant be enforced from the other side, so every ID named
  must resolve to a declared client. A typo currently reverts silently to
  permissive behaviour.

Acceptance criteria

• X.509-SVID and JWT-SVID authentication for the same SPIFFE ID produce
  equivalent sub, act, scopes, audiences, expiry and Cedar inputs.
• Public clients cannot use client_credentials or token exchange.
• Token exchange is unavailable without an explicitly permitted confidential
  client association.
• An actor token, when supplied, must be bound to the authenticated workload
  principal.
• Requested scope and resource cannot exceed workload entitlement or
  source-token authorization.
• Discovery advertises exactly spiffe_x509, spiffe_jwt, or both, according
  to operational configuration — never an unavailable method.
• Existing secret-authenticated confidential clients continue to use only their
  registered grants.
• Public-only deployments' discovery metadata stays byte-identical.

Dependencies

Do not start this until the discovery-metadata and consent pieces have landed or
been explicitly claimed.

• Sub-issues 3 and 4 (both authentication methods)
• Token-exchange grant is unreachable: no way to provision a confidential client #6082 blocker 2 — dynamic discovery metadata
• Add a consent model for external OIDC subject tokens #6149 / Consent model for external OIDC subject tokens in multi-issuer token exchange #5989 — delegation consent for external subject tokens
• Support explicit actor_token and id_token subject type in token exchange #5815 — explicit actor_token and id_token subject type

Related

• Part of the SPIFFE client-authentication epic
• Embedded auth server should support RFC 8693 token exchange so agents can act on behalf of users #5194 (RFC 8693 token exchange)

[jhrozek]

While reviewing #6200's branch, we found a gap that affects this issue's acceptance criteria directly.

SPIFFEAssociationRegistry.Resolve() (pkg/authserver/spiffe_association_registry.go) correctly keeps two things separate for a wildcard /* association: the shared, operator-declared client_id (the policy handle) and the caller's own concrete SPIFFE ID (NormalizedSPIFFEPrincipal.SPIFFEID()), which is never collapsed even when many workloads match the same pattern.

The risk is downstream. The existing secret-authenticated path in pkg/authserver/server/tokenexchange/handler.go:115 does actorID := client.GetID() — correct there, because a secret-authenticated confidential client's client_id already is its identity. If this gets copied as-is for SPIFFE clients, every workload matching a wildcard association would audit and act as the same actor, since client.GetID() returns the pattern's shared client_id, not the workload's own SPIFFE ID. That defeats the reason to use SPIFFE for a dynamic fleet (e.g. ephemeral coding-agent instances) in the first place, and it would silently fail the "capture the actual actor identity" requirement from #6035.

Two concrete things this issue needs to get right:

1. act.sub (and any audit field derived from it) must be sourced from the resolved NormalizedSPIFFEPrincipal.SPIFFEID(), never from client.GetID(), whenever the client is SPIFFE-authenticated.
2. There's currently no channel for that resolved SPIFFE ID to reach the token-issuance handler at all. registration.SPIFFEClient (the fosite.Client fosite hands back to handlers) has no field for it — only client_id. Whatever authenticates the SVID will need to carry the resolved principal through fosite's request context or session, since it can't ride on the client object itself. That plumbing is this issue's job, not something Define the SPIFFE client identity, association, and configuration model #6200 could set up in advance.

Also worth noting: this issue's dependency section says "SPIFFE makes the client ID equal to the SPIFFE ID" — that's only true for an exact-match association. For a wildcard, client_id is intentionally many-to-one (the "one shared service account behind a pattern" case is a legitimate, separate use case), so this assumption should be scoped to exact associations only when this issue gets implemented.

[jhrozek]

Reuse from the spiffee-authserver branch: low to medium.

The branch made discovery metadata dynamic, which the epic credits with independently fixing the second blocker in #6082. Worth checking whether that shape survived into current main or needs redoing.

docs/spiffe-poc/future-directions.md proposes concrete field names for the draft's discovery additions, spiffe_trust_domains and spiffe_bundle_endpoint, and points at buildOAuthMetadata in the discovery handler as the place to populate them.

Two things it flags that aren't in the scope above:

spiffe_bundle_endpoint implies ToolHive serves a bundle endpoint, which no sub-issue currently covers. federation.NewHandler from go-spiffe does it in about ten lines given a spiffebundle.Source, which #6201 will produce. Worth deciding here whether that is in scope or a follow-up.

The PoC advertised tls_client_auth (RFC 8705) as the token endpoint auth method, where the draft defines a new method named spiffe. If any of that naming gets lifted, it needs correcting.