From 6f1e6394065a17f7c4e686dad23e06b6843e20e0 Mon Sep 17 00:00:00 2001 From: Patrick Jones Date: Wed, 4 Aug 2021 21:45:42 +0000 Subject: [PATCH] google/downscope: update documentation Change-Id: Ib4dfc7b554c1e7565cc61bc372a98ddd390e7453 GitHub-Last-Rev: 63894e56810431f8a45d381f4ffb123da1a1b8e0 GitHub-Pull-Request: golang/oauth2#512 Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/338389 Reviewed-by: Cody Oss Reviewed-by: Chris Broadfoot Trust: Cody Oss Trust: Chris Broadfoot Run-TryBot: Cody Oss Run-TryBot: Chris Broadfoot TryBot-Result: Go Bot --- google/downscope/downscoping.go | 29 +++++++++++++++++++++++++++-- google/downscope/example_test.go | 8 +++++++- 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/google/downscope/downscoping.go b/google/downscope/downscoping.go index 2d74c37..5d9ad53 100644 --- a/google/downscope/downscoping.go +++ b/google/downscope/downscoping.go @@ -4,9 +4,34 @@ /* Package downscope implements the ability to downscope, or restrict, the -Identity and AccessManagement permissions that a short-lived Token +Identity and Access Management permissions that a short-lived Token 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 +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 +Conditions, see https://cloud.google.com/iam/docs/conditions-overview. + +This functionality would typically 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 +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 +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 +"cloud.google.com/go/storage" package and pass in option.WithTokenSource(yourTokenSource)) */ package downscope @@ -91,7 +116,7 @@ type downscopingTokenSource struct { config DownscopingConfig } -// NewTokenSource returns an empty downscopingTokenSource. +// NewTokenSource returns a configured downscopingTokenSource. func NewTokenSource(ctx context.Context, conf DownscopingConfig) (oauth2.TokenSource, error) { if conf.RootSource == nil { return nil, fmt.Errorf("downscope: rootSource cannot be nil") diff --git a/google/downscope/example_test.go b/google/downscope/example_test.go index 061cf57..138b9f4 100644 --- a/google/downscope/example_test.go +++ b/google/downscope/example_test.go @@ -6,6 +6,7 @@ package downscope_test import ( "context" + "fmt" "golang.org/x/oauth2" "golang.org/x/oauth2/google/downscope" @@ -29,8 +30,13 @@ func ExampleNewTokenSource() { dts, err := downscope.NewTokenSource(ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary}) if err != nil { - _ = dts + fmt.Printf("failed to generate downscoped token source: %v", err) + return } + + // Enables automatic token refreshing + _ = oauth2.ReuseTokenSource(nil, dts) + // You can now use the token held in myTokenSource to make // Google Cloud Storage calls, as follows: