[oauth2] google: add external account documentation
115 views
Skip to first unread message
Gerrit Bot (Gerrit)
Mar 14, 2021, 11:34:24 PM3/14/21
to goph...@pubsubhelper.golang.org, Patrick Jones, golang-co...@googlegroups.com
Gerrit Bot has uploaded this change for review.
google: add external account documentation
Adds some documentation to existing public structures for third-party authentication.
Change-Id: I756f5cd5619fbd752c028e99176991139fd45c60
GitHub-Last-Rev: da817920f065d73475ef67bec45524e44cb41d50
GitHub-Pull-Request: golang/oauth2#485
---
M google/doc.go
M google/internal/externalaccount/basecredentials.go
M google/internal/externalaccount/clientauth.go
M google/internal/externalaccount/impersonate.go
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 @@
// 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 @@
}
// 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 @@
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 @@
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 @@
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",
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Cody Oss (Gerrit)
Mar 17, 2021, 6:02:23 PM3/17/21
to Patrick Jones, Gerrit Bot, goph...@pubsubhelper.golang.org, Tyler Bui-Palsulich, golang-co...@googlegroups.com
Attention is currently required from: Tyler Bui-Palsulich.
2 comments:
File google/internal/externalaccount/basecredentials.go:
Patch Set #1, Line 21:
// Audience is the STS audience which contains the resource name for the workloadnit: Please move all of these to be above their respected struct Field.
File google/internal/externalaccount/clientauth.go:
Patch Set #1, Line 22:
// InjectAuthentication is simply used to add authentication to a Secure Token Service exchangenit: Remove the word simply.
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Cody Oss (Gerrit)
Mar 17, 2021, 6:02:34 PM3/17/21
to Patrick Jones, Gerrit Bot, goph...@pubsubhelper.golang.org, Tyler Bui-Palsulich, golang-co...@googlegroups.com
Attention is currently required from: Tyler Bui-Palsulich.
Patch set 1:Run-TryBot +1Trust +1
Gerrit Bot (Gerrit)
Mar 17, 2021, 6:27:53 PM3/17/21
to Patrick Jones, goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention is currently required from: Tyler Bui-Palsulich.
Gerrit Bot uploaded patch set #2 to this change.
google: add external account documentation
Adds some documentation to existing public structures for third-party authentication.
Change-Id: I756f5cd5619fbd752c028e99176991139fd45c60
GitHub-Last-Rev: 9d2d872dacb6545118e0f26db988e1a2e49b3e93
GitHub-Pull-Request: golang/oauth2#485
---
M google/doc.go
M google/internal/externalaccount/basecredentials.go
M google/internal/externalaccount/clientauth.go
M google/internal/externalaccount/impersonate.go
4 files changed, 29 insertions(+), 6 deletions(-)
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Tyler Bui-Palsulich (Gerrit)
Mar 19, 2021, 10:01:19 AM3/19/21
to Patrick Jones, Gerrit Bot, goph...@pubsubhelper.golang.org, Go Bot, Cody Oss, golang-co...@googlegroups.com
Patch set 2:Trust +1
3 comments:
File google/internal/externalaccount/basecredentials.go:
Patch Set #2, Line 19:
// Config stores the configuration for fetching tokens with external credentials:s/:/.
https://github.com/golang/go/wiki/CodeReviewComments#comment-sentences (the "end in a period" part applies here).
STS?
Patch Set #2, Line 25:
// e.g. `urn:ietf:params:oauth:token-type:jwt`Nit: also a period at the end.
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Jun 22, 2021, 4:01:15 PM6/22/21
to Patrick Jones, goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Gerrit Bot uploaded patch set #3 to this change.
google: add external account documentation
Adds some documentation to existing public structures for third-party authentication.
Change-Id: I756f5cd5619fbd752c028e99176991139fd45c60
GitHub-Last-Rev: 89cec012bb834a3bc8afa1998d1f56ffcccfbdce
GitHub-Pull-Request: golang/oauth2#485
---
M google/doc.go
M google/internal/externalaccount/basecredentials.go
M google/internal/externalaccount/clientauth.go
M google/internal/externalaccount/impersonate.go
4 files changed, 29 insertions(+), 6 deletions(-)
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Jun 22, 2021, 4:03:31 PM6/22/21
to Patrick Jones, goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Gerrit Bot uploaded patch set #4 to this change.
google: add external account documentation
Adds some documentation to existing public structures for third-party authentication.
Change-Id: I756f5cd5619fbd752c028e99176991139fd45c60
GitHub-Last-Rev: 78072af7e1a7c538bd8c12fa57b429afa6bc492d
GitHub-Pull-Request: golang/oauth2#485
---
M google/doc.go
M google/internal/externalaccount/basecredentials.go
M google/internal/externalaccount/clientauth.go
M google/internal/externalaccount/impersonate.go
4 files changed, 29 insertions(+), 5 deletions(-)
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Patrick Jones (Gerrit)
Jun 22, 2021, 4:04:23 PM6/22/21
to Gerrit Bot, goph...@pubsubhelper.golang.org, Tyler Bui-Palsulich, Go Bot, Cody Oss, golang-co...@googlegroups.com
Attention is currently required from: Cody Oss, Tyler Bui-Palsulich.
5 comments:
File google/internal/externalaccount/basecredentials.go:
Patch Set #1, Line 21:
// Audience is the STS audience which contains the resource name for the workload
nit: Please move all of these to be above their respected struct Field.
Done
File google/internal/externalaccount/basecredentials.go:
Patch Set #2, Line 19:
// Config stores the configuration for fetching tokens with external credentials:
s/:/. […]
Done
STS?
Done
Patch Set #2, Line 25:
// e.g. `urn:ietf:params:oauth:token-type:jwt`Nit: also a period at the end.
Done
File google/internal/externalaccount/clientauth.go:
Patch Set #1, Line 22:
// InjectAuthentication is simply used to add authentication to a Secure Token Service exchangenit: Remove the word simply.
Done
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Cody Oss (Gerrit)
Jun 22, 2021, 4:08:40 PM6/22/21
to Patrick Jones, Gerrit Bot, goph...@pubsubhelper.golang.org, Tyler Bui-Palsulich, Go Bot, golang-co...@googlegroups.com
Attention is currently required from: Tyler Bui-Palsulich.
Patch set 4:Run-TryBot +1Trust +1
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Cody Oss (Gerrit)
Jun 22, 2021, 4:42:23 PM6/22/21
to Patrick Jones, Gerrit Bot, goph...@pubsubhelper.golang.org, Go Bot, Tyler Bui-Palsulich, golang-co...@googlegroups.com
Attention is currently required from: Tyler Bui-Palsulich.
Patch set 4:Code-Review +2
1 comment:
File google/doc.go:
Patch Set #4, Line 7:
// credentials, service accounts, Google Compute Engine service accounts,nit: remove extra space.
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Patrick Jones (Gerrit)
Jun 22, 2021, 5:06:55 PM6/22/21
to Gerrit Bot, goph...@pubsubhelper.golang.org, Cody Oss, Go Bot, Tyler Bui-Palsulich, golang-co...@googlegroups.com
Attention is currently required from: Tyler Bui-Palsulich.
1 comment:
File google/doc.go:
Patch Set #4, Line 7:
// credentials, service accounts, Google Compute Engine service accounts,nit: remove extra space.
Done
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Gerrit Bot (Gerrit)
Jun 22, 2021, 5:08:24 PM6/22/21
to Patrick Jones, goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention is currently required from: Tyler Bui-Palsulich.
Gerrit Bot uploaded patch set #5 to this change.
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
---
M google/doc.go
M google/internal/externalaccount/basecredentials.go
M google/internal/externalaccount/clientauth.go
M google/internal/externalaccount/impersonate.go
4 files changed, 29 insertions(+), 5 deletions(-)
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Cody Oss (Gerrit)
Jun 22, 2021, 5:54:40 PM6/22/21
to Patrick Jones, Gerrit Bot, goph...@pubsubhelper.golang.org, golang-...@googlegroups.com, Go Bot, Tyler Bui-Palsulich, golang-co...@googlegroups.com
Cody Oss submitted this change.
Approvals:
Cody Oss: Looks good to me, approved; Trusted
Tyler Bui-Palsulich: Trusted
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 <cod...@google.com>
Trust: Tyler Bui-Palsulich <t...@google.com>
Reviewed-by: Cody Oss <cod...@google.com>
---
M google/doc.go
M google/internal/externalaccount/basecredentials.go
M google/internal/externalaccount/clientauth.go
M google/internal/externalaccount/impersonate.go
4 files changed, 29 insertions(+), 5 deletions(-)
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",
4 is the latest approved patch-set.
The change was submitted with unreviewed changes in the following files:
The name of the file: google/doc.go
Insertions: 1, Deletions: 1.
```
@@ -6:7, +6:7 @@
- // credentials, service accounts, Google Compute Engine service accounts,
+ // credentials, service accounts, Google Compute Engine service accounts,
```
To view, visit change 301610. To unsubscribe, or for help writing mail filters, visit settings.
Reply all
Reply to author
Forward
0 new messages