google

package
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2024 License: BSD-3-Clause Imports: 25 Imported by: 11,820

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, Google App Engine service accounts and workload identity federation from non-Google cloud platforms.

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. For more information on using workload identity federation, refer to https://cloud.google.com/iam/docs/how-to#using-workload-identity-federation.

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.

Workload Identity Federation

Using workload identity federation, your application can access Google Cloud resources from Amazon Web Services (AWS), Microsoft Azure or any identity provider that supports OpenID Connect (OIDC) or SAML 2.0. Traditionally, applications running outside Google Cloud have used service account keys to access Google Cloud resources. Using identity federation, you can allow your workload to impersonate a service account. This lets you access Google Cloud resources directly, eliminating the maintenance and security burden associated with service account keys.

Follow the detailed instructions on how to configure Workload Identity Federation in various platforms: 

Amazon Web Services (AWS): https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#aws
Microsoft Azure: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#azure
OIDC identity provider: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#oidc
SAML 2.0 identity provider: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#saml

For OIDC and SAML providers, the library can retrieve tokens in three ways: from a local file location (file-sourced credentials), from a server (URL-sourced credentials), or from a local executable (executable-sourced credentials). For file-sourced credentials, a background process needs to be continuously refreshing the file location with a new OIDC/SAML token prior to expiration. For tokens with one hour lifetimes, the token needs to be updated in the file every hour. The token can be stored directly as plain text or in JSON format. For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC/SAML token. The response can be in plain text or JSON. Additional required request headers can also be specified. For executable-sourced credentials, an application needs to be available to output the OIDC/SAML token and other information in a JSON format. For more information on how these work (and how to implement executable-sourced credentials), please check out: https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create_a_credential_configuration

Note that this library does not perform any validation on the token_url, token_info_url, or service_account_impersonation_url fields of the credential configuration. It is not recommended to use a credential configuration that you did not generate with the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain.

Workforce Identity Federation

Workforce identity federation lets you use an external identity provider (IdP) to authenticate and authorize a workforce—a group of users, such as employees, partners, and contractors—using IAM, so that the users can access Google Cloud services. Workforce identity federation extends Google Cloud's identity capabilities to support syncless, attribute-based single sign on.

With workforce identity federation, your workforce can access Google Cloud resources using an external identity provider (IdP) that supports OpenID Connect (OIDC) or SAML 2.0 such as Azure Active Directory (Azure AD), Active Directory Federation Services (AD FS), Okta, and others.

Follow the detailed instructions on how to configure Workload Identity Federation in various platforms: 

Azure AD: https://cloud.google.com/iam/docs/workforce-sign-in-azure-ad
Okta: https://cloud.google.com/iam/docs/workforce-sign-in-okta
OIDC identity provider: https://cloud.google.com/iam/docs/configuring-workforce-identity-federation#oidc
SAML 2.0 identity provider: https://cloud.google.com/iam/docs/configuring-workforce-identity-federation#saml

For workforce identity federation, the library can retrieve tokens in three ways: from a local file location (file-sourced credentials), from a server (URL-sourced credentials), or from a local executable (executable-sourced credentials). For file-sourced credentials, a background process needs to be continuously refreshing the file location with a new OIDC/SAML token prior to expiration. For tokens with one hour lifetimes, the token needs to be updated in the file every hour. The token can be stored directly as plain text or in JSON format. For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC/SAML token. The response can be in plain text or JSON. Additional required request headers can also be specified. For executable-sourced credentials, an application needs to be available to output the OIDC/SAML token and other information in a JSON format. For more information on how these work (and how to implement executable-sourced credentials), please check out: https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#generate_a_configuration_file_for_non-interactive_sign-in

Security considerations

Note that this library does not perform any validation on the token_url, token_info_url, or service_account_impersonation_url fields of the credential configuration. It is not recommended to use a credential configuration that you did not generate with the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain.

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.

Application Default Credentials also support workload identity federation to access Google Cloud resources from non-Google Cloud platforms including Amazon Web Services (AWS), Microsoft Azure or any identity provider that supports OpenID Connect (OIDC). Workload identity federation is recommended for non-Google Cloud environments as it avoids the need to download, manage and store service account private keys locally.

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.

Example (ServiceAccount) 
package main

import (
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"golang.org/x/oauth2/jwt"
)

func main() {
	// Your credentials should be obtained from the Google
	// Developer Console (https://console.developers.google.com).
	conf := &jwt.Config{
		Email: "xxx@developer.gserviceaccount.com",
		// The contents of your RSA private key or your PEM file
		// that contains a private key.
		// If you have a p12 file instead, you
		// can use `openssl` to export the private key into a pem file.
		//
		//    $ openssl pkcs12 -in key.p12 -passin pass:notasecret -out key.pem -nodes
		//
		// The field only supports PEM containers with no passphrase.
		// The openssl command will convert p12 keys to passphrase-less PEM containers.
		PrivateKey: []byte("-----BEGIN RSA PRIVATE KEY-----..."),
		Scopes: []string{
			"https://www.googleapis.com/auth/bigquery",
			"https://www.googleapis.com/auth/blogger",
		},
		TokenURL: google.JWTTokenURL,
		// If you would like to impersonate a user, you can
		// create a transport with a subject. The following GET
		// request will be made on the behalf of user@example.com.
		// Optional.
		Subject: "user@example.com",
	}
	// Initiate an http.Client, the following GET request will be
	// authorized and authenticated on the behalf of user@example.com.
	client := conf.Client(oauth2.NoContext)
	client.Get("...")
}

Output:
Example (WebServer) 
package main

import (
	"fmt"
	"log"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
)

func main() {
	// Your credentials should be obtained from the Google
	// Developer Console (https://console.developers.google.com).
	conf := &oauth2.Config{
		ClientID:     "YOUR_CLIENT_ID",
		ClientSecret: "YOUR_CLIENT_SECRET",
		RedirectURL:  "YOUR_REDIRECT_URL",
		Scopes: []string{
			"https://www.googleapis.com/auth/bigquery",
			"https://www.googleapis.com/auth/blogger",
		},
		Endpoint: google.Endpoint,
	}
	// Redirect user to Google's consent page to ask for permission
	// for the scopes specified above.
	url := conf.AuthCodeURL("state")
	fmt.Printf("Visit the URL for the auth dialog: %v", url)

	// Handle the exchange code to initiate a transport.
	tok, err := conf.Exchange(oauth2.NoContext, "authorization-code")
	if err != nil {
		log.Fatal(err)
	}
	client := conf.Client(oauth2.NoContext, tok)
	client.Get("...")
}

Output:

Index

Examples

Constants

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

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

View Source 
const MTLSTokenURL = "https://oauth2.mtls.googleapis.com/token"

MTLSTokenURL is Google's OAuth 2.0 default mTLS endpoint.

Variables

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

Endpoint is Google's OAuth 2.0 default 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.

Example 
package main

import (
	"net/http"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
)

func main() {
	client := &http.Client{
		Transport: &oauth2.Transport{
			// Fetch from Google Compute Engine's metadata server to retrieve
			// an access token for the provided account.
			// If no account is specified, "default" is used.
			// If no scopes are specified, a set of default scopes
			// are automatically granted.
			Source: google.ComputeTokenSource("", "https://www.googleapis.com/auth/bigquery"),
		},
	}
	client.Get("...")
}

Output:

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.

Example 
package main

import (
	"log"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
)

func main() {
	client, err := google.DefaultClient(oauth2.NoContext,
		"https://www.googleapis.com/auth/devstorage.full_control")
	if err != nil {
		log.Fatal(err)
	}
	client.Get("...")
}

Output:

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 JWTAccessTokenSourceWithScope 

func JWTAccessTokenSourceWithScope(jsonKey []byte, scope ...string) (oauth2.TokenSource, error)

JWTAccessTokenSourceWithScope 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 scope is typically a list of URLs 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.

Example 
package main

import (
	"io/ioutil"
	"log"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
)

func main() {
	// Your credentials should be obtained from the Google
	// Developer Console (https://console.developers.google.com).
	// Navigate to your project, then see the "Credentials" page
	// under "APIs & Auth".
	// To create a service account client, click "Create new Client ID",
	// select "Service Account", and click "Create Client ID". A JSON
	// key file will then be downloaded to your computer.
	data, err := ioutil.ReadFile("/path/to/your-project-key.json")
	if err != nil {
		log.Fatal(err)
	}
	conf, err := google.JWTConfigFromJSON(data, "https://www.googleapis.com/auth/bigquery")
	if err != nil {
		log.Fatal(err)
	}
	// Initiate an http.Client. The following GET request will be
	// authorized and authenticated on the behalf of
	// your service account.
	client := conf.Client(oauth2.NoContext)
	client.Get("...")
}

Output:

Types

type AuthenticationError 

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

AuthenticationError indicates there was an error in the authentication flow.

Use (*AuthenticationError).Temporary to check if the error can be retried.

func (*AuthenticationError) Error 

func (e *AuthenticationError) Error() string

func (*AuthenticationError) Temporary 

func (e *AuthenticationError) Temporary() bool

Temporary indicates that the network error has one of the following status codes and may be retried: 500, 503, 408, or 429.

func (*AuthenticationError) Unwrap 

func (e *AuthenticationError) Unwrap() error

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
	// contains filtered or unexported fields
}

Credentials holds Google credentials, including "Application Default Credentials". For more details, see: https://developers.google.com/accounts/docs/application-default-credentials Credentials from external accounts (workload identity federation) are used to identify a particular application from an on-prem or non-Google Cloud platform including Amazon Web Services (AWS), Microsoft Azure or any identity provider that supports OpenID Connect (OIDC).

func CredentialsFromJSON 

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

CredentialsFromJSON invokes CredentialsFromJSONWithParams with the specified scopes.

Example 
package main

import (
	"context"
	"io/ioutil"
	"log"

	"golang.org/x/oauth2/google"
)

func main() {
	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.
}

Output:

func CredentialsFromJSONWithParams 

func CredentialsFromJSONWithParams(ctx context.Context, jsonData []byte, params CredentialsParams) (*Credentials, error)

CredentialsFromJSONWithParams obtains Google credentials from a JSON value. The JSON can represent either a Google Developers Console client_credentials.json file (as in ConfigFromJSON), a Google Developers service account key file, a gcloud user credentials file (a.k.a. refresh token JSON), or the JSON configuration file for workload identity federation in non-Google cloud platforms (see https://cloud.google.com/iam/docs/how-to#using-workload-identity-federation).

func FindDefaultCredentials 

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

FindDefaultCredentials invokes FindDefaultCredentialsWithParams with the specified scopes.

func FindDefaultCredentialsWithParams 

func FindDefaultCredentialsWithParams(ctx context.Context, params CredentialsParams) (*Credentials, error)

FindDefaultCredentialsWithParams 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. For workload identity federation, refer to https://cloud.google.com/iam/docs/how-to#using-workload-identity-federation on how to generate the JSON configuration file for on-prem/non-Google cloud platforms.
  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.

func (*Credentials) GetUniverseDomain added in v0.16.0 

func (c *Credentials) GetUniverseDomain() (string, error)

GetUniverseDomain returns the default service domain for a given Cloud universe.

The default value is "googleapis.com".

It obtains the universe domain from the attached service account on GCE when authenticating via the GCE metadata server. See also [The attached service account](https://cloud.google.com/docs/authentication/application-default-credentials#attached-sa). If the GCE metadata server returns a 404 error, the default value is returned. If the GCE metadata server returns an error other than 404, the error is returned.

func (*Credentials) UniverseDomain deprecated added in v0.13.0 

func (c *Credentials) UniverseDomain() string

UniverseDomain returns the default service domain for a given Cloud universe.

The default value is "googleapis.com".

Deprecated: Use instead (*Credentials).GetUniverseDomain(), which supports obtaining the universe domain when authenticating via the GCE metadata server. Unlike GetUniverseDomain, this method, UniverseDomain, will always return the default value when authenticating via the GCE metadata server. See also [The attached service account](https://cloud.google.com/docs/authentication/application-default-credentials#attached-sa).

type CredentialsParams 

type CredentialsParams struct {
	// Scopes is the list OAuth scopes. Required.
	// Example: https://www.googleapis.com/auth/cloud-platform
	Scopes []string

	// Subject is the user email used for domain wide delegation (see
	// https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority).
	// Optional.
	Subject string

	// AuthHandler is the AuthorizationHandler used for 3-legged OAuth flow. Required for 3LO flow.
	AuthHandler authhandler.AuthorizationHandler

	// State is a unique string used with AuthHandler. Required for 3LO flow.
	State string

	// PKCE is used to support PKCE flow. Optional for 3LO flow.
	PKCE *authhandler.PKCEParams

	// The OAuth2 TokenURL default override. This value overrides the default TokenURL,
	// unless explicitly specified by the credentials config file. Optional.
	TokenURL string

	// EarlyTokenRefresh is the amount of time before a token expires that a new
	// token will be preemptively fetched. If unset the default value is 10
	// seconds.
	//
	// Note: This option is currently only respected when using credentials
	// fetched from the GCE metadata server.
	EarlyTokenRefresh time.Duration

	// UniverseDomain is the default service domain for a given Cloud universe.
	// Only supported in authentication flows that support universe domains.
	// This value takes precedence over a universe domain explicitly specified
	// in a credentials config file or by the GCE metadata server. Optional.
	UniverseDomain string
}

CredentialsParams holds user supplied parameters that are used together with a credentials file for building a Credentials object.

type DefaultCredentials deprecated 

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.

Example 
package main

import (
	"log"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
)

func main() {
	// The credentials will be obtained from the first account that
	// has been authorized with `gcloud auth login`.
	conf, err := google.NewSDKConfig("")
	if err != nil {
		log.Fatal(err)
	}
	// Initiate an http.Client. The following GET request will be
	// authorized and authenticated on the behalf of the SDK user.
	client := conf.Client(oauth2.NoContext)
	client.Get("...")
}

Output:

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.

Source Files

View all Source files

Directories

Path Synopsis
Package downscope implements the ability to downscope, or restrict, the Identity and Access Management permissions that a short-lived Token can use.
 Package downscope implements the ability to downscope, or restrict, the Identity and Access Management permissions that a short-lived Token can use.
internal
externalaccount
externalaccountauthorizeduser
stsexchange

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.