From 8848f9143bb0d1031719399b4d7e206acbd6e5c8 Mon Sep 17 00:00:00 2001 From: rkoster Date: Fri, 18 Sep 2026 14:42:26 +0200 Subject: [PATCH 1/3] docs: define RFC 8693 token exchange research note --- ...693-token-exchange-research-note-design.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-18-rfc-8693-token-exchange-research-note-design.md diff --git a/docs/superpowers/specs/2026-09-18-rfc-8693-token-exchange-research-note-design.md b/docs/superpowers/specs/2026-09-18-rfc-8693-token-exchange-research-note-design.md new file mode 100644 index 0000000..302fa89 --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-rfc-8693-token-exchange-research-note-design.md @@ -0,0 +1,28 @@ +# RFC 8693 Token Exchange Research Note Design + +## Goal + +Add a sourced research note on RFC 8693 OAuth 2.0 Token Exchange for delegated agent authority. + +## Scope + +The note will cover the Security Token Service model, token exchange request/response, subject +and actor tokens, resource/audience/scope targeting, impersonation versus delegation, `act` and +`may_act` claims, and security considerations. It will identify RFC 8693 as an IETF Proposed +Standard and distinguish protocol mechanics from authorization policy and identity issuance. + +The Cloud Foundry analysis will map token exchange to UAA, instance identity, service bindings, +agent gateways, least privilege, service-to-service calls, and audit. It will not claim existing +CF/RFC 8693 integration. + +## Structure and evidence + +Create `research/rfc-8693-token-exchange.md` with the required four sections and frontmatter. +Use RFC 8693 and related OAuth/OIDC references. Clearly distinguish impersonation from delegation +and explain that token exchange does not itself decide whether a requested delegation is allowed. + +## Validation + +Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on +`research/rfc-8693-token-exchange`, push, and open a separate PR targeting `main` without +unrelated artifacts. From d830e3f6a2fbb8135d507ec63390f42e08a24a01 Mon Sep 17 00:00:00 2001 From: rkoster Date: Fri, 18 Sep 2026 14:43:08 +0200 Subject: [PATCH 2/3] docs: add RFC 8693 token exchange research note --- ...8-rfc-8693-token-exchange-research-note.md | 27 +++++ research/rfc-8693-token-exchange.md | 105 ++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-18-rfc-8693-token-exchange-research-note.md create mode 100644 research/rfc-8693-token-exchange.md diff --git a/docs/superpowers/plans/2026-09-18-rfc-8693-token-exchange-research-note.md b/docs/superpowers/plans/2026-09-18-rfc-8693-token-exchange-research-note.md new file mode 100644 index 0000000..62aed00 --- /dev/null +++ b/docs/superpowers/plans/2026-09-18-rfc-8693-token-exchange-research-note.md @@ -0,0 +1,27 @@ +# RFC 8693 Token Exchange Research Note Implementation Plan + +> **For agentic workers:** Execute this plan inline with validation checkpoints. + +**Goal:** Add and publish a sourced research note on RFC 8693 OAuth 2.0 Token Exchange for delegated agent authority. + +**Architecture:** Explain the STS exchange request/response, subject and actor tokens, targeting parameters, impersonation/delegation claims, and policy boundary. Map the protocol to CF identity and service-to-service authorization. + +**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI. + +--- + +### Task 1: Write `research/rfc-8693-token-exchange.md` + +- [ ] Add frontmatter with title `RFC 8693: OAuth 2.0 Token Exchange for Delegated Agent Authority`, author `Ruben Koster (@rkoster)`, date `2026-09-18`, tags `[authorization, identity, inter-agent-comms, ecosystem-survey]`, `cf_areas: [uaa, capi, diego]`, `status: draft`, ratings, and RFC 8693/RFC Editor sources. +- [ ] Explain RFC 8693 as an IETF Proposed Standard defining an HTTP/JSON Security Token Service protocol. +- [ ] Cover token exchange parameters including grant type, subject token, actor token, resource, audience, scope, and requested token type. +- [ ] Distinguish impersonation, where the issued subject acts as the original subject, from delegation, where `sub` and `act` preserve the principal and current actor; cover `may_act` authorization. +- [ ] Explain that RFC 8693 provides protocol mechanics but authorization policy, trust in token issuers, key validation, and resource policy remain deployment responsibilities. +- [ ] Assess CF relevance for UAA, instance identity, service bindings, agent gateways, service-to-service calls, least privilege, and audit. +- [ ] Add open questions about subject/actor mapping, audience/resource policy, token lifetime, revocation, nested delegation, and audit semantics. + +### Task 2: Validate and publish + +- [ ] Run `devbox run validate`, `devbox run test`, and `git diff --check`. +- [ ] Stage only the note and approved spec/plan, commit `docs: add RFC 8693 token exchange research note`, push `research/rfc-8693-token-exchange`, and open a separate checklist-complete PR targeting `main`. +- [ ] Verify PR metadata and CI with `gh pr view`. diff --git a/research/rfc-8693-token-exchange.md b/research/rfc-8693-token-exchange.md new file mode 100644 index 0000000..ce5d27f --- /dev/null +++ b/research/rfc-8693-token-exchange.md @@ -0,0 +1,105 @@ +--- +title: "RFC 8693: OAuth 2.0 Token Exchange for Delegated Agent Authority" +author: Ruben Koster (@rkoster) +date: 2026-09-18 +tags: [authorization, identity, inter-agent-comms, ecosystem-survey] +cf_areas: [uaa, capi, diego] +status: draft +ratings: + platform-impact: + value: 88 + note: "Token exchange provides a standardized mechanism for agents and services to obtain narrowly targeted credentials without sharing broad user tokens." + maturity: + value: 86 + note: "RFC 8693 is an IETF Proposed Standard with established OAuth and Security Token Service terminology." + novelty: + value: 58 + note: "The protocol formalizes established STS impersonation and delegation patterns rather than defining an agent-specific identity model." + actionability: + value: 90 + note: "The subject/actor/audience model maps directly to CF UAA, workload identity, service bindings, and agent gateway authorization." +sources: + - https://www.rfc-editor.org/rfc/rfc8693 + - https://www.rfc-editor.org/info/rfc8693/ + - https://datatracker.ietf.org/doc/rfc8693/ + - https://www.rfc-editor.org/rfc/rfc6749 +--- + +## Summary + +RFC 8693 defines an HTTP and JSON protocol for OAuth 2.0 token exchange through a Security Token +Service. A client presents a subject token, optionally an actor token, and target parameters to +obtain a new token appropriate for a resource or audience. The protocol supports impersonation +and delegation, making it a foundational mechanism for agents that need scoped authority without +holding broad user or provider credentials. + +## Key findings + +- **RFC 8693 standardizes an STS interaction.** It defines how a client requests a security + token from an OAuth authorization server using the token-exchange grant type. The server + validates the presented token(s), applies policy, and issues a token for the requested use. +- **The request carries explicit context.** Exchange parameters include `subject_token`, its + type, optional `actor_token`, target `resource`, logical `audience`, requested `scope`, and + requested token type. These fields let a deployment bind the issued token to a target service + and constrained authority. +- **Impersonation and delegation differ.** In impersonation, the client acts as the subject and + the issued token can preserve the subject identity without identifying a distinct actor. In + delegation, the subject is the party on whose behalf action occurs and the actor token + identifies the party currently acting. +- **The `act` claim preserves actor context.** RFC 8693 examples show an issued token with + `sub` identifying the subject and `act.sub` identifying the delegated actor. This preserves + accountability while allowing the actor to use a token targeted at a downstream service. +- **`may_act` can constrain delegation.** A subject token can express an actor authorized to act + on its behalf. The authorization server still decides whether the requested exchange is + allowed, how scopes are reduced, and what claims appear in the issued token. +- **Targeting is a security boundary.** `resource` identifies a protected resource URI and + `audience` identifies a logical target service. The target service can reject a token issued for + another audience, reducing the value of a token leaked outside its intended path. +- **Token exchange is not authorization policy by itself.** RFC 8693 defines protocol fields and + flows, but deployments choose trusted issuers, token validation, allowed actors, scope + reduction, audience/resource policy, token lifetime, revocation, and key management. +- **The issued token is a new credential.** Exchange does not merely forward the subject token; + it produces a token with the authorization server's issuer, target, lifetime, scopes, and + identity/delegation context. Downstream services must validate the new token and enforce their + own resource policy. +- **The model supports multi-hop services.** A service can exchange or pass delegated authority + onward when policy permits, but each hop increases the need for bounded scopes, actor-chain + visibility, audience restrictions, and reliable audit. +- **RFC 8693 is an IETF Proposed Standard.** It is a protocol foundation, not a complete agent + identity system, consent UX, credential vault, or workload lifecycle mechanism. + +## CF relevance + +Cloud Foundry could use RFC 8693 to let an agent exchange a user or workload token for a +resource-specific token without receiving a broad credential. UAA could participate as the +authorization server or trusted issuer, while a CF instance identity certificate identifies +the running workload. A gateway could exchange the agent's subject/actor context for a token +targeted at a service, tool, route, or downstream application. + +Service bindings could carry exchange endpoints and constrained client credentials rather than +long-lived provider secrets. The resulting token could identify the user in `sub`, the agent or +gateway in `act`, and the target CF service in `aud` or `resource`. CAPI and Diego lifecycle +events could inform revocation when an application, process instance, binding, or delegation is +removed, while Loggregator could correlate exchange, downstream request, policy decision, and +outcome. + +The protocol does not remove the need for CF policy. A platform must decide which workloads may +act for which users, how scopes are narrowed, whether nested delegation is allowed, how short +tokens live, and how token exchange is audited. RFC 8693 is therefore a useful interoperability +boundary for an identity broker or gateway, not a substitute for UAA governance or application +authorization. + +## Open questions + +- What should `sub` and `act` represent for CF users, app instances, agents, gateways, and + delegated tools? +- Should UAA issue exchange tokens directly, or should a dedicated agent identity broker sit + between UAA and downstream services? +- How should `resource` and `audience` map to CF apps, routes, service instances, tools, and + external providers? +- Which scopes may be exchanged, and how must every delegation hop reduce or preserve authority? +- How should instance replacement, certificate rotation, grant revocation, and user logout + invalidate exchanged tokens? +- What token lifetime and replay protections are appropriate for long-running agent tasks? +- How should nested `act` chains and exchange events appear in Loggregator, audit records, and + downstream authorization decisions? From cf4879ce4e1a7f00f95b3fe1ec43897ab24f4f19 Mon Sep 17 00:00:00 2001 From: rkoster Date: Sat, 19 Sep 2026 16:27:17 +0200 Subject: [PATCH 3/3] docs: update generated research map --- generated/research-map.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/generated/research-map.html b/generated/research-map.html index bbe5f21..4b3dc40 100644 --- a/generated/research-map.html +++ b/generated/research-map.html @@ -23,9 +23,9 @@

Focus use cases

Attested Workload Authority and Mediated Tool AccessExchange platform-attested workload identity for scoped authority while credentials and outbound tool access remain mediated by the platform.Strategic decision: Decide whether CF should become the portable trust and policy layer between agent workloads and the tools they invoke.
Gap, experiments, and evidence
Current CF gap
CF issues workload identity certificates but does not exchange them for scoped tool authority, keep third-party credentials out of workloads, mediate off-platform access, or record delegation-aware audit events.
Candidate POC
Exchange a Diego instance identity certificate for a short-lived scoped token, invoke one allowed tool through a credential proxy and egress mediator, deny another, and emit attributable audit events.
Candidate RFC scope
Define workload token exchange, authority and delegation claims, credential brokering, outbound mediation and policy enforcement, audit events, revocation, and integration boundaries for UAA, routing, and service brokers.

Core

Supporting

-
Gap, experiments, and evidence
Current CF gap
CF can stage apps and run ephemeral tasks but cannot cheaply compose a reusable environment with per-session workspace state, select stronger isolation, constrain session networking, or resume the session lifecycle.
Candidate POC
Start two isolated sessions from one content-addressed staged environment, attach separate mutable workspaces, apply per-session egress policy, stop one session, and resume it on fresh compute.
Candidate RFC scope
Define environment and workspace references, session identity and lifecycle, isolation classes, network policy, workspace persistence and cleanup, scheduling, quotas, and compatibility with existing CF staging and task APIs.

Core

Supporting

ResearchIdea

Platform Impact x Maturity

Emerging < Maturity > EstablishedLocal concern < Platform Impact > Platform-wide concern
Unplaced notes (0)
  • All notes are placed.
+
Gap, experiments, and evidence
Current CF gap
CF can stage apps and run ephemeral tasks but cannot cheaply compose a reusable environment with per-session workspace state, select stronger isolation, constrain session networking, or resume the session lifecycle.
Candidate POC
Start two isolated sessions from one content-addressed staged environment, attach separate mutable workspaces, apply per-session egress policy, stop one session, and resume it on fresh compute.
Candidate RFC scope
Define environment and workspace references, session identity and lifecycle, isolation classes, network policy, workspace persistence and cleanup, scheduling, quotas, and compatibility with existing CF staging and task APIs.

Core

Supporting

ResearchIdea

Platform Impact x Maturity

Emerging < Maturity > EstablishedLocal concern < Platform Impact > Platform-wide concern
Unplaced notes (0)
  • All notes are placed.
 -