google: update documentation for workload identity federation

Document using workload identity federation from non-Google Cloud platforms to access Google Cloud resources.
This covers federation from AWS, Azure and OIDC providers via Application Default Credentials.

Change-Id: I77ee7f6aac5a75d095304f07f3004ec3fb7b9613
GitHub-Last-Rev: 07c9dd0
GitHub-Pull-Request: #478
Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/293751
Reviewed-by: Cody Oss <[email protected]>
Trust: Cody Oss <[email protected]>
Trust: Tyler Bui-Palsulich <[email protected]>
Run-TryBot: Cody Oss <[email protected]>
TryBot-Result: Go Bot <[email protected]>

google/default.go

@@ -21,6 +21,10 @@ import (
 // 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).
 type Credentials struct {
 	ProjectID   string // may be empty
 	TokenSource oauth2.TokenSource
@@ -65,6 +69,10 @@ func DefaultTokenSource(ctx context.Context, scope ...string) (oauth2.TokenSourc
 //
 //   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.
@@ -119,8 +127,10 @@ func FindDefaultCredentials(ctx context.Context, scopes ...string) (*Credentials
 
 // 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).
+// ConfigFromJSON), a Google Developers service account key file (as in
+// JWTConfigFromJSON) 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 CredentialsFromJSON(ctx context.Context, jsonData []byte, scopes ...string) (*Credentials, error) {
 	var f credentialsFile
 	if err := json.Unmarshal(jsonData, &f); err != nil {

google/doc.go

@@ -4,13 +4,16 @@
 
 // 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.
+// 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
 //
@@ -19,6 +22,35 @@
 // 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).
+// 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/access-resources-aws
+//   Microsoft Azure: https://cloud.google.com/iam/docs/access-resources-azure
+//   OIDC identity provider: https://cloud.google.com/iam/docs/access-resources-oidc
+//
+// For OIDC providers, the library can retrieve OIDC tokens either from a
+// local file location (file-sourced credentials) or from a local server
+// (URL-sourced credentials).
+// For file-sourced credentials, a background process needs to be continuously
+// refreshing the file location with a new OIDC 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 token. The response can be in plain text or JSON.
+// Additional required request headers can also be specified.
+//
 //
 // Credentials
 //
@@ -29,6 +61,13 @@
 // 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.
 //