feat(option/internaloption): add new allowHardBoundTokens option (#2975)

Add allowHardBoundTokens option to the internaloption. This option will be used internally only to allow auto-generated clients to request a hard-bound tokens. Hard-bound tokens are tokens that include binding that must be enforced regardless of the IAM policy.

internal/settings.go

@@ -63,6 +63,7 @@ type DialSettings struct {
 	AllowNonDefaultServiceAccount bool
 	DefaultUniverseDomain         string
 	UniverseDomain                string
+	AllowHardBoundTokens          []string
 	Logger                        *slog.Logger
 	// Google API system parameters. For more information please read:
 	// https://cloud.google.com/apis/docs/system-parameters

option/internaloption/internaloption.go

@@ -186,6 +186,33 @@ func (w enableJwtWithScope) Apply(o *internal.DialSettings) {
 	o.EnableJwtWithScope = bool(w)
 }
 
+// AllowHardBoundTokens returns a ClientOption that allows libraries to request a hard-bound token.
+// Obtaining hard-bound tokens requires the connection to be established using either Application
+// Layer Transport Security (ALTS) or mutual TLS (mTLS) with S2A. For more information on ALTS,
+// see: https://cloud.google.com/docs/security/encryption-in-transit/application-layer-transport-security
+//
+// The AllowHardBoundTokens option accepts the following values (or a combination thereof):
+//
+//   - "MTLS_S2A": Allows obtaining hard-bound tokens when the connection uses mutual TLS with S2A.
+//   - "ALTS":     Allows obtaining hard-bound tokens when the connection uses ALTS.
+//
+// For example, to allow obtaining hard-bound tokens with either MTLS_S2A or ALTS, you would
+// provide both values (e.g., {"MTLS_S2A","ALTS"}).  If no value is provided, hard-bound tokens
+// will not be requested.
+//
+// It should only be used internally by generated clients.
+// This is an EXPERIMENTAL API and may be changed or removed in the future.
+func AllowHardBoundTokens(protocol ...string) option.ClientOption {
+	return allowHardBoundTokens(protocol)
+}
+
+type allowHardBoundTokens []string
+
+func (a allowHardBoundTokens) Apply(o *internal.DialSettings) {
+	o.AllowHardBoundTokens = make([]string, len(a))
+	copy(o.AllowHardBoundTokens, a)
+}
+
 // WithCredentials returns a client option to specify credentials which will be used to authenticate API calls.
 // This credential takes precedence over all other credential options.
 func WithCredentials(creds *google.Credentials) option.ClientOption {

option/internaloption/internaloption_test.go

@@ -40,6 +40,7 @@ func TestDefaultApply(t *testing.T) {
 		WithDefaultScopes("a"),
 		WithDefaultUniverseDomain("foo.com"),
 		WithDefaultAudience("audience"),
+		AllowHardBoundTokens("MTLS_S2A"),
 	}
 	var got internal.DialSettings
 	for _, opt := range opts {
@@ -52,6 +53,7 @@ func TestDefaultApply(t *testing.T) {
 		DefaultUniverseDomain:   "foo.com",
 		DefaultAudience:         "audience",
 		DefaultMTLSEndpoint:     "http://mtls.example.com:445",
+		AllowHardBoundTokens:    []string{"MTLS_S2A"},
 	}
 	ignore := []cmp.Option{
 		cmpopts.IgnoreUnexported(grpc.ClientConn{}),