Complete OAuth2 token refresh and expiration support (Java-compatible)

Ouverte
  • Quelque chose ne va pas ?
#1,095 2 commentaires 0 réactions 1 personne assignée Voir sur GitHub

Les mainteneurs répondent en général sous 2 jours

@lishuxu y travaille déjà.

Depuis le 5/11/2026.

Évaluation

Cette issue n'a pas encore été évaluée.

Description

Feature Description

Complete the remaining OAuth2 token refresh and expiration behavior in the REST catalog, using the Java implementation as the compatibility reference. Catalog and child sessions should refresh through the appropriate OAuth2 flow while preserving the session's authentication identity.

The shared auth refresh executor and child-session cache are already implemented by #1033 and #985. This issue builds on those foundations.

Current behavior as of 9c478f75:

  • Client-credential catalog sessions support background refresh.
  • Credential-based contextual sessions support background refresh when refresh is enabled and an auth executor is provided.
  • Contextual and table child sessions are cached, with idle eviction and refresh cleanup.
  • Initial RFC 8693 token exchange is supported.

Remaining gaps:

  • Background refresh always uses the client credentials flow. token-exchange-enabled is declared but ignored.
  • Direct bearer tokens in catalog and child sessions do not refresh automatically.
  • Token-exchange child sessions are created with refresh disabled.
  • token-expires-in-ms is unsupported. OAuth2 contextual sessions ignore context.properties; table-session bearer-token lifetime properties are also not consumed.
  • Java's token-exchange refresh and expired-token recovery behavior are not implemented.

These gaps matter for long-lived contexts and tables: reloading a session from the cache does not update a session already held by an existing caller.

User Experience

Use the existing REST auth APIs and caller-provided auth executor, with the same property names and refresh-flow semantics as Java:

Property Intended behavior
token-refresh-enabled Controls automatic refresh for supported catalog and child-session paths.
token-exchange-enabled Selects token exchange for refresh when enabled; uses the available client credential when disabled, following Java. This setting does not disable the initial exchange of a typed child token.
token-expires-in-ms Supplies the lifetime used to schedule refresh for a direct bearer token when JWT expiration is unavailable, following Java's property-presence and precedence rules.
auth.session-timeout-ms Continues to control cache idle eviction independently of token expiration.

For example, an opaque contextual bearer token can supply its lifetime separately from the sensitive token:

iceberg::SessionContext context{
    .session_id = "caller-session",
    .credentials = {{"token", "opaque-access-token"}},
    .properties = {{"token-expires-in-ms", "60000"}},
};

With refresh enabled, an auth executor configured, and a token endpoint that supports the selected flow, the derived session can refresh before expiration. The corresponding direct-bearer table-session path should also consume its lifetime property.

Spec and Compatibility
  • Use Java OAuth2Manager, OAuth2Util.AuthSession, and AuthConfig as the behavior reference, together with RFC 8693 for token exchange.
  • Refresh the current session token with its current issued token type. Do not enable child refresh by reusing a parent credential in a way that changes the child's authentication identity.
  • Match Java's handling of expired tokens and credential-backed recovery, including the required request authentication. Recovery is not an unconditional switch to the catalog identity.
  • Consume the specific contextual/table properties Java uses for bearer-token expiration. This does not imply merging all contextual properties into the parent OAuth configuration.
  • Preserve request-start-based expiration accounting, existing retry handling, and the caller-provided executor model.
  • Preserve cache eviction and shutdown guarantees: removed sessions stop scheduling refreshes, and close/eviction races do not introduce deadlocks or duplicate cleanup.
  • Define and test behavior when no auth executor, refresh credential, or usable expiration is available. Do not silently fall back to a different identity.
  • No Iceberg storage-format change is required. Any public API additions should be identified in the implementation PRs.
Task Breakdown

Proposed as three implementation PRs. Each PR includes its focused tests; the last step adds cross-path integration coverage and documentation.

  • 1. Implement the refresh strategy and expired-token recovery. Honor token-exchange-enabled; exchange the current token and issued token type; retain the Java-compatible client-credential path and request authentication. Cover both setting values, expired-token recovery, retries, and unavailable credentials.
  • 2. Support direct bearer expiration and refresh. Add token-expires-in-ms, align JWT/explicit-lifetime precedence and property-presence behavior with Java, consume contextual/table bearer lifetime properties, and enable the catalog/context/table direct-bearer refresh paths. Cover opaque tokens, JWTs, already-expired tokens, and refresh-disabled/no-executor behavior. Depends on step 1.
  • 3. Enable token-exchange child refresh and validate the lifecycle. Enable refresh for exchanged contextual/table sessions after the strategy is available. Verify identity-preserving refresh, refreshed expiration/type propagation, cache reuse, failure recovery, and close/eviction during refresh. Document the supported flows and remaining limitations. Depends on step 1; end-to-end validation also covers step 2.

Scope is limited to OAuth2 refresh and expiration parity. SigV4 provider extensibility, TLS configuration, general HTTP retry/idempotency, and storage credential refresh should be tracked separately.

I plan to work on this as a series of small PRs. Feedback on the scope and proposed split is welcome.

Related Issues and References
Langage dominant
C++
Étoiles
227
Forks
142
Merge moyen
3 j 21 min
PR mergées (30 j)
70

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de apache/iceberg-cpp

Toutes les issues de apache/iceberg-cpp

Issues similaires

Plus d'issues C++

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.