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 <codyoss@google.com>
Reviewed-by: Chris Broadfoot <cbro@golang.org>
Trust: Cody Oss <codyoss@google.com>
Trust: Chris Broadfoot <cbro@golang.org>
Run-TryBot: Cody Oss <codyoss@google.com>
Run-TryBot: Chris Broadfoot <cbro@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
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 @@
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 @@
import (
"context"
+ "fmt"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google/downscope"
@@ -29,8 +30,13 @@
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:
