google: add CredentialsFromJSON

Support obtaining a DefaultCredentials value from JSON data.

Also, add an example, and write more package doc.

For Go 1.9 and higher, rename DefaultCredentials to
Credentials and make the former an alias for the latter.

Updates google/google-api-go-client#247.

Change-Id: I9f9e234ed79f8e08fa13914d9c6c60e0154a06e5
Reviewed-on: https://go-review.googlesource.com/99795
Reviewed-by: Ross Light <light@google.com>
Reviewed-by: Chris Broadfoot <cbro@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

google/default.go

@@ -18,20 +18,6 @@ import (
 	"golang.org/x/oauth2"
 )
 
-// DefaultCredentials holds "Application Default Credentials".
-// For more details, see:
-// https://developers.google.com/accounts/docs/application-default-credentials
-type DefaultCredentials struct {
-	ProjectID   string // may be empty
-	TokenSource oauth2.TokenSource
-
-	// JSON contains the raw bytes from a JSON credentials file.
-	// This field may be nil if authentication is provided by the
-	// environment and not with a credentials file, e.g. when code is
-	// running on Google Cloud Platform.
-	JSON []byte
-}
-
 // DefaultClient returns an HTTP Client that uses the
 // DefaultTokenSource to obtain authentication credentials.
 func DefaultClient(ctx context.Context, scope ...string) (*http.Client, error) {
@@ -53,25 +39,12 @@ func DefaultTokenSource(ctx context.Context, scope ...string) (oauth2.TokenSourc
 	return creds.TokenSource, nil
 }
 
-// FindDefaultCredentials searches for "Application Default Credentials".
+// Common implementation for FindDefaultCredentials.
-//
+func findDefaultCredentials(ctx context.Context, scopes []string) (*DefaultCredentials, error) {
-// It looks for credentials in the following places,
-// preferring the first location found:
-//
-//   1. A JSON file whose path is specified by the
-//      GOOGLE_APPLICATION_CREDENTIALS environment variable.
-//   2. A JSON file in a location known to the gcloud command-line tool.
-//      On Windows, this is %APPDATA%/gcloud/application_default_credentials.json.
-//      On other systems, $HOME/.config/gcloud/application_default_credentials.json.
-//   3. On Google App Engine it uses the appengine.AccessToken function.
-//   4. On Google Compute Engine and Google App Engine Managed VMs, it fetches
-//      credentials from the metadata server.
-//      (In this final case any provided scopes are ignored.)
-func FindDefaultCredentials(ctx context.Context, scope ...string) (*DefaultCredentials, error) {
 	// First, try the environment variable.
 	const envVar = "GOOGLE_APPLICATION_CREDENTIALS"
 	if filename := os.Getenv(envVar); filename != "" {
-		creds, err := readCredentialsFile(ctx, filename, scope)
+		creds, err := readCredentialsFile(ctx, filename, scopes)
 		if err != nil {
 			return nil, fmt.Errorf("google: error getting credentials using %v environment variable: %v", envVar, err)
 		}
@@ -80,7 +53,7 @@ func FindDefaultCredentials(ctx context.Context, scope ...string) (*DefaultCrede
 
 	// Second, try a well-known file.
 	filename := wellKnownFile()
-	if creds, err := readCredentialsFile(ctx, filename, scope); err == nil {
+	if creds, err := readCredentialsFile(ctx, filename, scopes); err == nil {
 		return creds, nil
 	} else if !os.IsNotExist(err) {
 		return nil, fmt.Errorf("google: error getting credentials using well-known file (%v): %v", filename, err)
@@ -90,7 +63,7 @@ func FindDefaultCredentials(ctx context.Context, scope ...string) (*DefaultCrede
 	if appengineTokenFunc != nil && !appengineFlex {
 		return &DefaultCredentials{
 			ProjectID:   appengineAppIDFunc(ctx),
-			TokenSource: AppEngineTokenSource(ctx, scope...),
+			TokenSource: AppEngineTokenSource(ctx, scopes...),
 		}, nil
 	}
 
@@ -108,6 +81,23 @@ func FindDefaultCredentials(ctx context.Context, scope ...string) (*DefaultCrede
 	return nil, fmt.Errorf("google: could not find default credentials. See %v for more information.", url)
 }
 
+// Common implementation for CredentialsFromJSON.
+func credentialsFromJSON(ctx context.Context, jsonData []byte, scopes []string) (*DefaultCredentials, error) {
+	var f credentialsFile
+	if err := json.Unmarshal(jsonData, &f); err != nil {
+		return nil, err
+	}
+	ts, err := f.tokenSource(ctx, append([]string(nil), scopes...))
+	if err != nil {
+		return nil, err
+	}
+	return &DefaultCredentials{
+		ProjectID:   f.ProjectID,
+		TokenSource: ts,
+		JSON:        jsonData,
+	}, nil
+}
+
 func wellKnownFile() string {
 	const f = "application_default_credentials.json"
 	if runtime.GOOS == "windows" {
@@ -121,17 +111,5 @@ func readCredentialsFile(ctx context.Context, filename string, scopes []string)
 	if err != nil {
 		return nil, err
 	}
-	var f credentialsFile
+	return CredentialsFromJSON(ctx, b, scopes...)
-	if err := json.Unmarshal(b, &f); err != nil {
-		return nil, err
-	}
-	ts, err := f.tokenSource(ctx, append([]string(nil), scopes...))
-	if err != nil {
-		return nil, err
-	}
-	return &DefaultCredentials{
-		ProjectID:   f.ProjectID,
-		TokenSource: ts,
-		JSON:        b,
-	}, nil
 }

google/doc_go19.go

@@ -0,0 +1,42 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build go1.9
+
+// Package google provides support for making OAuth2 authorized and authenticated
+// HTTP requests to Google APIs. It supports the Web server flow, client-side
+// credentials, service accounts, Google Compute Engine service accounts, and Google
+// App Engine service accounts.
+//
+// A brief overview of the package follows. For more information, please read
+// https://developers.google.com/accounts/docs/OAuth2
+// and
+// https://developers.google.com/accounts/docs/application-default-credentials.
+//
+// OAuth2 Configs
+//
+// Two functions in this package return golang.org/x/oauth2.Config values from Google credential
+// data. Google supports two JSON formats for OAuth2 credentials: one is handled by ConfigFromJSON,
+// the other by JWTConfigFromJSON. The returned Config can be used to obtain a TokenSource or
+// create an http.Client.
+//
+//
+// Credentials
+//
+// The Credentials type represents Google credentials, including Application Default
+// Credentials.
+//
+// Use FindDefaultCredentials to obtain Application Default Credentials.
+// FindDefaultCredentials looks in some well-known places for a credentials file, and
+// will call AppEngineTokenSource or ComputeTokenSource as needed.
+//
+// DefaultClient and DefaultTokenSource are convenience methods. They first call FindDefaultCredentials,
+// then use the credentials to construct an http.Client or an oauth2.TokenSource.
+//
+// Use CredentialsFromJSON to obtain credentials from either of the two JSON formats
+// described in OAuth2 Configs, above. The TokenSource in the returned value is the
+// same as the one obtained from the oauth2.Config returned from ConfigFromJSON or
+// JWTConfigFromJSON, but the Credentials may contain additional information
+// that is useful is some circumstances.
+package google // import "golang.org/x/oauth2/google"

google/doc_not_go19.go

@@ -0,0 +1,43 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build !go1.9
+
+// Package google provides support for making OAuth2 authorized and authenticated
+// HTTP requests to Google APIs. It supports the Web server flow, client-side
+// credentials, service accounts, Google Compute Engine service accounts, and Google
+// App Engine service accounts.
+//
+// A brief overview of the package follows. For more information, please read
+// https://developers.google.com/accounts/docs/OAuth2
+// and
+// https://developers.google.com/accounts/docs/application-default-credentials.
+//
+// OAuth2 Configs
+//
+// Two functions in this package return golang.org/x/oauth2.Config values from Google credential
+// data. Google supports two JSON formats for OAuth2 credentials: one is handled by ConfigFromJSON,
+// the other by JWTConfigFromJSON. The returned Config can be used to obtain a TokenSource or
+// create an http.Client.
+//
+//
+// Credentials
+//
+// The DefaultCredentials type represents Google Application Default Credentials, as
+// well as other forms of credential.
+//
+// Use FindDefaultCredentials to obtain Application Default Credentials.
+// FindDefaultCredentials looks in some well-known places for a credentials file, and
+// will call AppEngineTokenSource or ComputeTokenSource as needed.
+//
+// DefaultClient and DefaultTokenSource are convenience methods. They first call FindDefaultCredentials,
+// then use the credentials to construct an http.Client or an oauth2.TokenSource.
+//
+// Use CredentialsFromJSON to obtain credentials from either of the two JSON
+// formats described in OAuth2 Configs, above. (The DefaultCredentials returned may
+// not be "Application Default Credentials".) The TokenSource in the returned value
+// is the same as the one obtained from the oauth2.Config returned from
+// ConfigFromJSON or JWTConfigFromJSON, but the DefaultCredentials may contain
+// additional information that is useful is some circumstances.
+package google // import "golang.org/x/oauth2/google"

google/example_test.go

@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// +build appenginevm appengine
-
 package google_test
 
 import (
@@ -12,6 +10,7 @@ import (
 	"log"
 	"net/http"
 
+	"golang.org/x/net/context"
 	"golang.org/x/oauth2"
 	"golang.org/x/oauth2/google"
 	"golang.org/x/oauth2/jwt"
@@ -148,3 +147,16 @@ func ExampleComputeTokenSource() {
 	}
 	client.Get("...")
 }
+
+func ExampleCredentialsFromJSON() {
+	ctx := context.Background()
+	data, err := ioutil.ReadFile("/path/to/key-file.json")
+	if err != nil {
+		log.Fatal(err)
+	}
+	creds, err := google.CredentialsFromJSON(ctx, data, "https://www.googleapis.com/auth/bigquery")
+	if err != nil {
+		log.Fatal(err)
+	}
+	_ = creds // TODO: Use creds.
+}

google/go19.go

@@ -0,0 +1,57 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build go1.9
+
+package google
+
+import (
+	"golang.org/x/net/context"
+	"golang.org/x/oauth2"
+)
+
+// Credentials holds Google credentials, including "Application Default Credentials".
+// For more details, see:
+// https://developers.google.com/accounts/docs/application-default-credentials
+type Credentials struct {
+	ProjectID   string // may be empty
+	TokenSource oauth2.TokenSource
+
+	// JSON contains the raw bytes from a JSON credentials file.
+	// This field may be nil if authentication is provided by the
+	// environment and not with a credentials file, e.g. when code is
+	// running on Google Cloud Platform.
+	JSON []byte
+}
+
+// DefaultCredentials is the old name of Credentials.
+//
+// Deprecated: use Credentials instead.
+type DefaultCredentials = Credentials
+
+// FindDefaultCredentials searches for "Application Default Credentials".
+//
+// It looks for credentials in the following places,
+// preferring the first location found:
+//
+//   1. A JSON file whose path is specified by the
+//      GOOGLE_APPLICATION_CREDENTIALS environment variable.
+//   2. A JSON file in a location known to the gcloud command-line tool.
+//      On Windows, this is %APPDATA%/gcloud/application_default_credentials.json.
+//      On other systems, $HOME/.config/gcloud/application_default_credentials.json.
+//   3. On Google App Engine it uses the appengine.AccessToken function.
+//   4. On Google Compute Engine and Google App Engine Managed VMs, it fetches
+//      credentials from the metadata server.
+//      (In this final case any provided scopes are ignored.)
+func FindDefaultCredentials(ctx context.Context, scopes ...string) (*Credentials, error) {
+	return findDefaultCredentials(ctx, scopes)
+}
+
+// CredentialsFromJSON obtains Google credentials from a JSON value. The JSON can
+// represent either a Google Developers Console client_credentials.json file (as in
+// ConfigFromJSON) or a Google Developers service account key file (as in
+// JWTConfigFromJSON).
+func CredentialsFromJSON(ctx context.Context, jsonData []byte, scopes ...string) (*Credentials, error) {
+	return credentialsFromJSON(ctx, jsonData, scopes)
+}

google/google.go

@@ -2,17 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package google provides support for making OAuth2 authorized and
+package google
-// authenticated HTTP requests to Google APIs.
-// It supports the Web server flow, client-side credentials, service accounts,
-// Google Compute Engine service accounts, and Google App Engine service
-// accounts.
-//
-// For more information, please read
-// https://developers.google.com/accounts/docs/OAuth2
-// and
-// https://developers.google.com/accounts/docs/application-default-credentials.
-package google // import "golang.org/x/oauth2/google"
 
 import (
 	"encoding/json"

google/not_go19.go

@@ -0,0 +1,54 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build !go1.9
+
+package google
+
+import (
+	"golang.org/x/net/context"
+	"golang.org/x/oauth2"
+)
+
+// DefaultCredentials holds Google credentials, including "Application Default Credentials".
+// For more details, see:
+// https://developers.google.com/accounts/docs/application-default-credentials
+type DefaultCredentials struct {
+	ProjectID   string // may be empty
+	TokenSource oauth2.TokenSource
+
+	// JSON contains the raw bytes from a JSON credentials file.
+	// This field may be nil if authentication is provided by the
+	// environment and not with a credentials file, e.g. when code is
+	// running on Google Cloud Platform.
+	JSON []byte
+}
+
+// FindDefaultCredentials searches for "Application Default Credentials".
+//
+// It looks for credentials in the following places,
+// preferring the first location found:
+//
+//   1. A JSON file whose path is specified by the
+//      GOOGLE_APPLICATION_CREDENTIALS environment variable.
+//   2. A JSON file in a location known to the gcloud command-line tool.
+//      On Windows, this is %APPDATA%/gcloud/application_default_credentials.json.
+//      On other systems, $HOME/.config/gcloud/application_default_credentials.json.
+//   3. On Google App Engine it uses the appengine.AccessToken function.
+//   4. On Google Compute Engine and Google App Engine Managed VMs, it fetches
+//      credentials from the metadata server.
+//      (In this final case any provided scopes are ignored.)
+func FindDefaultCredentials(ctx context.Context, scopes ...string) (*DefaultCredentials, error) {
+	return findDefaultCredentials(ctx, scopes)
+}
+
+// CredentialsFromJSON obtains Google credentials from a JSON value. The JSON can
+// represent either a Google Developers Console client_credentials.json file (as in
+// ConfigFromJSON) or a Google Developers service account key file (as in
+// JWTConfigFromJSON).
+//
+// Note: despite the name, the returned credentials may not be Application Default Credentials.
+func CredentialsFromJSON(ctx context.Context, jsonData []byte, scopes ...string) (*DefaultCredentials, error) {
+	return credentialsFromJSON(ctx, jsonData, scopes)
+}