google: add external account documentation

Adds some documentation to existing public structures for third-party authentication.

Change-Id: I756f5cd5619fbd752c028e99176991139fd45c60
GitHub-Last-Rev: c846ea6
GitHub-Pull-Request: #485
Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/301610
Trust: Cody Oss <[email protected]>
Trust: Tyler Bui-Palsulich <[email protected]>
Reviewed-by: Cody Oss <[email protected]>

Author: gIthuriel

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, 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

google/internal/externalaccount/basecredentials.go

@@ -20,15 +20,34 @@ var now = func() time.Time {
 
 // Config stores the configuration for fetching tokens with external credentials.
 type Config struct {
+	// Audience is the Secure Token Service (STS) audience which contains the resource name for the workload
+	// identity pool or the workforce pool and the provider identifier in that pool.
 	Audience                       string
+	// SubjectTokenType is the STS token type based on the Oauth2.0 token exchange spec
+	// e.g. `urn:ietf:params:oauth:token-type:jwt`.
 	SubjectTokenType               string
+	// TokenURL is the STS token exchange endpoint.
 	TokenURL                       string
+	// 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.
 	TokenInfoURL                   string
+	// 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.
 	ServiceAccountImpersonationURL string
+	// ClientSecret is 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.
 	ClientSecret                   string
+	// ClientID is only required in conjunction with ClientSecret, as described above.
 	ClientID                       string
+	// CredentialSource contains the necessary information to retrieve the token itself, as well
+	// as some environmental information.
 	CredentialSource               CredentialSource
+	// 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.
 	QuotaProjectID                 string
+	// Scopes contains the desired scopes for the returned access token.
 	Scopes                         []string
 }
 
@@ -66,6 +85,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"`
 
@@ -107,7 +128,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

google/internal/externalaccount/clientauth.go

@@ -19,6 +19,9 @@ type clientAuthentication struct {
 	ClientSecret string
 }
 
+// InjectAuthentication is 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

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",