Package credentials 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.
Credentials
The cloud.google.com/go/auth.Credentials type represents Google credentials, including Application Default Credentials.
Use DetectDefault to obtain Application Default Credentials.
Application Default Credentials 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.
Workforce Identity Federation
For more information on this feature see cloud.google.com/go/auth/credentials/externalaccount.
Functions
func DetectDefault
func DetectDefault(opts *DetectOptions) (*auth.Credentials, error)DetectDefault searches for "Application Default Credentials" and returns a credential based on the [DetectOptions] provided.
It looks for credentials in the following places, preferring the first location found:
- 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.
- 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.
- On Google Compute Engine, Google App Engine standard second generation runtimes, and Google App Engine flexible environment, it fetches credentials from the metadata server.
Examples
package main
import (
"log"
"cloud.google.com/go/auth/credentials"
"cloud.google.com/go/auth/httptransport"
)
func main() {
creds, err := credentials.DetectDefault(&credentials.DetectOptions{
Scopes: []string{"https://www.googleapis.com/auth/devstorage.full_control"},
})
if err != nil {
log.Fatal(err)
}
client, err := httptransport.NewClient(&httptransport.Options{
Credentials: creds,
})
if err != nil {
log.Fatal(err)
}
client.Get("...")
}
withFilepath
package main
import (
"log"
"cloud.google.com/go/auth/credentials"
"cloud.google.com/go/auth/httptransport"
)
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.
filepath := "/path/to/your-project-key.json"
creds, err := credentials.DetectDefault(&credentials.DetectOptions{
Scopes: []string{"https://www.googleapis.com/auth/bigquery"},
CredentialsFile: filepath,
})
if err != nil {
log.Fatal(err)
}
client, err := httptransport.NewClient(&httptransport.Options{
Credentials: creds,
})
if err != nil {
log.Fatal(err)
}
client.Get("...")
}
withJSON
package main
import (
"log"
"os"
"cloud.google.com/go/auth/credentials"
"cloud.google.com/go/auth/httptransport"
)
func main() {
data, err := os.ReadFile("/path/to/key-file.json")
if err != nil {
log.Fatal(err)
}
creds, err := credentials.DetectDefault(&credentials.DetectOptions{
Scopes: []string{"https://www.googleapis.com/auth/bigquery"},
CredentialsJSON: data,
})
if err != nil {
log.Fatal(err)
}
client, err := httptransport.NewClient(&httptransport.Options{
Credentials: creds,
})
if err != nil {
log.Fatal(err)
}
client.Get("...")
}
func OnGCE
func OnGCE() boolOnGCE reports whether this process is running in Google Cloud.
DetectOptions
type DetectOptions struct {
// Scopes that credentials tokens should have. Example:
// https://www.googleapis.com/auth/cloud-platform. Required if Audience is
// not provided.
Scopes []string
// Audience that credentials tokens should have. Only applicable for 2LO
// flows with service accounts. If specified, scopes should not be provided.
Audience string
// Subject is the user email used for [domain wide delegation](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority).
// Optional.
Subject string
// EarlyTokenRefresh configures how early before a token expires that it
// should be refreshed.
EarlyTokenRefresh time.Duration
// AuthHandlerOptions configures an authorization handler and other options
// for 3LO flows. It is required, and only used, for client credential
// flows.
AuthHandlerOptions *auth.AuthorizationHandlerOptions
// TokenURL allows to set the token endpoint for user credential flows. If
// unset the default value is: https://oauth2.googleapis.com/token.
// Optional.
TokenURL string
// STSAudience is the audience sent to when retrieving an STS token.
// Currently this only used for GDCH auth flow, for which it is required.
STSAudience string
// CredentialsFile overrides detection logic and sources a credential file
// from the provided filepath. If provided, CredentialsJSON must not be.
// Optional.
CredentialsFile string
// CredentialsJSON overrides detection logic and uses the JSON bytes as the
// source for the credential. If provided, CredentialsFile must not be.
// Optional.
CredentialsJSON []byte
// UseSelfSignedJWT directs service account based credentials to create a
// self-signed JWT with the private key found in the file, skipping any
// network requests that would normally be made. Optional.
UseSelfSignedJWT bool
// Client configures the underlying client used to make network requests
// when fetching tokens. Optional.
Client *http.Client
// UniverseDomain is the default service domain for a given Cloud universe.
// The default value is "googleapis.com". This option is ignored for
// authentication flows that do not support universe domain. Optional.
UniverseDomain string
}DetectOptions provides configuration for [DetectDefault].