downscope: add new examples and update existing ones.

google/downscope/tokenbroker_test.go

@@ -7,12 +7,17 @@ package downscope_test
 import (
 	"context"
 	"fmt"
+	"golang.org/x/oauth2/google"
 
 	"golang.org/x/oauth2"
 	"golang.org/x/oauth2/google/downscope"
 )
 
+
+
 func ExampleNewTokenSource() {
+	// This shows how to generate a downscoped token.  This code would be run on the
+	// token broker, which holds the root token used to generate the downscoped token.
 	ctx := context.Background()
 	// Initializes an accessBoundary with one Rule.
 	accessBoundary := []downscope.AccessBoundaryRule{
@@ -26,18 +31,26 @@ func ExampleNewTokenSource() {
 	// This Source can be initialized in multiple ways; the following example uses
 	// Application Default Credentials.
 
-	// rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform")
+	rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform")
 
 	dts, err := downscope.NewTokenSource(ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary})
 	if err != nil {
 		fmt.Printf("failed to generate downscoped token source: %v", err)
+		return
 	}
 
-	// Enables automatic token refreshing
-	_ = oauth2.ReuseTokenSource(nil, dts)
+	tok, err := dts.Token()
+	if err != nil {
+		fmt.Printf("failed to generate token: %v", err)
+		return
+	}
+	_ = tok
+	// You can now pass tok to a token consumer however you wish, such as exposing
+	// a REST API and sending it over HTTP.
 
-	// You can now use the token held in myTokenSource to make
+	// You can instead use the token held in myTokenSource to make
 	// Google Cloud Storage calls, as follows:
 
 	// storageClient, err := storage.NewClient(ctx, option.WithTokenSource(myTokenSource))
+
 }

google/downscope/tokenconsumer_test.go

@@ -0,0 +1,44 @@
+package downscope_test
+
+import (
+	"golang.org/x/oauth2"
+)
+
+type localTokenSource struct {
+	requestedPerms []string
+	requestedObject string
+	brokerURL string
+}
+
+func (localTokenSource) Token() (*oauth2.Token, error){
+	var remoteToken oauth2.Token
+	// retrieve remoteToken, an oauth2.Token, from token broker
+	return &remoteToken, nil
+}
+
+
+func Example() {
+	// A token consumer should define their own tokenSource.  In the Token() method,
+	// it should send a query to a token broker requesting a downscoped token.
+	// The token broker holds the root credential that is used to generate the
+	// downscoped token.
+
+	thisTokenSource := localTokenSource{
+		requestedPerms: []string{"inRole:roles/storage.objectViewer"},
+		requestedObject: "//storage.googleapis.com/projects/_/buckets/foo",
+		brokerURL: "yourURL.com/internal/broker",
+	}
+
+	// Wrap the TokenSource in an oauth2.ReuseTokenSource to enable automatic refreshing
+	refreshableTS := oauth2.ReuseTokenSource(nil, thisTokenSource)
+
+
+	// You can now use the token source to access Google Cloud Storage resources as follows.
+
+	// storageClient, err := storage.NewClient(ctx, option.WithTokenSource(refreshableTS))
+	// bkt := storageClient.Bucket(bucketName)
+	// obj := bkt.Object(objectName)
+	// rc, err := obj.NewReader(ctx)
+	// defer rc.Close()
+	// data, err := ioutil.ReadAll(rc)
+}