Merge pull request #1 from Galadros/downscopeDocumentation

Merging with master to fix some PR oddities for downscoping documentation

google/downscope/downscoping.go

@@ -7,6 +7,30 @@ Package downscope implements the ability to downscope, or restrict, the
 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-base conditional
+access to the aforementioned resources.  For more information on IAM
+Credentials, 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.
 */
 package downscope
 
@@ -91,7 +115,7 @@ type downscopingTokenSource struct {
 	config DownscopingConfig
 }
 
-// NewTokenSource returns an empty downscopingTokenSource.
+// NewTokenSource returns an 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,11 +6,16 @@ package downscope_test
 
 import (
 	"context"
+	"fmt"
 
 	"golang.org/x/oauth2"
 	"golang.org/x/oauth2/google/downscope"
 )
 
+func Example() {
+
+}
+
 func ExampleNewTokenSource() {
 	ctx := context.Background()
 	// Initializes an accessBoundary with one Rule.
@@ -29,8 +34,12 @@ 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)
 	}
+
+	// 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: