google: add external account documentation
Adds some documentation to existing public structures for third-party authentication.
Change-Id: I756f5cd5619fbd752c028e99176991139fd45c60
GitHub-Last-Rev: c846ea6748d2cc15bf496bbfc41f671c264d2220
GitHub-Pull-Request: golang/oauth2#485
Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/301610
Trust: Cody Oss <codyoss@google.com>
Trust: Tyler Bui-Palsulich <tbp@google.com>
Reviewed-by: Cody Oss <codyoss@google.com>
diff --git a/google/doc.go b/google/doc.go
index b241c72..8e6a57c 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, 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 1a6e93c..a4d45d9 100644
--- a/google/internal/externalaccount/basecredentials.go
+++ b/google/internal/externalaccount/basecredentials.go
@@ -20,15 +20,34 @@
// 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 @@
}
// 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 @@
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..62c2e36 100644
--- a/google/internal/externalaccount/clientauth.go
+++ b/google/internal/externalaccount/clientauth.go
@@ -19,6 +19,9 @@
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
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 @@
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",
