feat(option): add safer credentials JSON loading options

Add option.WithAuthCredentialsFile and option.WithAuthCredentialsJSON
to mitigate a security vulnerability where credential configurations
from untrusted sources could be used without validation. These new
functions require the credential type to be explicitly specified.

Deprecate the less safe option.WithCredentialsFile and
option.WithCredentialsJSON functions.

Author: quartzmo

README.md

@@ -60,13 +60,22 @@ client, err := sheets.NewService(ctx)
 ```
 
 To authorize using a [JSON key file](https://cloud.google.com/iam/docs/managing-service-account-keys), pass
-[`option.WithCredentialsFile`](https://pkg.go.dev/google.golang.org/api/option#WithCredentialsFile) to the `NewService`
-function of the desired package. For example:
+[`option.WithAuthCredentialsFile`](https://pkg.go.dev/google.golang.org/api/option#WithAuthCredentialsFile) to the `NewService`
+function of the desired package. You must also specify the credential type. For example, to use a service account key file:
 
 ```go
-client, err := sheets.NewService(ctx, option.WithCredentialsFile("path/to/keyfile.json"))
+client, err := sheets.NewService(ctx, option.WithAuthCredentialsFile(option.ServiceAccount, "path/to/keyfile.json"))
 ```
 
+Similarly, you can use JSON credentials directly with [`option.WithAuthCredentialsJSON`](https://pkg.go.dev/google.golang.org/api/option#WithAuthCredentialsJSON):
+
+```go
+// where jsonKey is a []byte containing the JSON key
+client, err := sheets.NewService(ctx, option.WithAuthCredentialsJSON(option.ServiceAccount, jsonKey))
+```
+
+The older `option.WithCredentialsFile` and `option.WithCredentialsJSON` functions are deprecated due to a potential security risk.
+
 You can exert more control over authorization by using the [`golang.org/x/oauth2`](https://pkg.go.dev/golang.org/x/oauth2)
 package to create an `oauth2.TokenSource`. Then pass [`option.WithTokenSource`](https://pkg.go.dev/google.golang.org/api/option#WithTokenSource)
 to the `NewService` function:

idtoken/idtoken.go

@@ -110,11 +110,13 @@ func newTokenSourceNewAuth(ctx context.Context, audience string, ds *internal.Di
 	if ds.AuthCredentials != nil {
 		return nil, fmt.Errorf("idtoken: option.WithTokenProvider not supported")
 	}
+	credsJSON, _ := ds.GetAuthCredentialsJSON()
+	credsFile, _ := ds.GetAuthCredentialsFile()
 	creds, err := newidtoken.NewCredentials(&newidtoken.Options{
 		Audience:        audience,
 		CustomClaims:    ds.CustomClaims,
-		CredentialsFile: ds.CredentialsFile,
-		CredentialsJSON: ds.CredentialsJSON,
+		CredentialsFile: credsFile,
+		CredentialsJSON: credsJSON,
 		Client:          oauth2.NewClient(ctx, nil),
 		Logger:          ds.Logger,
 	})
@@ -233,20 +235,159 @@ func (w withCustomClaims) Apply(o *internal.DialSettings) {
 	o.CustomClaims = w
 }
 
+// CredentialsType specifies the type of JSON credentials being provided
+// to a loading function such as [WithAuthCredentialsFile] or
+// [WithAuthCredentialsJSON].
+type CredentialsType = option.CredentialsType
+
+const (
+	// Unknown represents an unknown JSON file type.
+	//
+	// IMPORTANT:
+	// This credential type does not validate the credential configuration. A security
+	// risk occurs when a credential configuration configured with malicious urls
+	// is used.
+	// You should validate credential configurations provided by untrusted sources.
+	// See [Security requirements when using credential configurations from an external
+	// source] https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
+	// for more details.
+	Unknown = option.Unknown
+	// ServiceAccount represents a service account file type.
+	ServiceAccount = option.ServiceAccount
+	// User represents a user credentials file type.
+	User = option.User
+	// ImpersonatedServiceAccount represents an impersonated service account file type.
+	//
+	// IMPORTANT:
+	// This credential type does not validate the credential configuration. A security
+	// risk occurs when a credential configuration configured with malicious urls
+	// is used.
+	// You should validate credential configurations provided by untrusted sources.
+	// See [Security requirements when using credential configurations from an external
+	// source] https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
+	// for more details.
+	ImpersonatedServiceAccount = option.ImpersonatedServiceAccount
+	// ExternalAccount represents an external account file type.
+	//
+	// IMPORTANT:
+	// This credential type does not validate the credential configuration. A security
+	// risk occurs when a credential configuration configured with malicious urls
+	// is used.
+	// You should validate credential configurations provided by untrusted sources.
+	// See [Security requirements when using credential configurations from an external
+	// source] https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
+	// for more details.
+	ExternalAccount = option.ExternalAccount
+)
+
 // WithCredentialsFile returns a ClientOption that authenticates
 // API calls with the given service account or refresh token JSON
 // credentials file.
+//
+// Important: If you accept a credential configuration (credential
+// JSON/File/Stream) from an external source for authentication to Google
+// Cloud Platform, you must validate it before providing it to any Google
+// API or library. Providing an unvalidated credential configuration to
+// Google APIs can compromise the security of your systems and data. For
+// more information, refer to [Validate credential configurations from
+// external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+//
+// Deprecated:  This function is being deprecated because of a potential security risk.
+//
+// This function does not validate the credential configuration. The security
+// risk occurs when a credential configuration is accepted from a source that
+// is not under your control and used without validation on your side.
+//
+// If you know that you will be loading credential configurations of a
+// specific type, it is recommended to use a credential-type-specific
+// option function.
+// This will ensure that an unexpected credential type with potential for
+// malicious intent is not loaded unintentionally. You might still have to do
+// validation for certain credential types. Please follow the recommendation
+// for that function. For example, if you want to load only service accounts,
+// you can use [WithAuthCredentialsFile] with [ServiceAccount]:
+// ```
+// option.WithAuthCredentialsFile(option.ServiceAccount, "/path/to/file.json")
+// ```
+//
+// If you are loading your credential configuration from an untrusted source and have
+// not mitigated the risks (e.g. by validating the configuration yourself), make
+// these changes as soon as possible to prevent security risks to your environment.
+//
+// Regardless of the function used, it is always your responsibility to validate
+// configurations received from external sources.
 func WithCredentialsFile(filename string) ClientOption {
 	return option.WithCredentialsFile(filename)
 }
 
+// WithAuthCredentialsFile returns a ClientOption that authenticates API calls
+// with the given JSON credentials file and credential type.
+//
+// Important: If you accept a credential configuration (credential
+// JSON/File/Stream) from an external source for authentication to Google
+// Cloud Platform, you must validate it before providing it to any Google
+// API or library. Providing an unvalidated credential configuration to
+// Google APIs can compromise the security of your systems and data. For
+// more information, refer to [Validate credential configurations from
+// external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+func WithAuthCredentialsFile(credType CredentialsType, filename string) ClientOption {
+	return option.WithAuthCredentialsFile(credType, filename)
+}
+
 // WithCredentialsJSON returns a ClientOption that authenticates
 // API calls with the given service account or refresh token JSON
 // credentials.
+//
+// Important: If you accept a credential configuration (credential
+// JSON/File/Stream) from an external source for authentication to Google
+// Cloud Platform, you must validate it before providing it to any Google
+// API or library. Providing an unvalidated credential configuration to
+// Google APIs can compromise the security of your systems and data. For
+// more information, refer to [Validate credential configurations from
+// external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+//
+// Deprecated:  This function is being deprecated because of a potential security risk.
+//
+// This function does not validate the credential configuration. The security
+// risk occurs when a credential configuration is accepted from a source that
+// is not under your control and used without validation on your side.
+//
+// If you know that you will be loading credential configurations of a
+// specific type, it is recommended to use a credential-type-specific
+// option function.
+// This will ensure that an unexpected credential type with potential for
+// malicious intent is not loaded unintentionally. You might still have to do
+// validation for certain credential types. Please follow the recommendation
+// for that function. For example, if you want to load only service accounts,
+// you can use [WithAuthCredentialsJSON] with [ServiceAccount]:
+// ```
+// option.WithAuthCredentialsJSON(option.ServiceAccount, json)
+// ```
+//
+// If you are loading your credential configuration from an untrusted source and have
+// not mitigated the risks (e.g. by validating the configuration yourself), make
+// these changes as soon as possible to prevent security risks to your environment.
+//
+// Regardless of the function used, it is always your responsibility to validate
+// configurations received from external sources.
 func WithCredentialsJSON(p []byte) ClientOption {
 	return option.WithCredentialsJSON(p)
 }
 
+// WithAuthCredentialsJSON returns a ClientOption that authenticates API calls
+// with the given JSON credentials and credential type.
+//
+// Important: If you accept a credential configuration (credential
+// JSON/File/Stream) from an external source for authentication to Google
+// Cloud Platform, you must validate it before providing it to any Google
+// API or library. Providing an unvalidated credential configuration to
+// Google APIs can compromise the security of your systems and data. For
+// more information, refer to [Validate credential configurations from
+// external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+func WithAuthCredentialsJSON(credType CredentialsType, json []byte) ClientOption {
+	return option.WithAuthCredentialsJSON(credType, json)
+}
+
 // WithHTTPClient returns a ClientOption that specifies the HTTP client to use
 // as the basis of communications. This option may only be used with services
 // that support HTTP as their communication transport. When used, the

impersonate/integration_test.go

@@ -87,7 +87,7 @@ func TestCredentialsTokenSourceIntegration(t *testing.T) {
 					Scopes:          []string{"https://www.googleapis.com/auth/devstorage.full_control"},
 					Delegates:       tt.delegates,
 				},
-				option.WithCredentialsFile(tt.baseKeyFile),
+				option.WithAuthCredentialsFile(option.ServiceAccount, tt.baseKeyFile),
 			)
 			if err != nil {
 				t.Fatalf("failed to create ts: %v", err)
@@ -143,7 +143,7 @@ func TestIDTokenSourceIntegration(t *testing.T) {
 					Delegates:       tt.delegates,
 					IncludeEmail:    true,
 				},
-				option.WithCredentialsFile(tt.baseKeyFile),
+				option.WithAuthCredentialsFile(option.ServiceAccount, tt.baseKeyFile),
 			)
 			if err != nil {
 				t.Fatalf("failed to create ts: %v", err)
@@ -198,7 +198,7 @@ func TestTokenSourceIntegration_user(t *testing.T) {
 					Scopes:          []string{"https://www.googleapis.com/auth/admin.directory.user", "https://www.googleapis.com/auth/admin.directory.group"},
 					Subject:         domainAdmin,
 				},
-				option.WithCredentialsFile(baseKeyFile),
+				option.WithAuthCredentialsFile(option.ServiceAccount, baseKeyFile),
 			)
 			if err != nil {
 				t.Fatalf("failed to create ts: %v", err)

integration-tests/byoid/integration_test.go

@@ -129,7 +129,7 @@ func getClientID(keyFileName string) (string, error) {
 }
 
 func generateGoogleToken(keyFileName string) (string, error) {
-	ts, err := idtoken.NewTokenSource(context.Background(), oidcAudience, option.WithCredentialsFile(keyFileName))
+	ts, err := idtoken.NewTokenSource(context.Background(), oidcAudience, option.WithAuthCredentialsFile(option.ServiceAccount, keyFileName))
 	if err != nil {
 		return "", nil
 	}
@@ -175,7 +175,7 @@ func testBYOID(t *testing.T, c config) {
 	writeConfig(t, c, func(name string) {
 		// Once the default credentials are obtained,
 		// we should be able to access Google Cloud resources.
-		dnsService, err := dns.NewService(context.Background(), option.WithCredentialsFile(name))
+		dnsService, err := dns.NewService(context.Background(), option.WithAuthCredentialsFile(option.ExternalAccount, name))
 		if err != nil {
 			t.Fatalf("Could not establish DNS Service: %v", err)
 		}

integration-tests/downscope/downscope_test.go

@@ -46,7 +46,7 @@ func TestMain(m *testing.M) {
 	credentialFileName := os.Getenv(envServiceAccountFile)
 
 	var err error
-	rootCredential, err = transport.Creds(ctx, option.WithCredentialsFile(credentialFileName), option.WithScopes(rootTokenScope))
+	rootCredential, err = transport.Creds(ctx, option.WithAuthCredentialsFile(option.ServiceAccount, credentialFileName), option.WithScopes(rootTokenScope))
 
 	if err != nil {
 		log.Fatalf("failed to construct root credential: %v", err)

integration-tests/impersonate/impersonate_test.go

@@ -71,7 +71,7 @@ func TestImpersonatedCredentials(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			svc, err := storage.NewService(ctx,
-				option.WithCredentialsFile(tt.baseSALocation),
+				option.WithAuthCredentialsFile(option.ServiceAccount, tt.baseSALocation),
 				option.ImpersonateCredentials(writerSA, tt.delgates...),
 			)
 			if err != nil {

internal/creds.go

@@ -139,11 +139,13 @@ func detectDefaultFromDialSettings(settings *DialSettings) (*auth.Credentials, e
 		aud = settings.DefaultAudience
 	}
 
+	credsFile, _ := settings.GetAuthCredentialsFile()
+	credsJSON, _ := settings.GetAuthCredentialsJSON()
 	return credentials.DetectDefault(&credentials.DetectOptions{
 		Scopes:           scopes,
 		Audience:         aud,
-		CredentialsFile:  settings.CredentialsFile,
-		CredentialsJSON:  settings.CredentialsJSON,
+		CredentialsFile:  credsFile,
+		CredentialsJSON:  credsJSON,
 		UseSelfSignedJWT: useSelfSignedJWT,
 		Logger:           settings.Logger,
 	})
@@ -159,8 +161,8 @@ func baseCreds(ctx context.Context, ds *DialSettings) (*google.Credentials, erro
 	if len(ds.CredentialsJSON) > 0 {
 		return credentialsFromJSON(ctx, ds.CredentialsJSON, ds)
 	}
-	if ds.CredentialsFile != "" {
-		data, err := os.ReadFile(ds.CredentialsFile)
+	if cf, _ := ds.GetAuthCredentialsFile(); cf != "" {
+		data, err := os.ReadFile(cf)
 		if err != nil {
 			return nil, fmt.Errorf("cannot read credentials file: %v", err)
 		}

internal/creds_test.go

@@ -593,7 +593,7 @@ func TestIsSelfSignedJWTFlow(t *testing.T) {
 		{
 			name: "EnableJwtWithScope true",
 			ds: &DialSettings{
-				CredentialsFile:    "testdata/service-account.json",
+				AuthCredentialsFile:    "testdata/service-account.json",
 				Scopes:             []string{"foo"},
 				EnableJwtWithScope: true,
 			},
@@ -602,7 +602,7 @@ func TestIsSelfSignedJWTFlow(t *testing.T) {
 		{
 			name: "EnableJwtWithScope false",
 			ds: &DialSettings{
-				CredentialsFile:    "testdata/service-account.json",
+				AuthCredentialsFile:    "testdata/service-account.json",
 				Scopes:             []string{"foo"},
 				EnableJwtWithScope: false,
 			},
@@ -611,7 +611,7 @@ func TestIsSelfSignedJWTFlow(t *testing.T) {
 		{
 			name: "UniverseDomain",
 			ds: &DialSettings{
-				CredentialsFile:    "testdata/service-account.json",
+				AuthCredentialsFile:    "testdata/service-account.json",
 				Scopes:             []string{"foo"},
 				EnableJwtWithScope: false,
 				UniverseDomain:     "example.com",
@@ -621,7 +621,7 @@ func TestIsSelfSignedJWTFlow(t *testing.T) {
 		{
 			name: "UniverseDomainUserAccount",
 			ds: &DialSettings{
-				CredentialsFile:    "testdata/user-account.json",
+				AuthCredentialsFile:    "testdata/user-account.json",
 				Scopes:             []string{"foo"},
 				EnableJwtWithScope: false,
 				UniverseDomain:     "example.com",
@@ -632,7 +632,7 @@ func TestIsSelfSignedJWTFlow(t *testing.T) {
 
 	for _, tc := range tests {
 
-		bytes, err := os.ReadFile(tc.ds.CredentialsFile)
+		bytes, err := os.ReadFile(tc.ds.AuthCredentialsFile)
 		if err != nil {
 			t.Fatal(err)
 		}