google/downscope: update documentation

Change-Id: Ib4dfc7b554c1e7565cc61bc372a98ddd390e7453
GitHub-Last-Rev: 63894e5681
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>

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")

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: