From faf39c7919d5800bdcad2fbcb2a330c3fdd0ef96 Mon Sep 17 00:00:00 2001 From: Patrick Jones Date: Mon, 9 Aug 2021 20:35:43 +0000 Subject: [PATCH] google/downscope: additional examples Updating examples to match the expected token broker & token consumer paradigm. Change-Id: I9f6474e6d433e544dc92d8b1595e9538a5266043 GitHub-Last-Rev: 2149795f02d502661402819ac4dcb23cee5e7b8b GitHub-Pull-Request: golang/oauth2#513 Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/339190 Reviewed-by: Leo Siracusa Reviewed-by: Cody Oss Trust: Cody Oss Trust: Chris Broadfoot Run-TryBot: Cody Oss TryBot-Result: Go Bot --- google/downscope/downscoping.go | 20 +++++++-------- .../{example_test.go => tokenbroker_test.go} | 25 ++++++++++++++----- 2 files changed, 29 insertions(+), 16 deletions(-) rename google/downscope/{example_test.go => tokenbroker_test.go} (56%) diff --git a/google/downscope/downscoping.go b/google/downscope/downscoping.go index 5d9ad53..ac5c00d 100644 --- a/google/downscope/downscoping.go +++ b/google/downscope/downscoping.go @@ -9,13 +9,13 @@ can use. Please note that only Google Cloud Storage supports this feature. For complete documentation, see https://cloud.google.com/iam/docs/downscoping-short-lived-credentials To downscope permissions of a source credential, you need to define -a Credential Access Boundary. Said Boundary specifies which resources +a Credential Access Boundary. Said Boundary specifies which resources the newly created credential can access, an upper bound on the permissions -it has over those resources, and optionally attribute-based conditional -access to the aforementioned resources. For more information on IAM +it has over those resources, and optionally attribute-based conditional +access to the aforementioned resources. For more information on IAM Conditions, see https://cloud.google.com/iam/docs/conditions-overview. -This functionality would typically be used to provide a third party with +This functionality can be used to provide a third party with limited access to and permissions on resources held by the owner of the root credential or internally in conjunction with the principle of least privilege to ensure that internal services only hold the minimum necessary privileges @@ -24,13 +24,13 @@ for their function. For example, a token broker can be set up on a server in a private network. Various workloads (token consumers) in the same network will send authenticated requests to that broker for downscoped tokens to access or modify specific google -cloud storage buckets. See the NewTokenSource example for an example of how a +cloud storage buckets. See the NewTokenSource example for an example of how a token broker would use this package. The broker will use the functionality in this package to generate a downscoped token with the requested configuration, and then pass it back to the token -consumer. These downscoped access tokens can then be used to access Google -Storage resources. For instance, you can create a NewClient from the +consumer. These downscoped access tokens can then be used to access Google +Storage resources. For instance, you can create a NewClient from the "cloud.google.com/go/storage" package and pass in option.WithTokenSource(yourTokenSource)) */ package downscope @@ -81,7 +81,7 @@ type AccessBoundaryRule struct { // An Condition restricts the availability of permissions // to specific Cloud Storage objects. Optional. // - // A Condition can be used to make permissions available for specific objects, + // A Condition can be used to make permissions available for specific objects, // rather than all objects in a Cloud Storage bucket. Condition *AvailabilityCondition `json:"availabilityCondition,omitempty"` } @@ -183,9 +183,9 @@ func (dts downscopingTokenSource) Token() (*oauth2.Token, error) { if resp.StatusCode != http.StatusOK { b, err := ioutil.ReadAll(resp.Body) if err != nil { - return nil, fmt.Errorf("downscope: unable to exchange token; %v. Failed to read response body: %v", resp.StatusCode, err) + return nil, fmt.Errorf("downscope: unable to exchange token; %v. Failed to read response body: %v", resp.StatusCode, err) } - return nil, fmt.Errorf("downscope: unable to exchange token; %v. Server responsed: %v", resp.StatusCode, string(b)) + return nil, fmt.Errorf("downscope: unable to exchange token; %v. Server responsed: %v", resp.StatusCode, string(b)) } var tresp downscopedTokenResponse diff --git a/google/downscope/example_test.go b/google/downscope/tokenbroker_test.go similarity index 56% rename from google/downscope/example_test.go rename to google/downscope/tokenbroker_test.go index 138b9f4..cb16878 100644 --- a/google/downscope/example_test.go +++ b/google/downscope/tokenbroker_test.go @@ -8,13 +8,19 @@ import ( "context" "fmt" + "golang.org/x/oauth2/google" + "golang.org/x/oauth2" "golang.org/x/oauth2/google/downscope" ) func ExampleNewTokenSource() { + // This shows how to generate a downscoped token. This code would be run on the + // token broker, which holds the root token used to generate the downscoped token. ctx := context.Background() - // Initializes an accessBoundary with one Rule. + // Initializes an accessBoundary with one Rule which restricts the downscoped + // token to only be able to access the bucket "foo" and only grants it the + // permission "storage.objectViewer". accessBoundary := []downscope.AccessBoundaryRule{ { AvailableResource: "//storage.googleapis.com/projects/_/buckets/foo", @@ -26,7 +32,7 @@ func ExampleNewTokenSource() { // This Source can be initialized in multiple ways; the following example uses // Application Default Credentials. - // rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform") + rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform") dts, err := downscope.NewTokenSource(ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary}) if err != nil { @@ -34,11 +40,18 @@ func ExampleNewTokenSource() { return } - // Enables automatic token refreshing - _ = oauth2.ReuseTokenSource(nil, dts) + tok, err := dts.Token() + if err != nil { + fmt.Printf("failed to generate token: %v", err) + return + } + _ = tok + // You can now pass tok to a token consumer however you wish, such as exposing + // a REST API and sending it over HTTP. - // You can now use the token held in myTokenSource to make + // You can instead use the token held in dts to make // Google Cloud Storage calls, as follows: - // storageClient, err := storage.NewClient(ctx, option.WithTokenSource(myTokenSource)) + // storageClient, err := storage.NewClient(ctx, option.WithTokenSource(dts)) + }