feat(auth): add --experimental-auth-token-file for short-lived OAuth2 access tokens

cfg/config.go

@@ -594,6 +594,8 @@ type FileSystemConfig struct {
 type GcsAuthConfig struct {
 	AnonymousAccess bool `yaml:"anonymous-access"`
 
+	ExperimentalAuthTokenFile ResolvedPath `yaml:"experimental-auth-token-file"`
+
 	KeyFile ResolvedPath `yaml:"key-file"`
 
 	ReuseTokenFromUrl bool `yaml:"reuse-token-from-url"`
@@ -1027,6 +1029,8 @@ func BuildFlagSet(flagSet *pflag.FlagSet) error {
 		return err
 	}
 
+	flagSet.StringP("experimental-auth-token-file", "", "", "Experimental: Absolute path to a file containing an OAuth2 token response in JSON format ({\"access_token\": \"...\", \"expires_in\": 3600, \"token_type\": \"Bearer\"}), to be used directly as the GCS credential. Mounting fails if the token is expired. The file is re-read when the token expires, so an external process may refresh the credential by rewriting the file.")
+
 	flagSet.BoolP("experimental-enable-dentry-cache", "", false, "When enabled, it sets the Dentry cache entry timeout same as metadata-cache-ttl. This enables kernel to use cached entry to map the file paths to inodes, instead of making LookUpInode calls to GCSFuse.")
 
 	if err := flagSet.MarkHidden("experimental-enable-dentry-cache"); err != nil {
@@ -1640,6 +1644,10 @@ func BindFlags(v *viper.Viper, flagSet *pflag.FlagSet) error {
 		return err
 	}
 
+	if err := v.BindPFlag("gcs-auth.experimental-auth-token-file", flagSet.Lookup("experimental-auth-token-file")); err != nil {
+		return err
+	}
+
 	if err := v.BindPFlag("file-system.experimental-enable-dentry-cache", flagSet.Lookup("experimental-enable-dentry-cache")); err != nil {
 		return err
 	}

cfg/params.yaml

@@ -583,6 +583,16 @@ params:
     usage: "This flag disables authentication."
     default: false
 
+  - config-path: "gcs-auth.experimental-auth-token-file"
+    flag-name: "experimental-auth-token-file"
+    type: "resolvedPath"
+    usage: >-
+      Experimental: Absolute path to a file containing an OAuth2 token response
+      in JSON format ({"access_token": "...", "expires_in": 3600, "token_type":
+      "Bearer"}), to be used directly as the GCS credential. Mounting fails if
+      the token is expired. The file is re-read when the token expires, so an
+      external process may refresh the credential by rewriting the file.
+
   - config-path: "gcs-auth.key-file"
     flag-name: "key-file"
     type: "resolvedPath"

cfg/validate.go

@@ -318,6 +318,18 @@ func isValidOptimizationProfile(config *Config) error {
 	return nil
 }
 
+func isValidGcsAuthConfig(config *GcsAuthConfig) error {
+	if config.ExperimentalAuthTokenFile != "" {
+		if config.KeyFile != "" {
+			return fmt.Errorf("experimental-auth-token-file cannot be used together with key-file")
+		}
+		if config.TokenUrl != "" {
+			return fmt.Errorf("experimental-auth-token-file cannot be used together with token-url")
+		}
+	}
+	return nil
+}
+
 // ValidateConfig returns a non-nil error if the config is invalid.
 func ValidateConfig(v *viper.Viper, config *Config) error {
 	var err error
@@ -342,6 +354,10 @@ func ValidateConfig(v *viper.Viper, config *Config) error {
 		return fmt.Errorf("error parsing token-url config: %w", err)
 	}
 
+	if err = isValidGcsAuthConfig(&config.GcsAuth); err != nil {
+		return fmt.Errorf("error parsing gcs-auth config: %w", err)
+	}
+
 	if err = isValidSequentialReadSizeMB(config.GcsConnection.SequentialReadSizeMb); err != nil {
 		return fmt.Errorf("error parsing gcs-connection config: %w", err)
 	}

cfg/validate_test.go

@@ -88,6 +88,29 @@ func TestValidateConfigSuccessful(t *testing.T) {
 				},
 			},
 		},
+		{
+			name: "Valid Config with experimental-auth-token-file set.",
+			config: &Config{
+				Logging:   LoggingConfig{LogRotate: validLogRotateConfig()},
+				FileCache: validFileCacheConfig(t),
+				GcsAuth: GcsAuthConfig{
+					ExperimentalAuthTokenFile: "/token.json",
+				},
+				GcsConnection: GcsConnectionConfig{
+					SequentialReadSizeMb: 200,
+				},
+				MetadataCache: MetadataCacheConfig{
+					ExperimentalMetadataPrefetchOnMount: "disabled",
+				},
+				Metrics: MetricsConfig{
+					Workers:    3,
+					BufferSize: 256,
+				},
+				Mrd: MrdConfig{
+					PoolSize: 4,
+				},
+			},
+		},
 		{
 			name: "Valid Config where input and expected custom endpoint differ.",
 			config: &Config{
@@ -455,6 +478,40 @@ func TestValidateConfig_ErrorScenarios(t *testing.T) {
 				},
 			},
 		},
+		{
+			name: "Invalid Config due to experimental-auth-token-file set together with key-file",
+			config: &Config{
+				Logging:   LoggingConfig{LogRotate: validLogRotateConfig()},
+				FileCache: validFileCacheConfig(t),
+				GcsAuth: GcsAuthConfig{
+					ExperimentalAuthTokenFile: "/token.json",
+					KeyFile:                   "/key.json",
+				},
+				MetadataCache: MetadataCacheConfig{
+					ExperimentalMetadataPrefetchOnMount: "sync",
+				},
+				GcsConnection: GcsConnectionConfig{
+					SequentialReadSizeMb: 200,
+				},
+			},
+		},
+		{
+			name: "Invalid Config due to experimental-auth-token-file set together with token-url",
+			config: &Config{
+				Logging:   LoggingConfig{LogRotate: validLogRotateConfig()},
+				FileCache: validFileCacheConfig(t),
+				GcsAuth: GcsAuthConfig{
+					ExperimentalAuthTokenFile: "/token.json",
+					TokenUrl:                  "https://www.abc.com",
+				},
+				MetadataCache: MetadataCacheConfig{
+					ExperimentalMetadataPrefetchOnMount: "sync",
+				},
+				GcsConnection: GcsConnectionConfig{
+					SequentialReadSizeMb: 200,
+				},
+			},
+		},
 		{
 			name: "Sequential read size MB more than 1024 (max permissible value)",
 			config: &Config{

cmd/legacy_main.go

@@ -154,6 +154,7 @@ func createStorageHandle(newConfig *cfg.Config, userAgent string, metricHandle m
 		UserAgent:                               userAgent,
 		CustomEndpoint:                          newConfig.GcsConnection.CustomEndpoint,
 		KeyFile:                                 string(newConfig.GcsAuth.KeyFile),
+		ExperimentalAuthTokenFile:               string(newConfig.GcsAuth.ExperimentalAuthTokenFile),
 		AnonymousAccess:                         newConfig.GcsAuth.AnonymousAccess,
 		TokenUrl:                                newConfig.GcsAuth.TokenUrl,
 		ReuseTokenFromUrl:                       newConfig.GcsAuth.ReuseTokenFromUrl,

cmd/root_test.go

@@ -753,15 +753,26 @@ func TestArgsParsing_GCSAuthFlags(t *testing.T) {
 				},
 			},
 		},
+		{
+			name: "Test experimental-auth-token-file flag.",
+			args: []string{"gcsfuse", "--experimental-auth-token-file=token.json", "abc", "pqr"},
+			expectedConfig: &cfg.Config{
+				GcsAuth: cfg.GcsAuthConfig{
+					ExperimentalAuthTokenFile: cfg.ResolvedPath(path.Join(wd, "token.json")),
+					ReuseTokenFromUrl:         true,
+				},
+			},
+		},
 		{
 			name: "Test default gcs auth flags.",
 			args: []string{"gcsfuse", "abc", "pqr"},
 			expectedConfig: &cfg.Config{
 				GcsAuth: cfg.GcsAuthConfig{
-					AnonymousAccess:   false,
-					KeyFile:           "",
-					ReuseTokenFromUrl: true,
-					TokenUrl:          "",
+					AnonymousAccess:           false,
+					KeyFile:                   "",
+					ExperimentalAuthTokenFile: "",
+					ReuseTokenFromUrl:         true,
+					TokenUrl:                  "",
 				},
 			},
 		},
@@ -804,6 +815,14 @@ func TestArgsParsing_GCSAuthFlagsThrowsError(t *testing.T) {
 			name: "Invalid value for token-url flag",
 			args: []string{"gcsfuse", "--token-url=a_b://abc", "abc", "pqr"},
 		},
+		{
+			name: "experimental-auth-token-file set together with key-file",
+			args: []string{"gcsfuse", "--experimental-auth-token-file=token.json", "--key-file=key.file", "abc", "pqr"},
+		},
+		{
+			name: "experimental-auth-token-file set together with token-url",
+			args: []string{"gcsfuse", "--experimental-auth-token-file=token.json", "--token-url=www.abc.com", "abc", "pqr"},
+		},
 	}
 
 	for _, tc := range tests {

internal/auth/auth.go

@@ -88,14 +88,18 @@ func newTokenSourceFromPath(ctx context.Context, path string, scope string) (oau
 func GetTokenSource(
 	ctx context.Context,
 	keyFile string,
+	tokenFile string,
 	tokenUrl string,
 	reuseTokenFromUrl bool,
 ) (tokenSrc oauth2.TokenSource, err error) {
 	// Create the oauth2 token source.
 	const scope = storagev1.DevstorageFullControlScope
 	var method string
 
-	if keyFile != "" {
+	if tokenFile != "" {
+		tokenSrc, err = NewTokenSourceFromTokenFile(tokenFile)
+		method = "NewTokenSourceFromTokenFile"
+	} else if keyFile != "" {
 		tokenSrc, err = newTokenSourceFromPath(ctx, keyFile, scope)
 		method = "newTokenSourceFromPath"
 	} else if tokenUrl != "" {

internal/auth/file_token_source.go

@@ -0,0 +1,69 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package auth
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"time"
+
+	"golang.org/x/oauth2"
+)
+
+// fileTokenSource is an oauth2.TokenSource that reads an OAuth2 token
+// response from a JSON file on disk.
+type fileTokenSource struct {
+	path string
+}
+
+func (ts fileTokenSource) Token() (*oauth2.Token, error) {
+	contents, err := os.ReadFile(ts.path)
+	if err != nil {
+		return nil, fmt.Errorf("fileTokenSource cannot read token file: %w", err)
+	}
+
+	token := &oauth2.Token{}
+	if err := json.Unmarshal(contents, token); err != nil {
+		return nil, fmt.Errorf("fileTokenSource cannot decode token file %q: %w", ts.path, err)
+	}
+
+	// The expires_in field is relative, so anchor it to the time the file was
+	// read to get an absolute expiry. An absolute expiry field, if present in
+	// the file, takes precedence.
+	if token.Expiry.IsZero() && token.ExpiresIn > 0 {
+		token.Expiry = time.Now().Add(time.Duration(token.ExpiresIn) * time.Second)
+	}
+	if !token.Valid() {
+		return nil, fmt.Errorf("token file %q contains an invalid or expired token", ts.path)
+	}
+
+	return token, nil
+}
+
+// NewTokenSourceFromTokenFile returns a TokenSource backed by a file
+// containing an OAuth2 token response in JSON format, e.g.
+// {"access_token": "...", "expires_in": 3600, "token_type": "Bearer"}.
+// The file is read eagerly so that an invalid or expired token fails at mount
+// time, and re-read when the token expires, so an external process may
+// refresh the credential by rewriting the file.
+func NewTokenSourceFromTokenFile(path string) (oauth2.TokenSource, error) {
+	ts := fileTokenSource{path: path}
+	token, err := ts.Token()
+	if err != nil {
+		return nil, err
+	}
+	return oauth2.ReuseTokenSource(token, ts), nil
+}