From 709dfbfc91baa5a172ed1fecbf3ae3c0a6a092fa Mon Sep 17 00:00:00 2001 From: rkoster Date: Fri, 18 Sep 2026 15:15:55 +0200 Subject: [PATCH 1/3] docs: define RFC 8628 device authorization research note --- ...vice-authorization-research-note-design.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-18-rfc-8628-device-authorization-research-note-design.md diff --git a/docs/superpowers/specs/2026-09-18-rfc-8628-device-authorization-research-note-design.md b/docs/superpowers/specs/2026-09-18-rfc-8628-device-authorization-research-note-design.md new file mode 100644 index 0000000..0636ee6 --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-rfc-8628-device-authorization-research-note-design.md @@ -0,0 +1,30 @@ +# RFC 8628 Device Authorization Research Note Design + +## Goal + +Add a sourced research note on RFC 8628 OAuth 2.0 Device Authorization Grant for headless +agents, CLIs, remote daemons, and constrained devices. + +## Scope + +The note will cover the device authorization request/response, device and user codes, +verification URI, user approval on a secondary device, polling, token issuance, discovery, and +security considerations including brute force, phishing, device trust, and polling control. +It will identify RFC 8628 as an IETF Proposed Standard. + +The Cloud Foundry analysis will map device authorization to UAA, remote agent daemons, service +bindings, human consent, headless workloads, token storage, polling, revocation, and audit. It +will not claim existing CF/RFC 8628 integration. + +## Structure and evidence + +Create `research/rfc-8628-device-authorization.md` with the required four sections and +frontmatter. Use RFC 8628, RFC Editor metadata, and OAuth references. Clearly distinguish device +authorization from agent delegation and token exchange: device flow obtains initial user consent; +it does not itself define downstream resource delegation policy. + +## Validation + +Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on +`research/rfc-8628-device-authorization`, push, and open a PR targeting `main` without unrelated +artifacts. From d76048621bfb89b2188aceea34f97ba3cc3a5c8b Mon Sep 17 00:00:00 2001 From: rkoster Date: Fri, 18 Sep 2026 15:16:42 +0200 Subject: [PATCH 2/3] docs: add RFC 8628 device authorization research note --- ...8628-device-authorization-research-note.md | 27 +++++ research/rfc-8628-device-authorization.md | 107 ++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-18-rfc-8628-device-authorization-research-note.md create mode 100644 research/rfc-8628-device-authorization.md diff --git a/docs/superpowers/plans/2026-09-18-rfc-8628-device-authorization-research-note.md b/docs/superpowers/plans/2026-09-18-rfc-8628-device-authorization-research-note.md new file mode 100644 index 0000000..b800800 --- /dev/null +++ b/docs/superpowers/plans/2026-09-18-rfc-8628-device-authorization-research-note.md @@ -0,0 +1,27 @@ +# RFC 8628 Device Authorization Research Note Implementation Plan + +> **For agentic workers:** Execute this plan inline with validation checkpoints. + +**Goal:** Add and publish a sourced research note on RFC 8628 OAuth 2.0 Device Authorization Grant for headless agents and remote workloads. + +**Architecture:** Explain the device authorization endpoint, user/device codes, secondary-device consent, polling and token issuance, then map the flow to CF UAA, remote daemons, bindings, and audit while separating initial consent from downstream delegation. + +**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI. + +--- + +### Task 1: Write `research/rfc-8628-device-authorization.md` + +- [ ] Add frontmatter with title `RFC 8628: Device Authorization for Headless Agents and Remote Workloads`, author `Ruben Koster (@rkoster)`, date `2026-09-18`, tags `[identity, authorization, orchestration, ecosystem-survey]`, `cf_areas: [uaa, capi, diego]`, `status: draft`, ratings, and RFC 8628/RFC Editor sources. +- [ ] Explain the constrained/headless client problem and the secondary-device authorization flow. +- [ ] Cover device authorization request, device code, user code, verification URI, expiry, polling interval, token request, and errors such as `authorization_pending`, `slow_down`, `access_denied`, and `expired_token`. +- [ ] Cover discovery and client authentication/public-client behavior. +- [ ] Explain brute-force, phishing, device trust, polling overload, user consent, and token storage security considerations. +- [ ] Assess CF relevance for UAA, headless CLIs, remote agent daemons, service bindings, user consent, token persistence, revocation, and audit. +- [ ] Distinguish device authorization from RFC 8693 token exchange and agent delegation; add open questions about device identity, polling, binding, and revocation. + +### 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 8628 device authorization research note`, push `research/rfc-8628-device-authorization`, and open a checklist-complete PR targeting `main`. +- [ ] Verify PR metadata and CI with `gh pr view`. diff --git a/research/rfc-8628-device-authorization.md b/research/rfc-8628-device-authorization.md new file mode 100644 index 0000000..5ab8586 --- /dev/null +++ b/research/rfc-8628-device-authorization.md @@ -0,0 +1,107 @@ +--- +title: "RFC 8628: Device Authorization for Headless Agents and Remote Workloads" +author: Ruben Koster (@rkoster) +date: 2026-09-18 +tags: [identity, authorization, orchestration, ecosystem-survey] +cf_areas: [uaa, capi, diego] +status: draft +ratings: + platform-impact: + value: 80 + note: "Device authorization is a practical bridge for connecting headless agents, CLIs, and remote daemons to human identity without embedding a browser." + maturity: + value: 88 + note: "RFC 8628 is an IETF Proposed Standard with a defined flow, error behavior, and security considerations." + novelty: + value: 52 + note: "The protocol formalizes a constrained-device OAuth pattern rather than introducing an agent-specific delegation model." + actionability: + value: 86 + note: "The flow maps directly to CF UAA, remote agent daemons, service bindings, user consent, and token lifecycle operations." +sources: + - https://www.rfc-editor.org/rfc/rfc8628 + - https://www.rfc-editor.org/info/rfc8628/ + - https://datatracker.ietf.org/doc/rfc8628/ + - https://www.rfc-editor.org/rfc/rfc6749 +--- + +## Summary + +RFC 8628 defines the OAuth 2.0 Device Authorization Grant for clients that cannot use a +browser-based authorization flow locally or are difficult to operate interactively. The client +requests a device code and user code, asks the user to authorize on a separate device, and polls +the authorization server until a token is available. This makes it relevant to headless agent +CLIs, remote daemons, coding sandboxes, and CF-hosted workloads, while leaving downstream +delegation and resource policy to other OAuth mechanisms. + +## Key findings + +- **The flow separates the client from the user agent.** A device client makes outbound HTTPS + requests and displays a verification URI and code. The user completes authentication and + consent on a phone or computer, so the client does not need to receive inbound browser traffic. +- **The authorization server returns short-lived flow state.** The device authorization response + includes a `device_code`, a human-entered `user_code`, a verification URI, an optional complete + verification URI, an expiration, and a recommended polling interval. +- **The client polls the token endpoint.** Before consent, the token endpoint returns + `authorization_pending`. The client must respect the interval; `slow_down` increases the + interval for subsequent requests. After approval, the client receives an OAuth access token + or another configured token response. Denial and expiry have explicit errors. +- **The user code is usability-sensitive.** Because users type the code, it has lower entropy + than a bearer token. RFC 8628 requires rate limiting and finite lifetime to make guessing + infeasible, and recommends user-facing information that helps prevent authorizing an attacker + controlled device. +- **Device and user codes have different security roles.** The device code is used by the client + during polling and must be protected as sensitive flow state. The user code is entered by the + human and needs rate limiting, sufficient entropy, expiration, and phishing defenses. +- **Public clients are supported.** Clients that cannot keep credentials secret identify + themselves with `client_id`, while confidential clients authenticate according to OAuth rules. + The grant is therefore suitable for command-line tools, remote daemons, and devices with no + secure client-secret storage. +- **Polling needs capacity controls.** The protocol explicitly addresses token-endpoint load by + requiring an interval and warning clients not to begin device authorization automatically on + every startup or expired session. Implementations need rate limits and retry behavior. +- **Device trust is part of the threat model.** The authorization server cannot assume that a + device or agent client is trustworthy merely because a user approved a code. Token storage, + malware, remote phishing, authorization-server choice, and device integrity remain deployment + concerns. +- **Device authorization is not token exchange.** RFC 8628 obtains user authorization through a + secondary device. RFC 8693 exchanges an existing subject/actor token for a targeted token. + A headless agent may use RFC 8628 for initial login and RFC 8693 or another mechanism for + downstream delegation. +- **RFC 8628 is an IETF Proposed Standard.** It standardizes the flow and security behavior but + does not define an agent registry, workload identity, consent taxonomy, or resource-specific + least-privilege policy. + +## CF relevance + +Cloud Foundry could use RFC 8628 for headless CLIs, remote agent daemons, coding sandboxes, and +automation that cannot open a browser on the execution host. A CLI or daemon could request a +device code from UAA, display the verification URI/code to the user, poll for completion, and +store the resulting token using the daemon's credential and filesystem policy. + +The flow also fits remote agents running under Diego or an adjacent sandbox substrate. CAPI +could manage the application or daemon, while a service binding supplies the UAA endpoints and +client identifier. The resulting access token would need bounded scopes and secure persistence; +device authorization alone does not establish that an agent may access every tool or resource +available to the user. + +CF operators would need to expose clear device/user consent information, rate-limit polling, +support revocation and logout, and audit the link between device code, user, client/agent, +application instance, and resulting token. For long-running agents, RFC 8628 is primarily an +initial or renewal login mechanism; token exchange, refresh, workload identity, or a delegation +broker may be needed to obtain resource-specific and renewable authority. + +## Open questions + +- Should CF UAA expose RFC 8628 for remote agent daemons and headless platform clients? +- How should a device authorization request identify the CF application, agent, sandbox, or + daemon without confusing the runtime identity with the consenting user? +- Where should tokens be stored for Diego processes, remote daemons, and disposable sandboxes, + and how should replacement or migration affect them? +- How should device flow scopes combine with RFC 8693 exchange, agent delegation, and service + binding policy? +- What polling, expiry, retry, and revocation behavior should CF enforce across many agents? +- How should user consent, device details, client identity, token issuance, and downstream agent + actions be correlated in Loggregator and protected audit records? +- Which phishing, device-trust, and user-code protections should be added beyond the RFC when + the client is an autonomous or semi-autonomous agent? From 5fb2c759cff9ba61e6f5c87b7af111f7745cb4bc Mon Sep 17 00:00:00 2001 From: rkoster Date: Sat, 19 Sep 2026 16:27:06 +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..873c7a8 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.
 -