Skip to content

docs(adr): Amend ADR 0026 §12 with token-exchange scope #1365

Open

Description

@gtema

Problem

ADR 0026 §12 reads as a feature roadmap for exchanging Keystone-native credentials (trust, application credential, EC2, Fernet) for OP JWTs, and ADR 0026 §13 Stage 4 presents Fernet-for-JWT exchange as the migration "long tail" tool. In practice:

  • Stage 3 moves machine identities away from application credentials to registered OAuth2Clients, and Stage 5 sunsets Fernet.
  • ADR 0036 (Proposed) supersedes trusts and defines on-behalf-of exchange (§6) as the delegation mechanism.
  • Implement token exchange using the mapping engine #1018 adds external-IdP JWT subjects, which §1's "Circular Token Exchange Trap" wording appears to prohibit.

The ADRs therefore do not state which subject kinds the grant is meant to serve long-term, and the shipped AppCred-only implementation is described as the beginning of a roadmap rather than as a migration bridge.

What must be done

  • Add an amendment to ADR 0026 §12 stating the intended scope of the grant:
    • Strategic uses: external-IdP JWT ingress (Implement token exchange using the mapping engine #1018) and on-behalf-of exchange / audience narrowing (ADR 0036 §6).
    • Legacy, migration-only: exchange of Fernet/JWS tokens and application-credential subjects. Frozen at its current feature set, sunset with Fernet (Stage 5). No Trust or EC2 subject support is added.
  • Amend §13 Stage 4 so it no longer implies Fernet exchange is a long-term feature.
  • Add the §1 "Circular Token Exchange Trap" note distinguishing external-JWT-for-native-JWT exchange (Implement token exchange using the mapping engine #1018) from the eliminated external-JWT-for-Fernet pattern.
  • Cross-link ADR 0036 §6 and §6.4 so both ADRs agree on supported subject kinds and revocation semantics (see oauth2: Decide scope of token-exchange subject kinds and revocation #1357 for the decisions this records).
  • Update the "Token exchange" row in doc/src/contributor/oauth2-production-readiness.md.

Acceptance criteria

  • A reader of ADR 0026 §12/§13 and ADR 0036 §6 gets one consistent answer to "which subject kinds does the exchange grant serve, and which are legacy?".

Tracked under #945. Depends on the decisions in #1357.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    Projects

    • Status
      Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions