From da817920f065d73475ef67bec45524e44cb41d50 Mon Sep 17 00:00:00 2001
From: Patrick Jones <ithuriel@google.com>
Date: Sun, 14 Mar 2021 19:28:07 -0700
Subject: [PATCH] Added documentation for external account integration.

Change-Id: I30610b306ea5a8c1d7e1fc3e6f151a4449345331
---
 google/doc.go                                 |  6 ++--
 .../externalaccount/basecredentials.go        | 35 +++++++++++++++++--
 google/internal/externalaccount/clientauth.go |  3 ++
 .../internal/externalaccount/impersonate.go   |  2 +-
 4 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/google/doc.go b/google/doc.go
index b241c72..3f18bce 100644
--- a/google/doc.go
+++ b/google/doc.go
@@ -4,9 +4,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, Google
-// App Engine service accounts and workload identity federation from non-Google
-// cloud platforms.
+// credentials, service accounts, external accounts (workload identity federation),
+// 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
diff --git a/google/internal/externalaccount/basecredentials.go b/google/internal/externalaccount/basecredentials.go
index 1b87c09..40fb557 100644
--- a/google/internal/externalaccount/basecredentials.go
+++ b/google/internal/externalaccount/basecredentials.go
@@ -16,7 +16,36 @@ import (
 // now aliases time.Now for testing
 var now = time.Now
 
-// Config stores the configuration for fetching tokens with external credentials.
+// Config stores the configuration for fetching tokens with external credentials:
+
+// Audience is the STS audience which contains the resource name for the workload
+// identity pool or the workforce pool and the provider identifier in that pool.
+
+// TokenURL is the STS token exchange endpoint.
+
+// TokenInfoURL is the token_info endpoint used to retrieve the account related information (
+// user attributes like account identifier, eg. email, username, uid, etc). This is
+// needed for gCloud session account identification.
+
+// SubjectTokenType is the STS token type based on the Oauth2.0 token exchange spec
+// e.g. `urn:ietf:params:oauth:token-type:jwt`
+
+// TokenURL is the STS token exchange endpoint
+
+// ServiceAccountImpersonationURL is the URL for the service account impersonation request. This is only
+// required for workload identity pools when APIs to be accessed have not integrated with UberMint.
+
+// Client ID and client secret are currently only required if token_info endpoint also
+// needs to be called with the generated GCP access token. When provided, STS will be
+// called with additional basic authentication using client_id as username and client_secret as password.
+
+// CredentialSource contains the necessary information to retrieve the token itself, as well
+// as some environmental information.
+
+// QuotaProjectID is injected by gCloud. If the value is non-empty, the Auth libraries
+// will set the x-goog-user-project which overrides the project associated with the credentials.
+
+// Scopes contains the desired scopes for the returned access token.
 type Config struct {
 	Audience                       string
 	SubjectTokenType               string
@@ -64,6 +93,8 @@ type format struct {
 }
 
 // CredentialSource stores the information necessary to retrieve the credentials for the STS exchange.
+// Either the File or the URL field should be filled, depending on the kind of credential in question.
+// The EnvironmentID should start with AWS if being used for an AWS credential.
 type CredentialSource struct {
 	File string `json:"file"`
 
@@ -105,7 +136,7 @@ type baseCredentialSource interface {
 	subjectToken() (string, error)
 }
 
-// tokenSource is the source that handles external credentials.
+// tokenSource is the source that handles external credentials.  It is used to retrieve Tokens.
 type tokenSource struct {
 	ctx  context.Context
 	conf *Config
diff --git a/google/internal/externalaccount/clientauth.go b/google/internal/externalaccount/clientauth.go
index feccf8b..a04c1f4 100644
--- a/google/internal/externalaccount/clientauth.go
+++ b/google/internal/externalaccount/clientauth.go
@@ -19,6 +19,9 @@ type clientAuthentication struct {
 	ClientSecret string
 }
 
+// InjectAuthentication is simply used to add authentication to a Secure Token Service exchange
+// request.  It modifies either the passed url.Values or http.Header depending on the desired
+// authentication format.
 func (c *clientAuthentication) InjectAuthentication(values url.Values, headers http.Header) {
 	if c.ClientID == "" || c.ClientSecret == "" || values == nil || headers == nil {
 		return
diff --git a/google/internal/externalaccount/impersonate.go b/google/internal/externalaccount/impersonate.go
index 1d29c46..1f6009b 100644
--- a/google/internal/externalaccount/impersonate.go
+++ b/google/internal/externalaccount/impersonate.go
@@ -36,7 +36,7 @@ type impersonateTokenSource struct {
 	scopes []string
 }
 
-// Token performs the exchange to get a temporary service account
+// Token performs the exchange to get a temporary service account token to allow access to GCP.
 func (its impersonateTokenSource) Token() (*oauth2.Token, error) {
 	reqBody := generateAccessTokenReq{
 		Lifetime: "3600s",