Skip to content

Commit 8c24b9f

Browse files
Add 5-minute token refresh buffer to pre-emptively refresh early (#1535)
## Summary Proactively refresh OAuth tokens that will expire within 5 minutes, preventing callers of `databricks auth token` from receiving near-expired tokens that may expire before they can be used. The CLI uses the SDK's logic to obtain tokens either from the server of from the cache. This change is intended to affect the CLI. ## Why The oauth2 library's default `expiryDelta` is 10 seconds, meaning `Token.Valid()` only triggers a refresh in the last 10 seconds before expiry. External consumers that use `databricks auth token` as a credential helper can receive a token with very little time remaining, which may expire before the next request is made: [Please support customizing expiryDelta for auth token command](databricks/cli#4564) This PR adds a hardcoded 5-minute refresh buffer so that tokens are refreshed early enough to be usable if received even right before a refresh. ## What changed ### Interface changes None. ### Behavioral changes - `PersistentAuth.Token()` now refreshes the token when it is valid but will expire within 5 minutes, instead of waiting until the last 10 seconds (the oauth2 library default). - Tokens with a zero expiry (never-expiring tokens) are not affected. ### Internal changes - Added `tokenRefreshBuffer` constant (5 minutes) in `credentials/u2m/persistent_auth.go`. - Added `tokenExpiringSoon` function that checks whether a token is within the buffer window. - Added `forceRefresh` method that creates a shallow copy of the token with a past expiry before calling `refresh`, bypassing the oauth2 library's internal validity check. - Updated existing tests to use 1-hour token expiry (previously 1 minute) so they remain outside the new buffer window. ## How is this tested? Unit tests covering the three key scenarios: - Token expiring in 4 minutes (within buffer) triggers a refresh. - Token expiring in 6 minutes (outside buffer) is returned as-is. - Token with zero expiry does not trigger a refresh. --------- Signed-off-by: Mihai Mitrea <[email protected]>
1 parent 146612b commit 8c24b9f

3 files changed

Lines changed: 226 additions & 16 deletions

File tree

‎NEXT_CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,6 @@
1111
### Documentation
1212

1313
### Internal Changes
14+
* Proactively attempt to refresh OAuth tokens expiring within 5 minutes in `PersistentAuth.Token()` to reduce the chance of callers receiving near-expired tokens. If the refresh fails and the token is still valid, the existing token is returned.
1415

1516
### API Changes

‎credentials/u2m/persistent_auth.go‎

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@ const (
3535
// listenerTimeout is the maximum duration spent trying to acquire a
3636
// listener (including port selection).
3737
listenerTimeout = 45 * time.Second
38+
39+
// tokenRefreshBuffer is the duration before token expiry at which the
40+
// token is proactively refreshed. This prevents callers from receiving
41+
// near-expired tokens that may expire before the next request.
42+
tokenRefreshBuffer = 5 * time.Minute
3843
)
3944

4045
var (
@@ -45,8 +50,8 @@ var (
4550

4651
// PersistentAuth is an OAuth manager that handles the U2M OAuth flow. Tokens
4752
// are stored in and looked up from the provided cache. Tokens include the
48-
// refresh token. On load, if the access token is expired, it is refreshed
49-
// using the refresh token.
53+
// refresh token. On load, if the access token is expired or close to expiry,
54+
// it is refreshed using the refresh token.
5055
//
5156
// The PersistentAuth is safe for concurrent use. The token cache is locked
5257
// during token retrieval, refresh and storage.
@@ -218,7 +223,8 @@ func NewPersistentAuth(ctx context.Context, opts ...PersistentAuthOption) (*Pers
218223
}
219224

220225
// Token loads the OAuth2 token for the given OAuthArgument from the cache. If
221-
// the token is expired, it is refreshed using the refresh token.
226+
// the token is expired or close to expiry, it is refreshed using the refresh
227+
// token.
222228
//
223229
// When a profile is set, lookup is by profile key first. If the profile key is
224230
// not found and the OAuthArgument implements HostCacheKeyProvider, a fallback
@@ -244,11 +250,13 @@ func (a *PersistentAuth) Token() (t *oauth2.Token, err error) {
244250
if err != nil {
245251
return nil, fmt.Errorf("cache: %w", err)
246252
}
247-
// refresh if invalid
248-
if !t.Valid() {
249-
t, err = a.refresh(t)
250-
if err != nil {
253+
if needsRefresh(t) {
254+
if refreshedToken, err := a.refresh(t); err == nil {
255+
t = refreshedToken
256+
} else if !t.Valid() {
251257
return nil, fmt.Errorf("token refresh: %w", err)
258+
} else {
259+
logger.Debugf(a.ctx, "proactive token refresh failed, returning existing token: %v", err)
252260
}
253261
}
254262

@@ -258,19 +266,31 @@ func (a *PersistentAuth) Token() (t *oauth2.Token, err error) {
258266
return t, nil
259267
}
260268

269+
// needsRefresh returns true when the token should be refreshed, either because
270+
// it is no longer valid or because it will expire within the
271+
// tokenRefreshBuffer window.
272+
func needsRefresh(t *oauth2.Token) bool {
273+
if !t.Valid() {
274+
return true
275+
}
276+
return !t.Expiry.IsZero() && time.Until(t.Expiry) < tokenRefreshBuffer
277+
}
278+
261279
// refresh refreshes the token for the given OAuthArgument, storing the new
262280
// token in the cache.
263281
func (a *PersistentAuth) refresh(oldToken *oauth2.Token) (*oauth2.Token, error) {
264-
// OAuth2 config is invoked only for expired tokens to speed up
265-
// the happy path in the token retrieval
266282
cfg, err := a.oauth2Config()
267283
if err != nil {
268284
return nil, err
269285
}
270-
// make OAuth2 library use our client
271286
ctx := a.setOAuthContext(a.ctx)
272-
// eagerly refresh token
273-
t, err := cfg.TokenSource(ctx, oldToken).Token()
287+
// Force the oauth2 library to refresh by ensuring the token appears
288+
// expired. PersistentAuth owns the refresh decision (including the
289+
// proactive buffer), so the oauth2 library should always perform the
290+
// refresh when asked.
291+
expired := *oldToken
292+
expired.Expiry = time.Now().Add(-time.Minute)
293+
t, err := cfg.TokenSource(ctx, &expired).Token()
274294
if err != nil {
275295
// The default RoundTripper of our httpclient.ApiClient returns an error
276296
// if the response status code is not 2xx. This isn't compliant with the

‎credentials/u2m/persistent_auth_test.go‎

Lines changed: 193 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ func TestToken(t *testing.T) {
3838
}
3939
return &oauth2.Token{
4040
AccessToken: "bcd",
41-
Expiry: time.Now().Add(1 * time.Minute),
41+
Expiry: time.Now().Add(1 * time.Hour),
4242
}, nil
4343
},
4444
}
@@ -74,7 +74,7 @@ func TestToken_WithProfile(t *testing.T) {
7474
}
7575
return &oauth2.Token{
7676
AccessToken: "profile-token",
77-
Expiry: time.Now().Add(1 * time.Minute),
77+
Expiry: time.Now().Add(1 * time.Hour),
7878
}, nil
7979
},
8080
}
@@ -112,7 +112,7 @@ func TestToken_WithProfile_FallbackToHostKey(t *testing.T) {
112112
if key == hostKey {
113113
return &oauth2.Token{
114114
AccessToken: "host-token",
115-
Expiry: time.Now().Add(1 * time.Minute),
115+
Expiry: time.Now().Add(1 * time.Hour),
116116
}, nil
117117
}
118118
t.Fatalf("lookup(): unexpected key %q", key)
@@ -187,7 +187,7 @@ func TestToken_NoProfile_NoFallbackAttempted(t *testing.T) {
187187
}
188188
return &oauth2.Token{
189189
AccessToken: "host-token",
190-
Expiry: time.Now().Add(1 * time.Minute),
190+
Expiry: time.Now().Add(1 * time.Hour),
191191
}, nil
192192
},
193193
}
@@ -544,6 +544,195 @@ func TestToken_RefreshesExpiredAccessToken(t *testing.T) {
544544
}
545545
}
546546

547+
func TestToken_RefreshesTokenExpiringSoon(t *testing.T) {
548+
ctx := context.Background()
549+
expectedKey := "https://accounts.cloud.databricks.com/oidc/accounts/xyz"
550+
c := &tokenCacheMock{
551+
lookup: func(key string) (*oauth2.Token, error) {
552+
if key != expectedKey {
553+
t.Fatalf("lookup(): want key %s, got %s", expectedKey, key)
554+
}
555+
return &oauth2.Token{
556+
AccessToken: "expiring-soon",
557+
RefreshToken: "cde",
558+
Expiry: time.Now().Add(4 * time.Minute),
559+
}, nil
560+
},
561+
store: func(key string, tok *oauth2.Token) error {
562+
return nil
563+
},
564+
}
565+
arg, err := NewBasicAccountOAuthArgument("https://accounts.cloud.databricks.com", "xyz")
566+
if err != nil {
567+
t.Fatalf("NewBasicAccountOAuthArgument(): want no error, got %v", err)
568+
}
569+
p, err := NewPersistentAuth(
570+
ctx,
571+
WithTokenCache(c),
572+
WithHttpClient(&http.Client{
573+
Transport: fixtures.SliceTransport{
574+
{
575+
Method: "POST",
576+
Resource: "/oidc/accounts/xyz/v1/token",
577+
Response: `access_token=refreshed&refresh_token=def`,
578+
ResponseHeaders: map[string][]string{
579+
"Content-Type": {"application/x-www-form-urlencoded"},
580+
},
581+
},
582+
},
583+
}),
584+
WithOAuthEndpointSupplier(MockOAuthEndpointSupplier{}),
585+
WithOAuthArgument(arg),
586+
)
587+
if err != nil {
588+
t.Fatalf("NewPersistentAuth(): want no error, got %v", err)
589+
}
590+
defer p.Close()
591+
592+
tok, err := p.Token()
593+
if err != nil {
594+
t.Fatalf("p.Token(): want no error, got %v", err)
595+
}
596+
if tok.AccessToken != "refreshed" {
597+
t.Errorf("p.Token(): want access token 'refreshed', got %s", tok.AccessToken)
598+
}
599+
}
600+
601+
func TestToken_ReturnsStillValidTokenWhenProactiveRefreshFails(t *testing.T) {
602+
ctx := context.Background()
603+
expectedKey := "https://accounts.cloud.databricks.com/oidc/accounts/xyz"
604+
transport := fixtures.SliceTransport{
605+
{
606+
Method: "POST",
607+
Resource: "/oidc/accounts/xyz/v1/token",
608+
Response: `{"error": "temporarily_unavailable", "error_description": "temporarily unavailable"}`,
609+
Status: 503,
610+
},
611+
}
612+
c := &tokenCacheMock{
613+
lookup: func(key string) (*oauth2.Token, error) {
614+
if key != expectedKey {
615+
t.Fatalf("lookup(): want key %s, got %s", expectedKey, key)
616+
}
617+
return &oauth2.Token{
618+
AccessToken: "still-valid",
619+
RefreshToken: "cde",
620+
Expiry: time.Now().Add(4 * time.Minute),
621+
}, nil
622+
},
623+
store: func(key string, tok *oauth2.Token) error {
624+
t.Fatalf("store(): unexpected call - refresh should not succeed")
625+
return nil
626+
},
627+
}
628+
arg, err := NewBasicAccountOAuthArgument("https://accounts.cloud.databricks.com", "xyz")
629+
if err != nil {
630+
t.Fatalf("NewBasicAccountOAuthArgument(): want no error, got %v", err)
631+
}
632+
p, err := NewPersistentAuth(
633+
ctx,
634+
WithTokenCache(c),
635+
WithHttpClient(&http.Client{Transport: transport}),
636+
WithOAuthEndpointSupplier(MockOAuthEndpointSupplier{}),
637+
WithOAuthArgument(arg),
638+
)
639+
if err != nil {
640+
t.Fatalf("NewPersistentAuth(): want no error, got %v", err)
641+
}
642+
defer p.Close()
643+
644+
tok, err := p.Token()
645+
if err != nil {
646+
t.Fatalf("p.Token(): want no error, got %v", err)
647+
}
648+
if tok.AccessToken != "still-valid" {
649+
t.Errorf("p.Token(): want access token 'still-valid', got %s", tok.AccessToken)
650+
}
651+
if tok.RefreshToken != "" {
652+
t.Errorf("p.Token(): want refresh token '', got %s", tok.RefreshToken)
653+
}
654+
if transport[0].Method != "" {
655+
t.Errorf("refresh(): want proactive refresh attempt, but request was not sent")
656+
}
657+
}
658+
659+
func TestToken_DoesNotRefreshTokenNotExpiringSoon(t *testing.T) {
660+
transport := fixtures.SliceTransport{}
661+
c := &tokenCacheMock{
662+
lookup: func(key string) (*oauth2.Token, error) {
663+
return &oauth2.Token{
664+
AccessToken: "still-valid",
665+
Expiry: time.Now().Add(6 * time.Minute),
666+
}, nil
667+
},
668+
store: func(key string, tok *oauth2.Token) error {
669+
t.Fatalf("store(): unexpected call — token should not be refreshed")
670+
return nil
671+
},
672+
}
673+
arg, err := NewBasicAccountOAuthArgument("https://accounts.cloud.databricks.com", "xyz")
674+
if err != nil {
675+
t.Fatalf("NewBasicAccountOAuthArgument(): want no error, got %v", err)
676+
}
677+
p, err := NewPersistentAuth(
678+
context.Background(),
679+
WithTokenCache(c),
680+
WithHttpClient(&http.Client{Transport: transport}),
681+
WithOAuthEndpointSupplier(MockOAuthEndpointSupplier{}),
682+
WithOAuthArgument(arg),
683+
)
684+
if err != nil {
685+
t.Fatalf("NewPersistentAuth(): want no error, got %v", err)
686+
}
687+
defer p.Close()
688+
689+
tok, err := p.Token()
690+
if err != nil {
691+
t.Fatalf("p.Token(): want no error, got %v", err)
692+
}
693+
if tok.AccessToken != "still-valid" {
694+
t.Errorf("p.Token(): want access token 'still-valid', got %s", tok.AccessToken)
695+
}
696+
}
697+
698+
func TestToken_ZeroExpiryDoesNotTriggerRefresh(t *testing.T) {
699+
transport := fixtures.SliceTransport{}
700+
c := &tokenCacheMock{
701+
lookup: func(key string) (*oauth2.Token, error) {
702+
return &oauth2.Token{
703+
AccessToken: "no-expiry",
704+
}, nil
705+
},
706+
store: func(key string, tok *oauth2.Token) error {
707+
t.Fatalf("store(): unexpected call — zero-expiry token should not be refreshed")
708+
return nil
709+
},
710+
}
711+
arg, err := NewBasicAccountOAuthArgument("https://accounts.cloud.databricks.com", "xyz")
712+
if err != nil {
713+
t.Fatalf("NewBasicAccountOAuthArgument(): want no error, got %v", err)
714+
}
715+
p, err := NewPersistentAuth(
716+
context.Background(),
717+
WithTokenCache(c),
718+
WithHttpClient(&http.Client{Transport: transport}),
719+
WithOAuthEndpointSupplier(MockOAuthEndpointSupplier{}),
720+
WithOAuthArgument(arg),
721+
)
722+
if err != nil {
723+
t.Fatalf("NewPersistentAuth(): want no error, got %v", err)
724+
}
725+
defer p.Close()
726+
727+
tok, err := p.Token()
728+
if err != nil {
729+
t.Fatalf("p.Token(): want no error, got %v", err)
730+
}
731+
if tok.AccessToken != "no-expiry" {
732+
t.Errorf("p.Token(): want access token 'no-expiry', got %s", tok.AccessToken)
733+
}
734+
}
735+
547736
func TestToken_ReturnsError(t *testing.T) {
548737
ctx := context.Background()
549738
cache := &tokenCacheMock{

0 commit comments

Comments
 (0)