Skip to content

Commit b805cf1

Browse files
Add force-refresh path for cached U2M tokens (#1552)
## Summary This PR adds an explicit `PersistentAuth.ForceRefreshToken()` path for cached U2M OAuth tokens so the CLI can implement `databricks auth token --force-refresh` on top of the 5-minute proactive refresh buffer introduced in #1535. For maintainability reasons it also splits token loading from refresh decisions and documents a cross-process refresh race for a follow-up fix. ## Why #1535 changed the default U2M token path to proactively refresh tokens that are within 5 minutes of expiry so callers of `databricks auth token` are less likely to receive a token that expires before it can be used. That addresses the "give me a useful token" case, which came out of the `auth token` discussion in [cli issue #4564](databricks/cli#4564 (comment)). That proactive refresh is intentionally best-effort, though. `PersistentAuth.Token()` still returns the existing access token when it is valid and a proactive refresh fails, because callers did not explicitly ask to block on a fresh token. That behavior is appropriate for the default path, but it is not strong enough for integrations that want to treat the CLI as a token minter or that want to manage their own cache/TTL policy. In those cases, "return a still-usable token" is different from "refresh now and give me a newly minted token or fail." This PR adds that stricter SDK primitive. It gives the CLI a clean way to implement `--force-refresh` without changing the semantics of the existing `Token()` flow. The raw oauth2 error text for forced refresh failures can be misleading. In particular, when a forced refresh is requested for a cached access token that is still valid but does not include a refresh token, the default oauth2 error suggests that the token is expired even though the real problem is that the cached token is not refresh-capable. This PR surfaces explicit refresh-token errors instead of relying on the default oauth2 wording, so callers can distinguish "the current access token is expired" from "a new token could not be minted because the refresh token is missing or was rejected by the IdP". ## What changed ### Interface changes - Added `(*PersistentAuth).ForceRefreshToken() (*oauth2.Token, error)`. This always attempts to refresh the cached U2M token, regardless of its current expiry, and redacts the refresh token from the returned value just like `Token()` does. ### Behavioral changes - For `Token()`, the only behavioral change is that expired tokens with no refresh token now return `ErrMissingRefreshToken` instead of a less specific oauth2 library error. Callers can use `errors.Is(err, ErrMissingRefreshToken)` to detect this case. - `PersistentAuth.ForceRefreshToken()` always tries to refresh, even when the cached access token is still valid. - If forced refresh fails, `ForceRefreshToken()` returns an error instead of falling back to the existing token. - If the cached token does not contain a refresh token, `ForceRefreshToken()` fails explicitly. ### Internal changes - Extracted cache lookup into `loadToken()` so token loading and refresh policy are separated. - Reused the existing refresh path so forced refresh still goes through the same endpoint resolution, token exchange, cache update, and refresh-token redaction logic as the normal path. - Added dedicated tests for force-refresh success, missing refresh token, transient refresh failure, invalid refresh token handling, and the profile-to-host fallback path. - Documented the remaining cross-process refresh race in `refresh()` with a follow-up TODO rather than expanding the scope of this PR to add inter-process coordination. - Added `ErrMissingRefreshToken` for the "cached token has no refresh token" case. - Added missing-refresh-token check into the shared `refresh()` path so both `Token()` and `ForceRefreshToken()` wrap the same semantic error. ## How is this tested? - `go test ./credentials/u2m` - Added unit tests covering: - refreshing a still-valid cached token via `ForceRefreshToken()` - failing `ForceRefreshToken()` when the cached token has no refresh token - surfacing the exact wrapped error on refresh failure - preserving `InvalidRefreshTokenError` behavior - exercising forced refresh through the existing profile-key to host-key fallback path --------- Signed-off-by: Mihai Mitrea <[email protected]>
1 parent c5ffd91 commit b805cf1

4 files changed

Lines changed: 431 additions & 11 deletions

File tree

‎NEXT_CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
### Breaking Changes
66

77
### New Features and Improvements
8+
* Add `PersistentAuth.ForceRefreshToken()` to force-refresh cached U2M OAuth tokens and return an error instead of falling back to an existing token when refresh fails.
9+
* Add `ErrMissingRefreshToken`, returned when a token refresh is requested but the cached token has no refresh token (i.e. `Token()` or `ForceRefreshToken()`).
810

911
### Bug Fixes
1012

‎credentials/u2m/error.go‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
11
package u2m
22

3-
// InvalidRefreshTokenError is returned from PersistentAuth's Load() method
4-
// if the access token has expired and the refresh token in the token cache
5-
// is invalid.
3+
import "errors"
4+
5+
// ErrMissingRefreshToken is returned when a token refresh is requested but the
6+
// cached OAuth token does not include a refresh token.
7+
var ErrMissingRefreshToken = errors.New("cached token has no refresh token")
8+
9+
// InvalidRefreshTokenError is returned from PersistentAuth's Token() and
10+
// ForceRefreshToken() methods when a token refresh is attempted and the cached
11+
// refresh token is invalid.
612
type InvalidRefreshTokenError struct {
713
error
814
}

‎credentials/u2m/persistent_auth.go‎

Lines changed: 59 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -222,17 +222,17 @@ func NewPersistentAuth(ctx context.Context, opts ...PersistentAuthOption) (*Pers
222222
return p, nil
223223
}
224224

225-
// Token loads the OAuth2 token for the given OAuthArgument from the cache. If
226-
// the token is expired or close to expiry, it is refreshed using the refresh
227-
// token.
228-
//
225+
// loadToken loads the cached OAuth2 token for the configured OAuthArgument.
229226
// When a profile is set, lookup is by profile key first. If the profile key is
230227
// not found and the OAuthArgument implements HostCacheKeyProvider, a fallback
231228
// lookup by host key is attempted. If found, the token is returned without
232229
// being migrated to the profile key (see inline comment for rationale).
233-
func (a *PersistentAuth) Token() (t *oauth2.Token, err error) {
230+
//
231+
// The returned token may be expired; callers are responsible for deciding
232+
// whether and how to refresh it.
233+
func (a *PersistentAuth) loadToken() (*oauth2.Token, error) {
234234
key := a.oAuthArgument.GetCacheKey()
235-
t, err = a.cache.Lookup(key)
235+
t, err := a.cache.Lookup(key)
236236
if errors.Is(err, cache.ErrNotFound) {
237237
hostKey := a.hostCacheKey()
238238
if hostKey != "" && hostKey != key {
@@ -250,6 +250,18 @@ func (a *PersistentAuth) Token() (t *oauth2.Token, err error) {
250250
if err != nil {
251251
return nil, fmt.Errorf("cache: %w", err)
252252
}
253+
return t, nil
254+
}
255+
256+
// Token loads the OAuth2 token for the given OAuthArgument from the cache. If
257+
// the token is expired or close to expiry, it is refreshed using the refresh
258+
// token. When a proactive refresh (token still valid but near expiry) fails,
259+
// the existing token is returned so the caller is not blocked.
260+
func (a *PersistentAuth) Token() (*oauth2.Token, error) {
261+
t, err := a.loadToken()
262+
if err != nil {
263+
return nil, err
264+
}
253265
if needsRefresh(t) {
254266
if refreshedToken, err := a.refresh(t); err == nil {
255267
t = refreshedToken
@@ -259,9 +271,35 @@ func (a *PersistentAuth) Token() (t *oauth2.Token, err error) {
259271
logger.Debugf(a.ctx, "proactive token refresh failed, returning existing token: %v", err)
260272
}
261273
}
274+
t.RefreshToken = ""
275+
return t, nil
276+
}
262277

263-
// Do not include the refresh token for security reasons. Refresh tokens are
264-
// long-lived credentials that we do not want to expose unnecessarily.
278+
// ForceRefreshToken loads the OAuth2 token from the cache and always refreshes
279+
// it, regardless of its expiry. Unlike Token(), if the refresh fails the error
280+
// is always returned -- the caller explicitly asked for a fresh token, so
281+
// silently falling back to a stale one would be incorrect.
282+
//
283+
// When the token was loaded via host-key fallback (profile key not found), the
284+
// refreshed token is dual-written to both the profile key and host key,
285+
// effectively migrating the token to the profile. Token() has the same
286+
// migration behavior when it refreshes a host-fallback token (expired or
287+
// nearly expired); ForceRefreshToken widens this to still-valid tokens because
288+
// it always refreshes.
289+
//
290+
// TODO: Thread provenance out of loadToken() so callers know whether the token
291+
// came from the primary key or host-key fallback. ForceRefreshToken could then
292+
// refuse to migrate a fallback token or refresh without writing to the profile
293+
// key, avoiding the risk of making a wrong-scoped token sticky.
294+
func (a *PersistentAuth) ForceRefreshToken() (*oauth2.Token, error) {
295+
t, err := a.loadToken()
296+
if err != nil {
297+
return nil, err
298+
}
299+
t, err = a.refresh(t)
300+
if err != nil {
301+
return nil, fmt.Errorf("forced token refresh: %w", err)
302+
}
265303
t.RefreshToken = ""
266304
return t, nil
267305
}
@@ -278,7 +316,20 @@ func needsRefresh(t *oauth2.Token) bool {
278316

279317
// refresh refreshes the token for the given OAuthArgument, storing the new
280318
// token in the cache.
319+
//
320+
// TODO: This read-refresh-write sequence is not coordinated across processes.
321+
// Because the CLI is stateless, two separate CLI invocations can load the same
322+
// cached refresh token, both attempt a refresh, and race to update the cache.
323+
// This should be fixed in a follow-up by adding cross-process coordination
324+
// around refresh and cache writes.
281325
func (a *PersistentAuth) refresh(oldToken *oauth2.Token) (*oauth2.Token, error) {
326+
// Fail fast with ErrMissingRefreshToken instead of letting the oauth2
327+
// library attempt to refresh and return a misleading error (e.g. "token
328+
// expired" when the real problem is that the cached token is not
329+
// refresh-capable).
330+
if oldToken.RefreshToken == "" {
331+
return nil, ErrMissingRefreshToken
332+
}
282333
cfg, err := a.oauth2Config()
283334
if err != nil {
284335
return nil, err

0 commit comments

Comments
 (0)