feat: add metric headers

credentials/java/com/google/auth/CredentialType.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *    * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *    * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *
+ *    * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package com.google.auth;
+
+public enum CredentialType {
+  USER_CREDENTIALS("u"),
+  SERVICE_ACCOUNT_CREDENTIALS_AT("sa"),
+  SERVICE_ACCOUNT_CREDENTIALS_JWT("jwt"),
+  VM_CREDENTIALS("mds"),
+  IMPERSONATED_CREDENTIALS("imp"),
+  UNKNOWN("unknown");
+
+  private String label;
+
+  private CredentialType(String label) {
+    this.label = label;
+  }
+
+  public String getLabel() {
+    return label;
+  }
+}

credentials/java/com/google/auth/Credentials.java

@@ -45,6 +45,8 @@ public abstract class Credentials implements Serializable {
 
   public static final String GOOGLE_DEFAULT_UNIVERSE = "googleapis.com";
 
+  private CredentialType credentialType = CredentialType.UNKNOWN;
+
   /**
    * A constant string name describing the authentication technology.
    *
@@ -70,6 +72,14 @@ public String getUniverseDomain() throws IOException {
     return GOOGLE_DEFAULT_UNIVERSE;
   }
 
+  public CredentialType getCredentialType() {
+    return this.credentialType;
+  }
+
+  public void setCredentialType(CredentialType credentialType) {
+    this.credentialType = credentialType;
+  }
+
   /**
    * Get the current request metadata, refreshing tokens if required.
    *

oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java

@@ -41,10 +41,12 @@
 import com.google.api.client.http.HttpStatusCodes;
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.util.GenericData;
+import com.google.auth.CredentialType;
 import com.google.auth.Credentials;
 import com.google.auth.Retryable;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.HttpTransportFactory;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Joiner;
 import com.google.common.base.MoreObjects.ToStringHelper;
@@ -133,7 +135,7 @@ public class ComputeEngineCredentials extends GoogleCredentials
    */
   private ComputeEngineCredentials(ComputeEngineCredentials.Builder builder) {
     super(builder);
-
+    this.setCredentialType(CredentialType.VM_CREDENTIALS);
     this.transportFactory =
         firstNonNull(
             builder.getHttpTransportFactory(),
@@ -234,7 +236,7 @@ public String getUniverseDomain() throws IOException {
   }
 
   private String getUniverseDomainFromMetadata() throws IOException {
-    HttpResponse response = getMetadataResponse(getUniverseDomainUrl());
+    HttpResponse response = getMetadataResponse(getUniverseDomainUrl(), RequestType.UNSPECIFIED);
     int statusCode = response.getStatusCode();
     if (statusCode == HttpStatusCodes.STATUS_CODE_NOT_FOUND) {
       return Credentials.GOOGLE_DEFAULT_UNIVERSE;
@@ -260,7 +262,8 @@ private String getUniverseDomainFromMetadata() throws IOException {
   /** Refresh the access token by getting it from the GCE metadata server */
   @Override
   public AccessToken refreshAccessToken() throws IOException {
-    HttpResponse response = getMetadataResponse(createTokenUrlWithScopes());
+    HttpResponse response =
+        getMetadataResponse(createTokenUrlWithScopes(), RequestType.ACCESS_TOKEN_REQUEST);
     int statusCode = response.getStatusCode();
     if (statusCode == HttpStatusCodes.STATUS_CODE_NOT_FOUND) {
       throw new IOException(
@@ -325,7 +328,8 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
       }
     }
     documentUrl.set("audience", targetAudience);
-    HttpResponse response = getMetadataResponse(documentUrl.toString());
+    HttpResponse response =
+        getMetadataResponse(documentUrl.toString(), RequestType.ID_TOKEN_REQUEST);
     InputStream content = response.getContent();
     if (content == null) {
       throw new IOException("Empty content from metadata token server request.");
@@ -334,13 +338,22 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
     return IdToken.create(rawToken);
   }
 
-  private HttpResponse getMetadataResponse(String url) throws IOException {
+  private HttpResponse getMetadataResponse(String url, RequestType requestType) throws IOException {
     GenericUrl genericUrl = new GenericUrl(url);
     HttpRequest request =
         transportFactory.create().createRequestFactory().buildGetRequest(genericUrl);
     JsonObjectParser parser = new JsonObjectParser(OAuth2Utils.JSON_FACTORY);
     request.setParser(parser);
     request.getHeaders().set(METADATA_FLAVOR, GOOGLE);
+    // do not send metric header for getUniverseDomain and getAccount
+    if (requestType != RequestType.UNSPECIFIED) {
+      request
+          .getHeaders()
+          .set(
+              MetricsUtils.API_CLIENT_HEADER,
+              MetricsUtils.getGoogleCredentialsMetricsHeader(requestType, getCredentialType()));
+    }
+
     request.setThrowExceptionOnExecuteError(false);
     HttpResponse response;
     try {
@@ -440,7 +453,12 @@ private static boolean pingComputeEngineMetadata(
             transportFactory.create().createRequestFactory().buildGetRequest(tokenUrl);
         request.setConnectTimeout(COMPUTE_PING_CONNECTION_TIMEOUT_MS);
         request.getHeaders().set(METADATA_FLAVOR, GOOGLE);
-
+        request
+            .getHeaders()
+            .set(
+                MetricsUtils.API_CLIENT_HEADER,
+                MetricsUtils.getGoogleCredentialsMetricsHeader(
+                    RequestType.METADATA_SERVER_PIN, CredentialType.UNKNOWN));
         HttpResponse response = request.execute();
         try {
           // Internet providers can return a generic response to all requests, so it is necessary
@@ -588,7 +606,7 @@ public byte[] sign(byte[] toSign) {
   }
 
   private String getDefaultServiceAccount() throws IOException {
-    HttpResponse response = getMetadataResponse(getServiceAccountsUrl());
+    HttpResponse response = getMetadataResponse(getServiceAccountsUrl(), RequestType.UNSPECIFIED);
     int statusCode = response.getStatusCode();
     if (statusCode == HttpStatusCodes.STATUS_CODE_NOT_FOUND) {
       throw new IOException(

oauth2_http/java/com/google/auth/oauth2/IamUtils.java

@@ -44,9 +44,11 @@
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.util.ExponentialBackOff;
 import com.google.api.client.util.GenericData;
+import com.google.auth.CredentialType;
 import com.google.auth.Credentials;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.HttpCredentialsAdapter;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.io.BaseEncoding;
 import java.io.IOException;
 import java.io.InputStream;
@@ -178,6 +180,7 @@ private static String getSignature(
    * @param transport transport used for building the HTTP request
    * @param targetAudience the audience the issued ID token should include
    * @param additionalFields additional fields to send in the IAM call
+   * @param credentialType credential type for credential making this call
    * @return IdToken issed to the serviceAccount
    * @throws IOException if the IdToken cannot be issued.
    * @see <a
@@ -189,7 +192,8 @@ static IdToken getIdToken(
       HttpTransport transport,
       String targetAudience,
       boolean includeEmail,
-      Map<String, ?> additionalFields)
+      Map<String, ?> additionalFields,
+      CredentialType credentialType)
       throws IOException {
 
     String idTokenUrl = String.format(ID_TOKEN_URL_FORMAT, serviceAccountEmail);
@@ -211,6 +215,13 @@ static IdToken getIdToken(
     request.setParser(parser);
     request.setThrowExceptionOnExecuteError(false);
 
+    request
+        .getHeaders()
+        .set(
+            MetricsUtils.API_CLIENT_HEADER,
+            MetricsUtils.getGoogleCredentialsMetricsHeader(
+                RequestType.ID_TOKEN_REQUEST, credentialType));
+
     HttpResponse response = request.execute();
     int statusCode = response.getStatusCode();
     if (statusCode >= 400 && statusCode < HttpStatusCodes.STATUS_CODE_SERVER_ERROR) {

oauth2_http/java/com/google/auth/oauth2/ImpersonatedCredentials.java

@@ -43,9 +43,11 @@
 import com.google.api.client.http.json.JsonHttpContent;
 import com.google.api.client.json.JsonObjectParser;
 import com.google.api.client.util.GenericData;
+import com.google.auth.CredentialType;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.HttpCredentialsAdapter;
 import com.google.auth.http.HttpTransportFactory;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects;
 import com.google.common.collect.ImmutableMap;
@@ -452,6 +454,7 @@ public ImpersonatedCredentials createWithCustomCalendar(Calendar calendar) {
 
   private ImpersonatedCredentials(Builder builder) {
     super(builder);
+    this.setCredentialType(CredentialType.IMPERSONATED_CREDENTIALS);
     this.sourceCredentials = builder.getSourceCredentials();
     this.targetPrincipal = builder.getTargetPrincipal();
     this.delegates = builder.getDelegates();
@@ -508,6 +511,12 @@ public AccessToken refreshAccessToken() throws IOException {
     HttpRequest request = requestFactory.buildPostRequest(url, requestContent);
     adapter.initialize(request);
     request.setParser(parser);
+    request
+        .getHeaders()
+        .set(
+            MetricsUtils.API_CLIENT_HEADER,
+            MetricsUtils.getGoogleCredentialsMetricsHeader(
+                RequestType.ACCESS_TOKEN_REQUEST, getCredentialType()));
 
     HttpResponse response = null;
     try {
@@ -557,7 +566,8 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
         transportFactory.create(),
         targetAudience,
         includeEmail,
-        ImmutableMap.of("delegates", this.delegates));
+        ImmutableMap.of("delegates", this.delegates),
+        getCredentialType());
   }
 
   @Override

oauth2_http/java/com/google/auth/oauth2/MetricsUtils.java

@@ -31,6 +31,7 @@
 
 package com.google.auth.oauth2;
 
+import com.google.auth.CredentialType;
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.Properties;
@@ -67,4 +68,44 @@ private static String getAuthLibraryVersion() {
     }
     return version;
   }
+
+  public enum RequestType {
+    ACCESS_TOKEN_REQUEST("at"),
+    ID_TOKEN_REQUEST("it"),
+    METADATA_SERVER_PIN("mds"),
+    UNSPECIFIED("unspecified");
+
+    private String label;
+
+    private RequestType(String label) {
+      this.label = label;
+    }
+
+    public String getLabel() {
+      return label;
+    }
+  }
+
+  static String getGoogleCredentialsMetricsHeader(
+      RequestType requestType, CredentialType credentialType) {
+    if (requestType == RequestType.UNSPECIFIED) {
+      return String.format(
+          "%s %s/%s",
+          MetricsUtils.getLanguageAndAuthLibraryVersions(), "cred-type", credentialType.getLabel());
+    }
+    if (credentialType == CredentialType.UNKNOWN) {
+      return String.format(
+          "%s %s/%s",
+          MetricsUtils.getLanguageAndAuthLibraryVersions(),
+          "auth-request-type",
+          requestType.getLabel());
+    }
+    return String.format(
+        "%s %s/%s %s/%s",
+        MetricsUtils.getLanguageAndAuthLibraryVersions(),
+        "auth-request-type",
+        requestType.getLabel(),
+        "cred-type",
+        credentialType.getLabel());
+  }
 }

oauth2_http/java/com/google/auth/oauth2/ServiceAccountCredentials.java

@@ -51,11 +51,13 @@
 import com.google.api.client.util.GenericData;
 import com.google.api.client.util.Joiner;
 import com.google.api.client.util.Preconditions;
+import com.google.auth.CredentialType;
 import com.google.auth.Credentials;
 import com.google.auth.RequestMetadataCallback;
 import com.google.auth.ServiceAccountSigner;
 import com.google.auth.http.AuthHttpConstants;
 import com.google.auth.http.HttpTransportFactory;
+import com.google.auth.oauth2.MetricsUtils.RequestType;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.common.collect.ImmutableList;
@@ -505,6 +507,12 @@ public AccessToken refreshAccessToken() throws IOException {
     HttpRequestFactory requestFactory = transportFactory.create().createRequestFactory();
     HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(tokenServerUri), content);
 
+    request
+        .getHeaders()
+        .set(
+            MetricsUtils.API_CLIENT_HEADER,
+            MetricsUtils.getGoogleCredentialsMetricsHeader(
+                RequestType.ACCESS_TOKEN_REQUEST, getCredentialType()));
     if (this.defaultRetriesEnabled) {
       request.setNumberOfRetries(OAuth2Utils.DEFAULT_NUMBER_OF_RETRIES);
     } else {
@@ -586,6 +594,14 @@ private IdToken getIdTokenOauthEndpoint(String targetAudience) throws IOExceptio
     UrlEncodedContent content = new UrlEncodedContent(tokenRequest);
 
     HttpRequest request = buildIdTokenRequest(tokenServerUri, transportFactory, content);
+    // add metric header
+    request
+        .getHeaders()
+        .set(
+            MetricsUtils.API_CLIENT_HEADER,
+            MetricsUtils.getGoogleCredentialsMetricsHeader(
+                RequestType.ID_TOKEN_REQUEST, getCredentialType()));
+
     HttpResponse httpResponse = executeRequest(request);
 
     GenericData responseData = httpResponse.parseAs(GenericData.class);
@@ -1013,9 +1029,12 @@ private Map<String, List<String>> getRequestMetadataForGdu(URI uri) throws IOExc
     // configured then use scopes to get access token.
     if ((!createScopedRequired() && !useJwtAccessWithScope)
         || isConfiguredForDomainWideDelegation()) {
+      // assertion token flow
+      this.setCredentialType(CredentialType.SERVICE_ACCOUNT_CREDENTIALS_AT);
       return super.getRequestMetadata(uri);
     }
-
+    // self-signed JWT flow
+    this.setCredentialType(CredentialType.SERVICE_ACCOUNT_CREDENTIALS_JWT);
     return getRequestMetadataWithSelfSignedJwt(uri);
   }