feat(auth): refactor public sigs to use Credentials (#9603)

This refactors all public surfaces to use Credentials rather than TokenProvider as the main abstraction.

Part 2 of 3 of breaking changes for the auth module.

Author: codyoss

auth/credentials/doc.go

@@ -74,8 +74,8 @@
 //
 // # Credentials
 //
-// The [Credentials] type represents Google credentials, including Application
-// Default Credentials.
+// The [cloud.google.com/go/auth.Credentials] type represents Google
+// credentials, including Application Default Credentials.
 //
 // Use [DetectDefault] to obtain Application Default Credentials.
 //

auth/credentials/example_test.go

@@ -30,7 +30,7 @@ func ExampleDetectDefault() {
 		log.Fatal(err)
 	}
 	client, err := httptransport.NewClient(&httptransport.Options{
-		TokenProvider: creds,
+		Credentials: creds,
 	})
 	if err != nil {
 		log.Fatal(err)
@@ -55,7 +55,7 @@ func ExampleDetectDefault_withFilepath() {
 		log.Fatal(err)
 	}
 	client, err := httptransport.NewClient(&httptransport.Options{
-		TokenProvider: creds,
+		Credentials: creds,
 	})
 	if err != nil {
 		log.Fatal(err)
@@ -76,7 +76,7 @@ func ExampleDetectDefault_withJSON() {
 		log.Fatal(err)
 	}
 	client, err := httptransport.NewClient(&httptransport.Options{
-		TokenProvider: creds,
+		Credentials: creds,
 	})
 	if err != nil {
 		log.Fatal(err)

auth/downscope/doc.go

@@ -33,7 +33,7 @@
 // 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 NewTokenProvider example
+// modify specific google cloud storage buckets. See the NewCredentials 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

auth/downscope/downscope.go

@@ -28,17 +28,16 @@ import (
 
 var identityBindingEndpoint = "https://sts.googleapis.com/v1/token"
 
-// Options for configuring [NewTokenProvider].
+// Options for configuring [NewCredentials].
 type Options struct {
-	// BaseProvider is the [cloud.google.com/go/auth.TokenProvider] used to
-	// create the downscoped provider. The downscoped provider therefore has
-	// some subset of the accesses of the original BaseProvider. Required.
-	BaseProvider auth.TokenProvider
-	// Rules defines the accesses held by the new downscoped provider. One or
+	// Credentials is the [cloud.google.com/go/auth.Credentials] used to
+	// create the downscoped credentials. Required.
+	Credentials *auth.Credentials
+	// Rules defines the accesses held by the new downscoped credentials. One or
 	// more AccessBoundaryRules are required to define permissions for the new
-	// downscoped provider. Each one defines an access (or set of accesses) that
-	// the new provider has to a given resource. There can be a maximum of 10
-	// AccessBoundaryRules. Required.
+	// downscoped credentials. Each one defines an access (or set of accesses)
+	//that the new credentials has to a given resource. There can be a maximum
+	// of 10 AccessBoundaryRules. Required.
 	Rules []AccessBoundaryRule
 	// Client configures the underlying client used to make network requests
 	// when fetching tokens. Optional.
@@ -84,14 +83,15 @@ type AvailabilityCondition struct {
 	Description string `json:"description,omitempty"`
 }
 
-// NewTokenProvider returns a [cloud.google.com/go/auth.TokenProvider] that is
-// more restrictive than [Options.BaseProvider] provided.
-func NewTokenProvider(opts *Options) (auth.TokenProvider, error) {
+// NewCredentials returns a [cloud.google.com/go/auth.Credentials] that is
+// more restrictive than [Options.Credentials] provided. The new credentials
+// will delegate to the base credentials for all non-token activity.
+func NewCredentials(opts *Options) (*auth.Credentials, error) {
 	if opts == nil {
 		return nil, fmt.Errorf("downscope: providing opts is required")
 	}
-	if opts.BaseProvider == nil {
-		return nil, fmt.Errorf("downscope: BaseProvider cannot be nil")
+	if opts.Credentials == nil {
+		return nil, fmt.Errorf("downscope: Credentials cannot be nil")
 	}
 	if len(opts.Rules) == 0 {
 		return nil, fmt.Errorf("downscope: length of AccessBoundaryRules must be at least 1")
@@ -107,7 +107,12 @@ func NewTokenProvider(opts *Options) (auth.TokenProvider, error) {
 			return nil, fmt.Errorf("downscope: all rules must provide at least one permission")
 		}
 	}
-	return &downscopedTokenProvider{Options: opts, Client: opts.client()}, nil
+	return auth.NewCredentials(&auth.CredentialsOptions{
+		TokenProvider:          &downscopedTokenProvider{Options: opts, Client: opts.client()},
+		ProjectIDProvider:      auth.CredentialsPropertyFunc(opts.Credentials.ProjectID),
+		QuotaProjectIDProvider: auth.CredentialsPropertyFunc(opts.Credentials.QuotaProjectID),
+		UniverseDomainProvider: auth.CredentialsPropertyFunc(opts.Credentials.UniverseDomain),
+	}), nil
 }
 
 // downscopedTokenProvider is used to retrieve a downscoped tokens.
@@ -138,7 +143,7 @@ func (dts *downscopedTokenProvider) Token(ctx context.Context) (*auth.Token, err
 		},
 	}
 
-	tok, err := dts.Options.BaseProvider.Token(ctx)
+	tok, err := dts.Options.Credentials.Token(ctx)
 	if err != nil {
 		return nil, fmt.Errorf("downscope: unable to obtain root token: %w", err)
 	}

auth/downscope/downscope_test.go

@@ -29,6 +29,12 @@ var (
 	standardRespBody = `{"access_token":"fake_token","expires_in":42,"token_type":"Bearer"}`
 )
 
+func staticCredentials(tok string) *auth.Credentials {
+	return auth.NewCredentials(&auth.CredentialsOptions{
+		TokenProvider: staticTokenProvider(tok),
+	})
+}
+
 type staticTokenProvider string
 
 func (s staticTokenProvider) Token(context.Context) (*auth.Token, error) {
@@ -58,8 +64,8 @@ func TestNewTokenProvider(t *testing.T) {
 	oldEndpoint := identityBindingEndpoint
 	identityBindingEndpoint = ts.URL
 	t.Cleanup(func() { identityBindingEndpoint = oldEndpoint })
-	tp, err := NewTokenProvider(&Options{
-		BaseProvider: staticTokenProvider("token_base"),
+	creds, err := NewCredentials(&Options{
+		Credentials: staticCredentials("token_base"),
 		Rules: []AccessBoundaryRule{
 			{
 				AvailableResource:    "test1",
@@ -70,16 +76,16 @@ func TestNewTokenProvider(t *testing.T) {
 	if err != nil {
 		t.Fatalf("NewTokenProvider() = %v", err)
 	}
-	tok, err := tp.Token(context.Background())
+	tok, err := creds.Token(context.Background())
 	if err != nil {
-		t.Fatalf("NewDownscopedTokenSource failed with error: %v", err)
+		t.Fatalf("Token failed with error: %v", err)
 	}
 	if want := "fake_token"; tok.Value != want {
 		t.Fatalf("got %v, want %v", tok.Value, want)
 	}
 }
 
-func TestTestNewTokenProvider_Validations(t *testing.T) {
+func TestTestNewCredentials_Validations(t *testing.T) {
 	tests := []struct {
 		name string
 		opts *Options
@@ -95,27 +101,27 @@ func TestTestNewTokenProvider_Validations(t *testing.T) {
 		{
 			name: "no rules",
 			opts: &Options{
-				BaseProvider: staticTokenProvider("token_base"),
+				Credentials: staticCredentials("token_base"),
 			},
 		},
 		{
 			name: "too many rules",
 			opts: &Options{
-				BaseProvider: staticTokenProvider("token_base"),
-				Rules:        []AccessBoundaryRule{{}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}},
+				Credentials: staticCredentials("token_base"),
+				Rules:       []AccessBoundaryRule{{}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}},
 			},
 		},
 		{
 			name: "no resource",
 			opts: &Options{
-				BaseProvider: staticTokenProvider("token_base"),
-				Rules:        []AccessBoundaryRule{{}},
+				Credentials: staticCredentials("token_base"),
+				Rules:       []AccessBoundaryRule{{}},
 			},
 		},
 		{
 			name: "no perm",
 			opts: &Options{
-				BaseProvider: staticTokenProvider("token_base"),
+				Credentials: staticCredentials("token_base"),
 				Rules: []AccessBoundaryRule{{
 					AvailableResource: "resource",
 				}},
@@ -124,7 +130,7 @@ func TestTestNewTokenProvider_Validations(t *testing.T) {
 	}
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
-			if _, err := NewTokenProvider(test.opts); err == nil {
+			if _, err := NewCredentials(test.opts); err == nil {
 				t.Fatal("want non-nil err")
 			}
 		})

auth/downscope/example_test.go

@@ -22,7 +22,7 @@ import (
 	"cloud.google.com/go/auth/downscope"
 )
 
-func ExampleNewTokenProvider() {
+func ExampleNewCredentials() {
 	// 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.
@@ -43,13 +43,13 @@ func ExampleNewTokenProvider() {
 	baseProvider, err := credentials.DetectDefault(&credentials.DetectOptions{
 		Scopes: []string{"https://www.googleapis.com/auth/cloud-platform"},
 	})
-	tp, err := downscope.NewTokenProvider(&downscope.Options{BaseProvider: baseProvider, Rules: accessBoundary})
+	creds, err := downscope.NewCredentials(&downscope.Options{Credentials: baseProvider, Rules: accessBoundary})
 	if err != nil {
 		fmt.Printf("failed to generate downscoped token provider: %v", err)
 		return
 	}
 
-	tok, err := tp.Token(ctx)
+	tok, err := creds.Token(ctx)
 	if err != nil {
 		fmt.Printf("failed to generate token: %v", err)
 		return

auth/downscope/integration_test.go

@@ -91,17 +91,17 @@ func TestDownscopedToken(t *testing.T) {
 	}
 }
 
-func testDownscopedToken(t *testing.T, rule downscope.AccessBoundaryRule, objectName string, tp auth.TokenProvider) error {
+func testDownscopedToken(t *testing.T, rule downscope.AccessBoundaryRule, objectName string, creds *auth.Credentials) error {
 	t.Helper()
 	ctx := context.Background()
-	tp, err := downscope.NewTokenProvider(&downscope.Options{BaseProvider: tp, Rules: []downscope.AccessBoundaryRule{rule}})
+	creds, err := downscope.NewCredentials(&downscope.Options{Credentials: creds, Rules: []downscope.AccessBoundaryRule{rule}})
 	if err != nil {
-		return fmt.Errorf("downscope.NewTokenProvider() = %v", err)
+		return fmt.Errorf("downscope.NewCredentials() = %v", err)
 	}
 
 	ctx, cancel := context.WithTimeout(ctx, time.Second*30)
 	defer cancel()
-	client := testgcs.NewClient(tp)
+	client := testgcs.NewClient(creds)
 	resp, err := client.DownloadObject(ctx, bucket, objectName)
 	if err != nil {
 		return err

auth/example_test.go

@@ -53,7 +53,9 @@ func ExampleNew2LOTokenProvider() {
 		log.Fatal(err)
 	}
 	client, err := httptransport.NewClient(&httptransport.Options{
-		TokenProvider: tp,
+		Credentials: auth.NewCredentials(&auth.CredentialsOptions{
+			TokenProvider: tp,
+		}),
 	})
 	if err != nil {
 		log.Fatal(err)

auth/grpctransport/dial_socketopt_test.go

@@ -26,6 +26,7 @@ import (
 	"testing"
 	"time"
 
+	"cloud.google.com/go/auth"
 	"google.golang.org/grpc"
 )
 
@@ -107,9 +108,11 @@ func TestDialWithDirectPathEnabled(t *testing.T) {
 	})
 
 	pool, err := Dial(ctx, true, &Options{
-		TokenProvider: staticTP("hey"),
-		GRPCDialOpts:  []grpc.DialOption{userDialer},
-		Endpoint:      "example.google.com:443",
+		Credentials: auth.NewCredentials(&auth.CredentialsOptions{
+			TokenProvider: staticTP("hey"),
+		}),
+		GRPCDialOpts: []grpc.DialOption{userDialer},
+		Endpoint:     "example.google.com:443",
 		InternalOptions: &InternalOptions{
 			EnableDirectPath: true,
 		},

auth/grpctransport/directpath.go

@@ -90,11 +90,11 @@ func isDirectPathXdsUsed(o *Options) bool {
 // configureDirectPath returns some dial options and an endpoint to use if the
 // configuration allows the use of direct path. If it does not the provided
 // grpcOpts and endpoint are returned.
-func configureDirectPath(grpcOpts []grpc.DialOption, opts *Options, endpoint string, creds auth.TokenProvider) ([]grpc.DialOption, string) {
+func configureDirectPath(grpcOpts []grpc.DialOption, opts *Options, endpoint string, creds *auth.Credentials) ([]grpc.DialOption, string) {
 	if isDirectPathEnabled(endpoint, opts) && metadata.OnGCE() && isTokenProviderDirectPathCompatible(creds, opts) {
 		// Overwrite all of the previously specific DialOptions, DirectPath uses its own set of credentials and certificates.
 		grpcOpts = []grpc.DialOption{
-			grpc.WithCredentialsBundle(grpcgoogle.NewDefaultCredentialsWithOptions(grpcgoogle.DefaultCredentialsOptions{PerRPCCreds: &grpcTokenProvider{TokenProvider: creds}}))}
+			grpc.WithCredentialsBundle(grpcgoogle.NewDefaultCredentialsWithOptions(grpcgoogle.DefaultCredentialsOptions{PerRPCCreds: &grpcCredentialsProvider{creds: creds}}))}
 		if timeoutDialerOption != nil {
 			grpcOpts = append(grpcOpts, timeoutDialerOption)
 		}