feat(gax): add API key authentication to ClientSettings

gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/InstantiatingGrpcChannelProvider.java

@@ -63,6 +63,8 @@
 import java.nio.charset.StandardCharsets;
 import java.security.GeneralSecurityException;
 import java.security.KeyStore;
+import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.Executor;
 import java.util.concurrent.ScheduledExecutorService;
@@ -407,8 +409,10 @@ ChannelCredentials createMtlsChannelCredentials() throws IOException, GeneralSec
   }
 
   private ManagedChannel createSingleChannel() throws IOException {
+    Map<String, String> mergedHeaders = mergeHeadersWithCredentialHeaders();
     GrpcHeaderInterceptor headerInterceptor =
-        new GrpcHeaderInterceptor(headerProvider.getHeaders());
+        new GrpcHeaderInterceptor(ImmutableMap.copyOf(mergedHeaders));
+
     GrpcMetadataHandlerInterceptor metadataHandlerInterceptor =
         new GrpcMetadataHandlerInterceptor();
 
@@ -496,6 +500,23 @@ private ManagedChannel createSingleChannel() throws IOException {
     return managedChannel;
   }
 
+  // dedup any headers explicitly set with headers provided by credential, with preference to
+  // credential headers
+  private Map<String, String> mergeHeadersWithCredentialHeaders() {
+    Map<String, String> userHeaders = new HashMap<>(headerProvider.getHeaders());
+    if (credentials != null) {
+      try {
+        Map<String, List<String>> credentialRequestMetatData = credentials.getRequestMetadata();
+        if (credentialRequestMetatData != null) {
+          userHeaders.keySet().removeAll(credentialRequestMetatData.keySet());
+        }
+      } catch (IOException e) {
+        // no-op, if we can't retrieve credentials metadata we will leave headers intact
+      }
+    }
+    return userHeaders;
+  }
+
   /**
    * Marked as Internal Api and intended for internal use. DirectPath must be enabled via the
    * settings and a few other configurations/settings must also be valid for the request to go

gax-java/gax-grpc/src/test/java/com/google/api/gax/grpc/InstantiatingGrpcChannelProviderTest.java

@@ -34,16 +34,19 @@
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.truth.Truth.assertThat;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import com.google.api.core.ApiFunction;
 import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider.Builder;
+import com.google.api.gax.rpc.FixedHeaderProvider;
 import com.google.api.gax.rpc.HeaderProvider;
 import com.google.api.gax.rpc.TransportChannel;
 import com.google.api.gax.rpc.TransportChannelProvider;
 import com.google.api.gax.rpc.internal.EnvironmentProvider;
 import com.google.api.gax.rpc.mtls.AbstractMtlsTransportChannelTest;
 import com.google.api.gax.rpc.mtls.MtlsProvider;
+import com.google.auth.ApiKeyCredentials;
 import com.google.auth.Credentials;
 import com.google.auth.oauth2.CloudShellCredentials;
 import com.google.auth.oauth2.ComputeEngineCredentials;
@@ -877,6 +880,82 @@ public void canUseDirectPath_nonGDUUniverseDomain() {
     Truth.assertThat(provider.canUseDirectPath()).isFalse();
   }
 
+  @Test
+  public void createChannel_handlesMatchCredentialAndExplicitHeaders() throws IOException {
+    ApiKeyCredentials apiKeyCredentials = ApiKeyCredentials.create("fake_api_key");
+    InstantiatingGrpcChannelProvider.Builder builder =
+        InstantiatingGrpcChannelProvider.newBuilder()
+            .setCredentials(apiKeyCredentials)
+            .setHeaderProvider(getHeaderProviderWithApiKeyHeader())
+            .setEndpoint("test.random.com:443");
+    InstantiatingGrpcChannelProvider provider = builder.build();
+
+    // calls createChannel
+    TransportChannel transportChannel = provider.getTransportChannel();
+
+    assertNotNull(transportChannel);
+    transportChannel.shutdownNow();
+  }
+
+  @Test
+  public void createChannel_handlesNullCredentials() throws IOException {
+    Map<String, String> header = new HashMap();
+    FixedHeaderProvider headerProvider = FixedHeaderProvider.create(header);
+    InstantiatingGrpcChannelProvider.Builder builder =
+        InstantiatingGrpcChannelProvider.newBuilder()
+            .setHeaderProvider(headerProvider)
+            .setEndpoint("test.random.com:443");
+    InstantiatingGrpcChannelProvider provider = builder.build();
+
+    // calls createChannel
+    TransportChannel transportChannel = provider.getTransportChannel();
+
+    assertNotNull(transportChannel);
+    transportChannel.shutdownNow();
+  }
+
+  @Test
+  public void createChannel_handlesNullCredentialsMetadataRequest() throws IOException {
+    Credentials credentials = Mockito.mock(Credentials.class);
+    Mockito.when(credentials.getRequestMetadata()).thenReturn(null);
+    InstantiatingGrpcChannelProvider.Builder builder =
+        InstantiatingGrpcChannelProvider.newBuilder()
+            .setHeaderProvider(getHeaderProviderWithApiKeyHeader())
+            .setEndpoint("test.random.com:443");
+    InstantiatingGrpcChannelProvider provider = builder.build();
+
+    // calls createChannel
+    TransportChannel transportChannel = provider.getTransportChannel();
+
+    assertNotNull(transportChannel);
+    transportChannel.shutdownNow();
+  }
+
+  @Test
+  public void createChannel_handlesErrorRetrievingCredentialsMetadataRequest() throws IOException {
+    Credentials credentials = Mockito.mock(Credentials.class);
+    Mockito.when(credentials.getRequestMetadata())
+        .thenThrow(new IOException("Error getting request metadata"));
+    InstantiatingGrpcChannelProvider.Builder builder =
+        InstantiatingGrpcChannelProvider.newBuilder()
+            .setHeaderProvider(getHeaderProviderWithApiKeyHeader())
+            .setEndpoint("test.random.com:443");
+    InstantiatingGrpcChannelProvider provider = builder.build();
+
+    // calls createChannel
+    TransportChannel transportChannel = provider.getTransportChannel();
+
+    assertNotNull(transportChannel);
+    transportChannel.shutdownNow();
+  }
+
+  private FixedHeaderProvider getHeaderProviderWithApiKeyHeader() {
+    String apiHeaderKey = "fake_api_key_2";
+    Map<String, String> header = new HashMap<>();
+    header.put("x-goog-api-key", apiHeaderKey);
+    return FixedHeaderProvider.create(header);
+  }
+
   private static class FakeLogHandler extends Handler {
 
     List<LogRecord> records = new ArrayList<>();

gax-java/gax/src/main/java/com/google/api/gax/rpc/ClientContext.java

@@ -43,6 +43,7 @@
 import com.google.api.gax.rpc.internal.QuotaProjectIdHidingCredentials;
 import com.google.api.gax.tracing.ApiTracerFactory;
 import com.google.api.gax.tracing.BaseApiTracerFactory;
+import com.google.auth.ApiKeyCredentials;
 import com.google.auth.Credentials;
 import com.google.auth.oauth2.GdchCredentials;
 import com.google.auto.value.AutoValue;
@@ -175,9 +176,9 @@ public static ClientContext create(StubSettings settings) throws IOException {
     // A valid EndpointContext should have been created in the StubSettings
     EndpointContext endpointContext = settings.getEndpointContext();
     String endpoint = endpointContext.resolvedEndpoint();
-
+    Credentials credentials = getCredentials(settings);
+    // check if need to adjust credentials/endpoint/endpointContext for GDC-H
     String settingsGdchApiAudience = settings.getGdchApiAudience();
-    Credentials credentials = settings.getCredentialsProvider().getCredentials();
     boolean usingGDCH = credentials instanceof GdchCredentials;
     if (usingGDCH) {
       // Can only determine if the GDC-H is being used via the Credentials. The Credentials object
@@ -187,22 +188,9 @@ public static ClientContext create(StubSettings settings) throws IOException {
       // Resolve the new endpoint with the GDC-H flow
       endpoint = endpointContext.resolvedEndpoint();
       // We recompute the GdchCredentials with the audience
-      String audienceString;
-      if (!Strings.isNullOrEmpty(settingsGdchApiAudience)) {
-        audienceString = settingsGdchApiAudience;
-      } else if (!Strings.isNullOrEmpty(endpoint)) {
-        audienceString = endpoint;
-      } else {
-        throw new IllegalArgumentException("Could not infer GDCH api audience from settings");
-      }
-
-      URI gdchAudienceUri;
-      try {
-        gdchAudienceUri = URI.create(audienceString);
-      } catch (IllegalArgumentException ex) { // thrown when passing a malformed uri string
-        throw new IllegalArgumentException("The GDC-H API audience string is not a valid URI", ex);
-      }
-      credentials = ((GdchCredentials) credentials).createWithGdchAudience(gdchAudienceUri);
+      credentials =
+          getGdchCredentials(
+              settingsGdchApiAudience, endpointContext.resolvedEndpoint(), credentials);
     } else if (!Strings.isNullOrEmpty(settingsGdchApiAudience)) {
       throw new IllegalArgumentException(
           "GDC-H API audience can only be set when using GdchCredentials");
@@ -291,6 +279,43 @@ public static ClientContext create(StubSettings settings) throws IOException {
         .build();
   }
 
+  /** Determines which credentials to use. API key overrides credentials provided by provider. */
+  private static Credentials getCredentials(StubSettings settings) throws IOException {
+    Credentials credentials;
+    if (settings.getApiKey() != null) {
+      // if API key exists it becomes the default credential
+      credentials = ApiKeyCredentials.create(settings.getApiKey());
+    } else {
+      credentials = settings.getCredentialsProvider().getCredentials();
+    }
+    return credentials;
+  }
+
+  /**
+   * Constructs a new {@link com.google.auth.Credentials} object based on credentials provided with
+   * a GDC-H audience
+   */
+  private static Credentials getGdchCredentials(
+      String settingsGdchApiAudience, String endpoint, Credentials credentials) throws IOException {
+    String audienceString;
+    if (!Strings.isNullOrEmpty(settingsGdchApiAudience)) {
+      audienceString = settingsGdchApiAudience;
+    } else if (!Strings.isNullOrEmpty(endpoint)) {
+      audienceString = endpoint;
+    } else {
+      throw new IllegalArgumentException("Could not infer GDCH api audience from settings");
+    }
+
+    URI gdchAudienceUri;
+    try {
+      gdchAudienceUri = URI.create(audienceString);
+    } catch (IllegalArgumentException ex) { // thrown when passing a malformed uri string
+      throw new IllegalArgumentException("The GDC-H API audience string is not a valid URI", ex);
+    }
+    credentials = ((GdchCredentials) credentials).createWithGdchAudience(gdchAudienceUri);
+    return credentials;
+  }
+
   /**
    * Getting a header map from HeaderProvider and InternalHeaderProvider from settings with Quota
    * Project Id.

gax-java/gax/src/main/java/com/google/api/gax/rpc/ClientSettings.java

@@ -112,6 +112,11 @@ public final WatchdogProvider getWatchdogProvider() {
     return stubSettings.getStreamWatchdogProvider();
   }
 
+  /** Gets the API Key that should be used for authentication. */
+  public final String getApiKey() {
+    return stubSettings.getApiKey();
+  }
+
   /** This method is obsolete. Use {@link #getWatchdogCheckIntervalDuration()} instead. */
   @Nonnull
   @ObsoleteApi("Use getWatchdogCheckIntervalDuration() instead")
@@ -144,6 +149,7 @@ public String toString() {
         .add("watchdogProvider", getWatchdogProvider())
         .add("watchdogCheckInterval", getWatchdogCheckInterval())
         .add("gdchApiAudience", getGdchApiAudience())
+        .add("apiKey", getApiKey())
         .toString();
   }
 
@@ -302,6 +308,21 @@ public B setGdchApiAudience(@Nullable String gdchApiAudience) {
       return self();
     }
 
+    /**
+     * Sets the API key. The API key will get translated to an {@link
+     * com.google.auth.ApiKeyCredentials} and stored in {@link ClientContext}.
+     *
+     * <p>API Key authorization is not supported for every product. Please check the documentation
+     * for each product to confirm if it is supported.
+     *
+     * <p>Note: If you set an API key and {@link CredentialsProvider} in the same ClientSettings the
+     * API key will override any credentials provided.
+     */
+    public B setApiKey(String apiKey) {
+      stubSettings.setApiKey(apiKey);
+      return self();
+    }
+
     /**
      * Gets the ExecutorProvider that was previously set on this Builder. This ExecutorProvider is
      * to use for running asynchronous API call logic (such as retries and long-running operations),
@@ -364,6 +385,11 @@ public WatchdogProvider getWatchdogProvider() {
       return stubSettings.getStreamWatchdogProvider();
     }
 
+    /** Gets the API Key that was previously set on this Builder. */
+    public String getApiKey() {
+      return stubSettings.getApiKey();
+    }
+
     /** This method is obsolete. Use {@link #getWatchdogCheckIntervalDuration()} instead */
     @Nullable
     @ObsoleteApi("Use getWatchdogCheckIntervalDuration() instead")
@@ -405,6 +431,7 @@ public String toString() {
           .add("watchdogProvider", getWatchdogProvider())
           .add("watchdogCheckInterval", getWatchdogCheckIntervalDuration())
           .add("gdchApiAudience", getGdchApiAudience())
+          .add("apiKey", getApiKey())
           .toString();
     }
   }

gax-java/gax/src/main/java/com/google/api/gax/rpc/StubSettings.java

@@ -82,6 +82,7 @@ public abstract class StubSettings<SettingsT extends StubSettings<SettingsT>> {
   // Track if deprecated setExecutorProvider is called
   private boolean deprecatedExecutorProviderSet;
   @Nonnull private final EndpointContext endpointContext;
+  private final String apiKey;
 
   /**
    * Indicate when creating transport whether it is allowed to use mTLS endpoint instead of the
@@ -107,6 +108,7 @@ protected StubSettings(Builder builder) {
     this.deprecatedExecutorProviderSet = builder.deprecatedExecutorProviderSet;
     this.gdchApiAudience = builder.gdchApiAudience;
     this.endpointContext = buildEndpointContext(builder);
+    this.apiKey = builder.apiKey;
   }
 
   /**
@@ -234,6 +236,11 @@ public final String getGdchApiAudience() {
     return gdchApiAudience;
   }
 
+  /** Gets the API Key that should be used for authentication. */
+  public final String getApiKey() {
+    return apiKey;
+  }
+
   @Override
   public String toString() {
     return MoreObjects.toStringHelper(this)
@@ -252,6 +259,7 @@ public String toString() {
         .add("streamWatchdogCheckInterval", streamWatchdogCheckInterval)
         .add("tracerFactory", tracerFactory)
         .add("gdchApiAudience", gdchApiAudience)
+        .add("apiKey", apiKey)
         .toString();
   }
 
@@ -277,6 +285,7 @@ public abstract static class Builder<
     private boolean deprecatedExecutorProviderSet;
     private String universeDomain;
     private final EndpointContext endpointContext;
+    private String apiKey;
 
     /**
      * Indicate when creating transport whether it is allowed to use mTLS endpoint instead of the
@@ -301,6 +310,7 @@ protected Builder(StubSettings settings) {
       this.tracerFactory = settings.tracerFactory;
       this.deprecatedExecutorProviderSet = settings.deprecatedExecutorProviderSet;
       this.gdchApiAudience = settings.gdchApiAudience;
+      this.apiKey = settings.apiKey;
 
       // The follow settings will be set to the original user configurations as the
       // EndpointContext will be rebuilt in the constructor.
@@ -353,6 +363,7 @@ protected Builder(ClientContext clientContext) {
         this.mtlsEndpoint = null;
         this.switchToMtlsEndpointAllowed = false;
         this.universeDomain = null;
+        this.apiKey = null;
         // Attempt to create an empty, non-functioning EndpointContext by default. The client will
         // have
         // a valid EndpointContext with user configurations after the client has been initialized.
@@ -574,6 +585,21 @@ public B setTracerFactory(@Nonnull ApiTracerFactory tracerFactory) {
       return self();
     }
 
+    /**
+     * Sets the API key. The API key will get translated to an {@link
+     * com.google.auth.ApiKeyCredentials} and stored in {@link ClientContext}.
+     *
+     * <p>API Key authorization is not supported for every product. Please check the documentation
+     * for each product to confirm if it is supported.
+     *
+     * <p>Note: If you set an API key and {@link CredentialsProvider} in the same ClientSettings the
+     * API key will override any credentials provided.
+     */
+    public B setApiKey(String apiKey) {
+      this.apiKey = apiKey;
+      return self();
+    }
+
     /** @deprecated Please use {@link #getBackgroundExecutorProvider()}. */
     @Deprecated
     public ExecutorProvider getExecutorProvider() {
@@ -616,6 +642,11 @@ public ApiClock getClock() {
       return clock;
     }
 
+    /** Gets the API Key that was previously set on this Builder. */
+    public final String getApiKey() {
+      return apiKey;
+    }
+
     /**
      * @return the resolved endpoint when the Builder was created. If invoked after
      *     `StubSettings.newBuilder()` is called, it will return the clientSettingsEndpoint value.