From add980136395b64876f296b9bc36b534781fd45e Mon Sep 17 00:00:00 2001
From: Patrick Jones <ithuriel@google.com>
Date: Thu, 10 Jun 2021 14:55:41 -0700
Subject: [PATCH] Add exmaple showing how NewTokenSource should be called.

---
 google/downscope/downscoping.go      |  5 +++-
 google/downscope/downscoping_test.go | 41 ++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/google/downscope/downscoping.go b/google/downscope/downscoping.go
index 2b9d113..343d6b8 100644
--- a/google/downscope/downscoping.go
+++ b/google/downscope/downscoping.go
@@ -155,7 +155,10 @@ func downscopedTokenWithEndpoint(ctx context.Context, config DownscopingConfig,
 // NewTokenSource takes a root TokenSource and returns a downscoped TokenSource
 // with a subset of the permissions held by the root source.  The
 // CredentialAccessBoundary in the config defines the permissions held
-// by the new TokenSource.
+// by the new TokenSource.  Do note that the returned TokenSource is
+// an oauth2.StaticTokenSource.  If you wish to refresh this token automatically,
+// then initialize a locally defined TokenSource struct with the Token held
+// by the StaticTokenSource and wrap that TokenSource in an oauth2.ReuseTokenSource.
 func NewTokenSource(ctx context.Context, config DownscopingConfig) (oauth2.TokenSource, error) {
 	return downscopedTokenWithEndpoint(ctx, config, identityBindingEndpoint)
 }
diff --git a/google/downscope/downscoping_test.go b/google/downscope/downscoping_test.go
index ee75632..40eaba6 100644
--- a/google/downscope/downscoping_test.go
+++ b/google/downscope/downscoping_test.go
@@ -2,8 +2,11 @@ package downscope
 
 import (
 	"context"
+	"fmt"
 	"golang.org/x/oauth2"
+	"golang.org/x/oauth2/google"
 	"io/ioutil"
+	"log"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -54,3 +57,41 @@ func Test_DownscopedTokenSource(t *testing.T) {
 		t.Fatalf("Token() call failed with error %v", err)
 	}
 }
+
+func Example() {
+	ctx := context.Background()
+	availableResource := "//storage.googleapis.com/projects/_/buckets/foo"
+	availablePermissions := []string{"inRole:roles/storage.objectViewer"}
+
+
+	// Initializes an accessBoundary
+	myBoundary := AccessBoundary{make([]AccessBoundaryRule, 0)}
+
+	// Add a new rule to the AccessBoundary
+	myBoundary.AccessBoundaryRules = append(myBoundary.AccessBoundaryRules, AccessBoundaryRule{availableResource, availablePermissions, nil})
+
+	// Get the token source for Application Default Credentials (DefaultTokenSource is a shorthand
+	// for is a shortcut for FindDefaultCredentials(ctx, scope).TokenSource.
+	// This example assumes that you've defined the GOOGLE_APPLICATION_CREDENTIALS environment variable
+	rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform")
+	if err != nil {
+		log.Fatalf("failed to generate root token source; %v", err)
+		return
+	}
+	myTokenSource, err := NewTokenSource(context.Background(), DownscopingConfig{rootSource, myBoundary})
+	//myTokenSource, err := NewSource(rootSource, myBoundary)
+	if err != nil {
+		log.Fatalf("failed to generate downscoped token source: %v", err)
+		return
+	}
+	fmt.Printf("%+v\n", myTokenSource)
+	// You can now use the token held in myTokenSource to make
+	// Google Cloud Storage calls.  A short example follows.
+
+	// storageClient, err := storage.NewClient(ctx, option.WithTokenSource(myTokenSource))
+	// bkt := storageClient.Bucket(bucketName)
+	// obj := bkt.Object(objectName)
+	// rc, err := obj.NewReader(ctx)
+	// data, err := ioutil.ReadAll(rc)
+	return
+}
\ No newline at end of file