Make secure token storage the default storage mode

simonfaltum · simonfaltum · commit 9cee127ab0d0 · 2026-05-19T16:00:15.000+02:00
U2M tokens for the databricks-cli auth type now write to the OS-native
keyring by default. Users who need the previous file-backed cache can
opt back via DATABRICKS_AUTH_STORAGE=plaintext or auth_storage =
plaintext under [__settings__] in .databrickscfg; the env var takes
precedence. The login-time keyring probe and fallback (already on main)
activate with this change.

Co-authored-by: Isaac
diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Notable Changes
 
+* Breaking change: U2M (`auth_type = databricks-cli`) tokens are now stored in the OS-native secure store by default (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) instead of `~/.databricks/token-cache.json`. After upgrading, run `databricks auth login` once per profile to re-authenticate; cached tokens from older versions are not migrated. To keep the previous file-backed storage, set `DATABRICKS_AUTH_STORAGE=plaintext` or add `auth_storage = plaintext` under `[__settings__]` in `~/.databrickscfg` (the env var takes precedence over the config setting), then re-run `databricks auth login`.
+
 ### CLI
 
 * Added `databricks aitools` command group for installing Databricks skills into your coding agents (Claude Code, Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity). Skills are fetched from [github.com/databricks/databricks-agent-skills](https://github.com/databricks/databricks-agent-skills) and either symlinked into each agent's skills directory or copied into the current project. Use `databricks aitools install` to set up, `update` to pull newer versions, `list` to see what's available, and `uninstall` to remove them.
diff --git a/acceptance/cmd/auth/describe/u2m-json-output/output.txt b/acceptance/cmd/auth/describe/u2m-json-output/output.txt
@@ -2,7 +2,7 @@
 >>> [CLI] auth describe --profile u2m-profile --output json
 Warn: [hostmetadata] failed to fetch host metadata for https://u2m-profile.databricks.test, will skip for 1m0s
 {
-  "mode": "plaintext",
-  "location": "~/.databricks/token-cache.json",
+  "mode": "secure",
+  "location": "OS keyring (service: databricks-cli)",
   "source": "default"
 }
diff --git a/acceptance/cmd/auth/describe/u2m-plaintext-default/test.toml b/acceptance/cmd/auth/describe/u2m-plaintext-default/test.toml
diff --git a/acceptance/cmd/auth/describe/u2m-secure-default/out.test.toml b/acceptance/cmd/auth/describe/u2m-secure-default/out.test.toml
diff --git a/acceptance/cmd/auth/describe/u2m-secure-default/output.txt b/acceptance/cmd/auth/describe/u2m-secure-default/output.txt
@@ -1,8 +1,8 @@
 
 >>> [CLI] auth describe --profile u2m-profile
 Warn: [hostmetadata] failed to fetch host metadata for https://u2m-profile.databricks.test, will skip for 1m0s
-Unable to authenticate: error getting token: cache: token not found
-Token storage: plaintext, ~/.databricks/token-cache.json (from default)
+Unable to authenticate: error getting token: [KEYRING_LOOKUP_ERROR]
+Token storage: secure, OS keyring (service: databricks-cli) (from default)
 -----
 Current configuration:
   ✓ host: https://u2m-profile.databricks.test (from ./home/.databrickscfg config file)
diff --git a/acceptance/cmd/auth/describe/u2m-secure-default/script b/acceptance/cmd/auth/describe/u2m-secure-default/script
diff --git a/acceptance/cmd/auth/describe/u2m-secure-default/test.toml b/acceptance/cmd/auth/describe/u2m-secure-default/test.toml
@@ -0,0 +1,11 @@
+Ignore = [
+    "home"
+]
+
+# Normalize the platform-specific keyring lookup error. macOS returns
+# cache.ErrNotFound for a clean miss; Linux without D-Bus returns a
+# backend-specific error. The point of this test is the resolved storage
+# mode, not the lookup outcome.
+[[Repls]]
+Old = 'Unable to authenticate: error getting token: .*'
+New = 'Unable to authenticate: error getting token: [KEYRING_LOOKUP_ERROR]'
diff --git a/acceptance/script.prepare b/acceptance/script.prepare
@@ -1,3 +1,9 @@
+# Force plaintext token storage so acceptance tests exercise the file-backed
+# cache rather than the OS keyring, which is not reliably reachable in CI.
+# Tests that want to exercise the secure path or the resolver default unset
+# or override this in their own script.prepare or script.
+export DATABRICKS_AUTH_STORAGE=plaintext
+
 errcode() {
     # Temporarily disable 'set -e' to prevent the script from exiting on error
     set +e
diff --git a/cmd/auth/describe_test.go b/cmd/auth/describe_test.go
@@ -240,21 +240,21 @@ func TestResolveTokenStorageInfo(t *testing.T) {
 			want:     nil,
 		},
 		{
-			name:     "databricks-cli with default plaintext",
+			name:     "databricks-cli with default secure",
 			authType: authTypeDatabricksCLI,
 			want: &tokenStorageInfo{
-				Mode:     "plaintext",
-				Location: plaintextLocation,
+				Mode:     "secure",
+				Location: secureLocation,
 				Source:   "default",
 			},
 		},
 		{
-			name:     "databricks-cli with secure from env",
+			name:     "databricks-cli with plaintext from env",
 			authType: authTypeDatabricksCLI,
-			envValue: "secure",
+			envValue: "plaintext",
 			want: &tokenStorageInfo{
-				Mode:     "secure",
-				Location: secureLocation,
+				Mode:     "plaintext",
+				Location: plaintextLocation,
 				Source:   "DATABRICKS_AUTH_STORAGE environment variable",
 			},
 		},
diff --git a/libs/auth/storage/cache.go b/libs/auth/storage/cache.go
@@ -59,10 +59,6 @@ func ResolveCache(ctx context.Context, override StorageMode) (cache.TokenCache,
 //     The timeout is ambiguous (locked vs hung); a misdiagnosis fails
 //     the final Store rather than silently downgrading to plaintext.
 //
-// Rules 1 and 2 are dormant today: the resolver default is plaintext, so
-// (mode=Secure, explicit=false) is unreachable. They activate when the
-// default flips to secure at GA.
-//
 // Login-specific. Read paths (auth token, bundle commands) keep the original
 // keyring error so they don't silently mint plaintext copies of tokens that
 // were stored in the keyring on another machine.
@@ -120,12 +116,6 @@ func resolveCacheForLoginWith(ctx context.Context, override StorageMode, f cache
 // resolved mode and whether the user explicitly asked for it. Split out so
 // tests can drive the (mode, explicit) input space directly without depending
 // on whatever the resolver's default mode happens to be at any point in time.
-//
-// Pin-on-success across modes (locking in the first working behavior to
-// insulate users from keyring flakiness) is intentionally not implemented
-// here. It lands at GA alongside the default flip; pinning before the
-// flip would freeze every default user into plaintext and make the flip a
-// no-op for them.
 func applyLoginFallback(ctx context.Context, mode StorageMode, explicit bool, f cacheFactories) (cache.TokenCache, StorageMode, error) {
 	switch mode {
 	case StorageModePlaintext:
@@ -168,11 +158,9 @@ func applyLoginFallback(ctx context.Context, mode StorageMode, explicit bool, f
 // in .databrickscfg so subsequent commands skip the (slow/blocking) keyring
 // probe and route straight to the file cache.
 //
-// Only called on the (mode=Secure, explicit=false) probe-failure branch. That
-// branch is unreachable today (resolver default is plaintext), so this is
-// dormant infrastructure: it activates when the default flips to secure
-// at GA and lets default-on-broken-keyring users avoid a 3s probe on every
-// command.
+// Only called on the (mode=Secure, explicit=false) probe-failure branch.
+// Persisting the fallback lets default-on-broken-keyring users avoid a 3s
+// probe on every command.
 func persistPlaintextFallback(ctx context.Context) error {
 	configPath := env.Get(ctx, "DATABRICKS_CONFIG_FILE")
 	return databrickscfg.SetConfiguredAuthStorage(ctx, string(StorageModePlaintext), configPath)
diff --git a/libs/auth/storage/cache_test.go b/libs/auth/storage/cache_test.go
@@ -41,15 +41,15 @@ func hermetic(t *testing.T) {
 	t.Setenv("DATABRICKS_CONFIG_FILE", filepath.Join(t.TempDir(), "databrickscfg"))
 }
 
-func TestResolveCache_DefaultsToPlaintextFile(t *testing.T) {
+func TestResolveCache_DefaultsToSecureKeyring(t *testing.T) {
 	hermetic(t)
 	ctx := t.Context()
 
 	got, mode, err := resolveCacheWith(ctx, "", fakeFactories(t))
 
 	require.NoError(t, err)
-	assert.Equal(t, StorageModePlaintext, mode)
-	assert.Equal(t, "file", got.(stubCache).source)
+	assert.Equal(t, StorageModeSecure, mode)
+	assert.Equal(t, "keyring", got.(stubCache).source)
 }
 
 func TestResolveCache_OverrideSecureUsesKeyring(t *testing.T) {
diff --git a/libs/auth/storage/mode.go b/libs/auth/storage/mode.go
@@ -1,9 +1,10 @@
 // Package storage selects and constructs the CLI's U2M token storage backend.
 //
-// Two modes are supported. Plaintext writes to ~/.databricks/token-cache.json
-// with host-key dual-write for older Go SDK versions (v0.61-v0.103); it is the
-// resolver default. Secure writes to the OS-native keyring under the profile
-// cache key only; it is opt-in pre-GA and slated to become the default at GA.
+// Two modes are supported. Secure writes to the OS-native keyring under the
+// profile cache key only; it is the resolver default. Plaintext writes to
+// ~/.databricks/token-cache.json with host-key dual-write for older Go SDK
+// versions (v0.61-v0.103); it is the opt-in fallback for environments where
+// the OS keyring is not available.
 package storage
 
 import (
@@ -26,12 +27,15 @@ const (
 
 	// StorageModePlaintext writes tokens to ~/.databricks/token-cache.json
 	// and mirrors each token under the legacy host-based cache key for
-	// older Go SDK versions (v0.61-v0.103). This is the resolver default.
+	// older Go SDK versions (v0.61-v0.103). Opt-in via DATABRICKS_AUTH_STORAGE
+	// or [__settings__].auth_storage for environments where the OS keyring
+	// is not available.
 	StorageModePlaintext StorageMode = "plaintext"
 
 	// StorageModeSecure writes tokens to the OS-native secure store
 	// (macOS Keychain, Windows Credential Manager, Linux Secret Service)
 	// under the profile cache key only. No host-key entry is written.
+	// This is the resolver default.
 	StorageModeSecure StorageMode = "secure"
 )
 
@@ -101,7 +105,7 @@ func ParseMode(raw string) StorageMode {
 //  1. override (typically from a command-level flag such as --secure-storage).
 //  2. DATABRICKS_AUTH_STORAGE env var.
 //  3. [__settings__].auth_storage in .databrickscfg.
-//  4. StorageModePlaintext.
+//  4. StorageModeSecure.
 //
 // StorageModeUnknown as override means "no flag set; fall through." The
 // override is trusted to be a valid StorageMode: callers that parse user
@@ -138,7 +142,7 @@ func ResolveStorageModeWithSource(ctx context.Context, override StorageMode) (St
 		return mode, StorageSourceConfig, err
 	}
 
-	return StorageModePlaintext, StorageSourceDefault, nil
+	return StorageModeSecure, StorageSourceDefault, nil
 }
 
 func parseFromSource(raw, source string) (StorageMode, error) {
diff --git a/libs/auth/storage/mode_test.go b/libs/auth/storage/mode_test.go
@@ -41,7 +41,7 @@ func TestResolveStorageMode(t *testing.T) {
 	}{
 		{
 			name: "default when nothing is set",
-			want: StorageModePlaintext,
+			want: StorageModeSecure,
 		},
 		{
 			name:       "override wins over env and config",
@@ -63,8 +63,8 @@ func TestResolveStorageMode(t *testing.T) {
 		},
 		{
 			name:       "config sets mode when env and override unset",
-			configBody: "[__settings__]\nauth_storage = secure\n",
-			want:       StorageModeSecure,
+			configBody: "[__settings__]\nauth_storage = plaintext\n",
+			want:       StorageModePlaintext,
 		},
 		{
 			name:     "env value is case-insensitive and trimmed",
@@ -141,19 +141,19 @@ func TestResolveStorageModeWithSource(t *testing.T) {
 	}{
 		{
 			name:       "default",
-			wantMode:   StorageModePlaintext,
+			wantMode:   StorageModeSecure,
 			wantSource: StorageSourceDefault,
 		},
 		{
 			name:       "override",
-			override:   StorageModeSecure,
-			wantMode:   StorageModeSecure,
+			override:   StorageModePlaintext,
+			wantMode:   StorageModePlaintext,
 			wantSource: StorageSourceOverride,
 		},
 		{
 			name:       "env",
-			envValue:   "secure",
-			wantMode:   StorageModeSecure,
+			envValue:   "plaintext",
+			wantMode:   StorageModePlaintext,
 			wantSource: StorageSourceEnvVar,
 		},
 		{

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`	`>>> [CLI] auth describe --profile u2m-profile --output json`
`3`	`3`	`Warn: [hostmetadata] failed to fetch host metadata for https://u2m-profile.databricks.test, will skip for 1m0s`
`4`	`4`	`{`
`5`		`- "mode": "plaintext",`
`6`		`- "location": "~/.databricks/token-cache.json",`
	`5`	`+ "mode": "secure",`
	`6`	`+ "location": "OS keyring (service: databricks-cli)",`
`7`	`7`	`"source": "default"`
`8`	`8`	`}`