google

Documentation

Overview

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.

Index

• Constants
• Variables
• func AppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource
• func ComputeTokenSource(account string, scope ...string) oauth2.TokenSource
• func ConfigFromJSON(jsonKey []byte, scope ...string) (*oauth2.Config, error)
• func DefaultClient(ctx context.Context, scope ...string) (*http.Client, error)
• func DefaultTokenSource(ctx context.Context, scope ...string) (oauth2.TokenSource, error)
• func JWTAccessTokenSourceFromJSON(jsonKey []byte, audience string) (oauth2.TokenSource, error)
• func JWTConfigFromJSON(jsonKey []byte, scope ...string) (*jwt.Config, error)
• type Credentials
  • func CredentialsFromJSON(ctx context.Context, jsonData []byte, scopes ...string) (*Credentials, error)
  • func FindDefaultCredentials(ctx context.Context, scopes ...string) (*Credentials, error)
• type DefaultCredentials
• type SDKConfig
  • func NewSDKConfig(account string) (*SDKConfig, error)
  • func (c *SDKConfig) Client(ctx context.Context) *http.Client
  • func (c *SDKConfig) Scopes() []string
  • func (c *SDKConfig) TokenSource(ctx context.Context) oauth2.TokenSource

Constants

const JWTTokenURL = "https://oauth2.googleapis.com/token"

JWTTokenURL is Google's OAuth 2.0 token URL to use with the JWT flow.

Variables

var Endpoint = oauth2.Endpoint{
	AuthURL:   "https://accounts.google.com/o/oauth2/auth",
	TokenURL:  "https://oauth2.googleapis.com/token",
	AuthStyle: oauth2.AuthStyleInParams,
}

Endpoint is Google's OAuth 2.0 endpoint.

Functions

func AppEngineTokenSource

func AppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource

AppEngineTokenSource returns a token source that fetches tokens from either the current application's service account or from the metadata server, depending on the App Engine environment. See below for environment-specific details. If you are implementing a 3-legged OAuth 2.0 flow on App Engine that involves user accounts, see oauth2.Config instead.

First generation App Engine runtimes (<= Go 1.9): AppEngineTokenSource returns a token source that fetches tokens issued to the current App Engine application's service account. The provided context must have come from appengine.NewContext.

Second generation App Engine runtimes (>= Go 1.11) and App Engine flexible: AppEngineTokenSource is DEPRECATED on second generation runtimes and on the flexible environment. It delegates to ComputeTokenSource, and the provided context and scopes are not used. Please use DefaultTokenSource (or ComputeTokenSource, which DefaultTokenSource will use in this case) instead.

func ComputeTokenSource

func ComputeTokenSource(account string, scope ...string) oauth2.TokenSource

ComputeTokenSource returns a token source that fetches access tokens from Google Compute Engine (GCE)'s metadata server. It's only valid to use this token source if your program is running on a GCE instance. If no account is specified, "default" is used. If no scopes are specified, a set of default scopes are automatically granted. Further information about retrieving access tokens from the GCE metadata server can be found at https://cloud.google.com/compute/docs/authentication.

func ConfigFromJSON

func ConfigFromJSON(jsonKey []byte, scope ...string) (*oauth2.Config, error)

ConfigFromJSON uses a Google Developers Console client_credentials.json file to construct a config. client_credentials.json can be downloaded from https://console.developers.google.com, under "Credentials". Download the Web application credentials in the JSON format and provide the contents of the file as jsonKey.

func DefaultClient

func DefaultClient(ctx context.Context, scope ...string) (*http.Client, error)

DefaultClient returns an HTTP Client that uses the DefaultTokenSource to obtain authentication credentials.

func DefaultTokenSource

func DefaultTokenSource(ctx context.Context, scope ...string) (oauth2.TokenSource, error)

DefaultTokenSource returns the token source for "Application Default Credentials". It is a shortcut for FindDefaultCredentials(ctx, scope).TokenSource.

func JWTAccessTokenSourceFromJSON

func JWTAccessTokenSourceFromJSON(jsonKey []byte, audience string) (oauth2.TokenSource, error)

JWTAccessTokenSourceFromJSON uses a Google Developers service account JSON key file to read the credentials that authorize and authenticate the requests, and returns a TokenSource that does not use any OAuth2 flow but instead creates a JWT and sends that as the access token. The audience is typically a URL that specifies the scope of the credentials.

Note that this is not a standard OAuth flow, but rather an optimization supported by a few Google services. Unless you know otherwise, you should use JWTConfigFromJSON instead.

func JWTConfigFromJSON

func JWTConfigFromJSON(jsonKey []byte, scope ...string) (*jwt.Config, error)

JWTConfigFromJSON uses a Google Developers service account JSON key file to read the credentials that authorize and authenticate the requests. Create a service account on "Credentials" for your project at https://console.developers.google.com to download a JSON key file.

Types

type 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
}

Credentials holds Google credentials, including "Application Default Credentials". For more details, see: https://developers.google.com/accounts/docs/application-default-credentials

func CredentialsFromJSON

func CredentialsFromJSON(ctx context.Context, jsonData []byte, scopes ...string) (*Credentials, error)

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 FindDefaultCredentials

func FindDefaultCredentials(ctx context.Context, scopes ...string) (*Credentials, error)

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 standard first generation runtimes (<= Go 1.9) it uses the appengine.AccessToken function.
4. On Google Compute Engine, Google App Engine standard second generation runtimes (>= Go 1.11), and Google App Engine flexible environment, it fetches credentials from the metadata server.

type DefaultCredentials

type DefaultCredentials = Credentials

DefaultCredentials is the old name of Credentials.

Deprecated: use Credentials instead.

type SDKConfig

type SDKConfig struct {
	// contains filtered or unexported fields
}

An SDKConfig provides access to tokens from an account already authorized via the Google Cloud SDK.

func NewSDKConfig

func NewSDKConfig(account string) (*SDKConfig, error)

NewSDKConfig creates an SDKConfig for the given Google Cloud SDK account. If account is empty, the account currently active in Google Cloud SDK properties is used. Google Cloud SDK credentials must be created by running `gcloud auth` before using this function. The Google Cloud SDK is available at https://cloud.google.com/sdk/.

func (*SDKConfig) Client

func (c *SDKConfig) Client(ctx context.Context) *http.Client

Client returns an HTTP client using Google Cloud SDK credentials to authorize requests. The token will auto-refresh as necessary. The underlying http.RoundTripper will be obtained using the provided context. The returned client and its Transport should not be modified.

func (*SDKConfig) Scopes

func (c *SDKConfig) Scopes() []string

Scopes are the OAuth 2.0 scopes the current account is authorized for.

func (*SDKConfig) TokenSource

func (c *SDKConfig) TokenSource(ctx context.Context) oauth2.TokenSource

TokenSource returns an oauth2.TokenSource that retrieve tokens from Google Cloud SDK credentials using the provided context. It will returns the current access token stored in the credentials, and refresh it when it expires, but it won't update the credentials with the new access token.