google/downscope: update documentation

Change-Id: Ib4dfc7b554c1e7565cc61bc372a98ddd390e7453
GitHub-Last-Rev: 63894e56810431f8a45d381f4ffb123da1a1b8e0
GitHub-Pull-Request: golang/oauth2#512
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 <>
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
+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
+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
+"" 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 (
+	"fmt"
@@ -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: