Skip to content

Add --force-refresh flag to auth token command#4767

Draft
mihaimitrea-db wants to merge 3 commits intomainfrom
mihaimitrea-db/token-force-refresh
Draft

Add --force-refresh flag to auth token command#4767
mihaimitrea-db wants to merge 3 commits intomainfrom
mihaimitrea-db/token-force-refresh

Conversation

@mihaimitrea-db
Copy link
Contributor

Wire a new --force-refresh CLI flag that delegates to the SDK's ForceRefreshToken() method, bypassing the cached token validity check. The default path through Token() is unchanged.

Note: this will not compile until the SDK ships ForceRefreshToken() (databricks/databricks-sdk-go#1552).

Changes

  • Add a --force-refresh boolean flag to databricks auth token. When set, the command calls PersistentAuth.ForceRefreshToken() instead of PersistentAuth.Token(), which always performs a token refresh against the IdP regardless of the cached token's remaining TTL.
  • The error handling is shared between both paths: invalid refresh tokens produce the same actionable "To reauthenticate, run..." message, and the backward-compat cache.ErrNotFound rewrite is preserved.
  • Add three acceptance tests covering the force-refresh flag end-to-end:
    • force-refresh-success: pre-populated cache with a valid token, --force-refresh returns the server's new token (not the cached one).
    • force-refresh-invalid-refresh-token: server returns 401 with invalid refresh token; asserts the actionable re-login error message.
    • force-refresh-no-cache: no cached token exists; asserts the backward-compat error message is preserved for --force-refresh.
  • Add unit tests verifying the default path still returns a cached valid token without refreshing, and that --force-refresh correctly delegates to ForceRefreshToken() for both success and failure cases.

Why

#4564 reports that external consumers using databricks auth token as a credential helper (e.g. Claude Code via apiKeyHelper) can receive near-expired tokens that expire before they can be used.

databricks/databricks-sdk-go#1535 addressed the common case by adding a 5-minute proactive refresh buffer to Token(). However, that proactive refresh is intentionally best-effort: Token() still returns the existing access token when it is valid and a proactive refresh fails, because callers did not explicitly ask for a fresh token.

For integrations that treat the CLI as a token minter or want to manage their own cache/TTL policy, "return a still-usable token" is different from "refresh now and give me a newly minted token or fail." The --force-refresh flag gives those integrations an explicit way to guarantee a fresh token.

Tests

  • Unit tests in cmd/auth/token_test.go: table-driven cases covering default-path cache reuse, force-refresh success, and force-refresh error preservation.
  • Acceptance tests in acceptance/cmd/auth/token/force-refresh-{success,invalid-refresh-token,no-cache}/: end-to-end tests against the mock OIDC server, run for both terraform and direct engine variants.

@mihaimitrea-db mihaimitrea-db force-pushed the mihaimitrea-db/token-force-refresh branch from f78303b to c2ce190 Compare March 17, 2026 12:54
@eng-dev-ecosystem-bot
Copy link
Collaborator

eng-dev-ecosystem-bot commented Mar 17, 2026

Commit: 7335554

Run: 23306245217

Wire a new --force-refresh CLI flag that delegates to the SDK's
ForceRefreshToken() method, bypassing the cached token validity
check. The default path through Token() is unchanged.

Note: this will not compile until the SDK ships ForceRefreshToken().
@mihaimitrea-db mihaimitrea-db force-pushed the mihaimitrea-db/token-force-refresh branch from c2ce190 to 807421a Compare March 17, 2026 13:14
@mihaimitrea-db mihaimitrea-db self-assigned this Mar 17, 2026
- Add failOnCallTransport to assert no network call when reusing cached token
- Remove inherited Ignore from force-refresh-invalid-refresh-token test.toml
- Add explanatory comment in force-refresh-success script
- Tighten --force-refresh description in Long help text
- Rename resp -> got in validateToken callbacks for consistency
- Fix inMemoryTokenCache to copy tokens on Lookup/Store, matching
  file-backed cache semantics and preventing cross-test corruption
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Please support customizing expiryDelta for auth token command

2 participants