Add tokenExchange OAuth2 flow (OAuth 2.0 Token Exchange, RFC 8693)#44
Open
cayetanobv wants to merge 4 commits into
Open
Add tokenExchange OAuth2 flow (OAuth 2.0 Token Exchange, RFC 8693)#44cayetanobv wants to merge 4 commits into
cayetanobv wants to merge 4 commits into
Conversation
…fication#5428 Adds tokenExchange to the pre-defined OAuth2 flow keys: tokenUrl required, scopes as for all flows. Includes the JSON Schema rule, a collection example, and a CHANGELOG entry.
cayetanobv
added a commit
to cayetanobv/portolan-cli
that referenced
this pull request
Jul 7, 2026
…catalogs Repurposes this proposal after the upstream agreement: the vending step is standardized upstream (OAI/OpenAPI-Specification#5428 mirrored by stac-extensions/authentication#44), so Portolan adopts the Authentication extension wholesale instead of owning an access: namespace. - spec/extensions/authentication.md: profile note — two-step gated read (openIdConnect identity + oauth2/tokenExchange vending), fields used, client algorithm, chaining convention (pending upstream), validation rules, security considerations. - spec/examples/authentication-collection.json: gated collection with two schemes and two gated assets (GeoParquet + Iceberg metadata) on one exchange; validates against the v1.1.0 schema. - access: extension files removed (shape preserved in history as the recorded fallback).
Draft
1 task
Links the exchange to the scheme that supplies its subject_token, so a generic client (e.g. STAC Browser) can resolve the order of the steps from the document instead of hardcoding it. Optional; RECOMMENDED when more than one scheme is declared.
cayetanobv
added a commit
to cayetanobv/portolan-cli
that referenced
this pull request
Jul 13, 2026
…authentication#44 The tokenExchange flow now declares which auth:schemes entry supplies its subject_token (added upstream after maintainer review, for generic- client implementability). Profile: publishers SHOULD provide it, clients MUST use it when present; portolan check requires it and enforces the cross-reference resolution the upstream JSON Schema cannot express. Status note updated: maintainer proposes releasing as a new minor version of the Auth extension, decoupled from the OpenAPI timeline.
Shows the full chain end-to-end: asset -> auth:refs -> token_exchange -> subjectTokenScheme -> oauth. Previously the scheme was declared but unreferenced.
Reverts examples/collection.json to its pristine state and adds examples/collection-token-exchange.json: identity scheme (oidc) + exchange scheme linked via subjectTokenScheme + two gated assets sharing one exchange. The identity scheme is intentionally unreferenced by any auth:refs — the case that motivates the field. Follows the multi-example convention of other extensions (e.g. datacube). README points to it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds
tokenExchangeto the pre-defined OAuth2 flow keys, mirroring the proposed OpenAPI addition OAI/OpenAPI-Specification#5428 as discussed with @m-mohr in portolan-sdi/portolan-cli#551: OpenAPI PR first, this extension mirrors it.The flow corresponds to RFC 8693 (OAuth 2.0 Token Exchange): the client presents a token obtained elsewhere — e.g. an identity token from an
openIdConnectscheme — at thetokenUrland receives a different token back, typically short-lived scoped credentials for direct data access. This is the pattern behind cloud STS endpoints and credential vending in data platforms; the driving STAC use case is catalogs whose assets live in access-controlled object storage.Changes (all mirroring how the existing flows are handled):
tokenExchangeadded to the pre-defined flow keys;tokenUrlREQUIRED for it; a short paragraph in the OAuth2 Flow Object section referencing RFC 8693 and the OpenAPI PR.tokenExchangeadded to thetokenUrl-required pattern.examples/collection-token-exchange.json: a dedicated, focused example of the two-step pattern — identity scheme + exchange scheme linked viasubjectTokenScheme+ gated assets (the identity scheme is deliberately unreferenced by anyauth:refs, which is the case that motivates the field). The pre-existing examples are untouched.npm testpasses (remark + stac-node-validator, examples valid).Update (2026-07-13): the design question below is now resolved after maintainer review: added an optional
subjectTokenSchemefield on thetokenExchangeflow — the key of theauth:schemesentry whose token the client presents as the RFC 8693subject_token. This makes the two-step order machine-discoverable (a generic client, e.g. STAC Browser, resolves the chain from the document instead of hardcoding it). It deliberately goes one field beyond the OpenAPI proposal: OpenAPI's security work is being reorganized on its own timeline (OAI/OpenAPI-Specification#5428 discussion), and this extension already has precedent for STAC-specific additions (s3,signedUrl); it is a candidate to propose upstream once that settles.One design question deliberately not addressed here, for discussion: whether/how atokenExchangescheme should declare which other scheme's token is the expectedsubject_token(e.g. a field referencing anauth:schemeskey vs. leaving it todescriptionprose). Kept out to stay a faithful mirror of the OpenAPI PR; happy to follow up in a separate issue/PR if there's interest.Note on tooling: AI tooling was used for research and drafting; I reviewed and take responsibility for all content.