feat: add client logging with slf4j (#1586)

This Pr contains changes for adding client logging capability to auth.
see [go/java-client-logging-design](http://goto.google.com/java-client-logging-design)

Some logging setups are mirror of same setting in Gax ([pr 3403](googleapis/sdk-platform-java#3403))

Changes includes:
- add slf4j as optional dependency, enable logging only when GOOGLE_SDK_JAVA_LOGGING=true
- user app should add SLF4J + binding dependencies accordingly. For SLF4J 1x, we record extra info with MDC; for SLF4J2x, we record extra info with KeyValuePairs. More user guide to be added via README (see [draft](https://docs.google.com/document/d/1g8HJCstkEEZZc73gFlQO8uPGs07SkWKkr7NG-Yg4bvM/edit?tab=t.0#heading=h.9t58aw3up7to)). 
- If env var not true, or no binding present, default to no-op.
- Add log for request and response made to auth endpoints for UserCredentials, ServiceAccountCredentials, ComputeEngineCredentials, ImpersonatedCredentials. For token values included, added hash in log. Note this PR mainly focuses on adding logging setups, logging statements can be added incrementally later if necessary.


Here is an example logging output for access token request from UserCredentials when DEBUG level is allowed. (TO UPDATE)

```
{"@timestamp":"2024-12-04T21:10:48.596382834-05:00","@Version":"1","message":"Sending auth request to refresh access token.","logger_name":"com.google.auth.oauth2.UserCredentials","thread_name":"main","severity":"DEBUG","level_value":10000,"request.method":"POST","request.headers":{"x-goog-api-client":"gl-java/19.0.1 auth/1.32.2-SNAPSHOT cred-type/u","accept-encoding":["gzip"]},"request.url":"https://foo.com/bar","request.payload":{"refresh_token":"bae0258be92ea1d1e14f984507bee05ff4502a29104f4101d22a4a88706b0fc0","grant_type":"refresh_token","client_secret":"2d3c802ef65d75e88b098792e2268cd3f55a08bcbb8c8c4672f1195d1951d4b5","client_id":"ya29.1.AADtN_UtlxN3PuGAxrN2XQnZTVRvDyVWnYq4I6dws"}}
{"@timestamp":"2024-12-04T21:10:48.624914522-05:00","@Version":"1","message":"Received auth respond for refresh access token.","logger_name":"com.google.auth.oauth2.UserCredentials","thread_name":"main","severity":"INFO","level_value":20000,"response.status":"200","response.headers":"{}"}
{"@timestamp":"2024-12-04T21:10:48.627483862-05:00","@Version":"1","message":"Auth response payload.","logger_name":"com.google.auth.oauth2.UserCredentials","thread_name":"main","severity":"DEBUG","level_value":10000,"access_token":"1/MkS*****KPY2","refresh_token":"1/Tl6*****yGWY","token_type":"Bearer","expires_in":"3600"}
```

Testing setup -  Currently added flavor of tests: 
- unit tests with no extra dependency
- unit tests depending on either binding be present, or logback implementation to capture logging for test
- test for log behaviors for various requests where logs are added. (see LoggingTest)

Remaining issue with test scenarios: 
1. when no binding present: this is tested via regular tests
2.  when env var is T and binding present: tested via test-logging (profile with logback deps)
3. no SLF4J present: same logic as 1, it should be fine with coverage of 1. This is hard to setup this because SLF4J is needed at compile.
4. SLF4J 1x + binding: Hard to setup because SLF4J 2x is needed at compile

Author: zhumin8

.github/workflows/ci.yaml

@@ -36,6 +36,22 @@ jobs:
     - run: .kokoro/build.sh
       env:
         JOB_TYPE: test
+  units-logging:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        java: [11, 17, 21]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-java@v4
+      with:
+        distribution: temurin
+        java-version: ${{matrix.java}}
+    - run: java -version
+    - run: .kokoro/build.sh
+      env:
+        JOB_TYPE: test-logging
   units-java8:
     # Building using Java 17 and run the tests with Java 8 runtime
     name: "units (8)"

.github/workflows/sonar.yaml

@@ -38,9 +38,11 @@ jobs:
         SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
       run: |
         mvn -B verify -Dcheckstyle.skip \
+            -Djacoco.skip=true \
             -DenableFullTestCoverage \
             -Dsonar.coverage.jacoco.xmlReportPaths=oauth2_http/target/site/jacoco/jacoco.xml \
             org.sonarsource.scanner.maven:sonar-maven-plugin:sonar \
             -Dsonar.projectKey=googleapis_google-auth-library-java \
             -Dsonar.organization=googleapis \
             -Dsonar.host.url=https://sonarcloud.io
+

.kokoro/build.sh

@@ -51,6 +51,11 @@ test)
     mvn test -B -ntp -Dclirr.skip=true -Denforcer.skip=true ${SUREFIRE_JVM_OPT}
     RETURN_CODE=$?
     ;;
+test-logging)
+    echo "SUREFIRE_JVM_OPT: ${SUREFIRE_JVM_OPT}"
+    mvn clean test -P '!slf4j2x,slf4j2x-test' -B -ntp -Dclirr.skip=true -Denforcer.skip=true ${SUREFIRE_JVM_OPT}
+    RETURN_CODE=$?
+    ;;
 lint)
     mvn com.coveo:fmt-maven-plugin:check -B -ntp
     RETURN_CODE=$?
@@ -66,6 +71,7 @@ integration)
       -DtrimStackTrace=false \
       -Dclirr.skip=true \
       -Denforcer.skip=true \
+      -Djacoco.skip=true  \
       -fae \
       verify
     RETURN_CODE=$?
@@ -74,14 +80,14 @@ graalvmA)
     # Run Unit and Integration Tests with Native Image
     bash .kokoro/populate-secrets.sh
     export GOOGLE_APPLICATION_CREDENTIALS="${KOKORO_GFILE_DIR}/secret_manager/java-it-service-account"
-    mvn -B ${INTEGRATION_TEST_ARGS} -ntp -Pnative -Pnative-test test -pl 'oauth2_http'
+    mvn -B ${INTEGRATION_TEST_ARGS} -ntp -Pnative -Pnative-test -Pslf4j2x test -pl 'oauth2_http'
     RETURN_CODE=$?
     ;;
 graalvmB)
     # Run Unit and Integration Tests with Native Image
     bash .kokoro/populate-secrets.sh
     export GOOGLE_APPLICATION_CREDENTIALS="${KOKORO_GFILE_DIR}/secret_manager/java-it-service-account"
-    mvn -B ${INTEGRATION_TEST_ARGS} -ntp -Pnative -Pnative-test test -pl 'oauth2_http'
+    mvn -B ${INTEGRATION_TEST_ARGS} -ntp -Pnative -Pnative-test -Pslf4j2x test -pl 'oauth2_http'
     RETURN_CODE=$?
     ;;
 samples)

.kokoro/dependencies.sh

@@ -54,6 +54,7 @@ retry_with_backoff 3 10 \
   mvn install -B -V -ntp \
     -DskipTests=true \
     -Dmaven.javadoc.skip=true \
+    -Djacoco.skip=true \
     -Dclirr.skip=true
 
 mvn -B dependency:analyze -DfailOnWarning=true

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

@@ -51,6 +51,7 @@
 import com.google.common.base.Joiner;
 import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.io.BufferedReader;
@@ -94,6 +95,8 @@ public class ComputeEngineCredentials extends GoogleCredentials
   static final Duration COMPUTE_REFRESH_MARGIN = Duration.ofMinutes(3).plusSeconds(45);
 
   private static final Logger LOGGER = Logger.getLogger(ComputeEngineCredentials.class.getName());
+  private static final LoggerProvider LOGGER_PROVIDER =
+      LoggerProvider.forClazz(ComputeEngineCredentials.class);
 
   static final String DEFAULT_METADATA_SERVER_URL = "http://metadata.google.internal";
 
@@ -371,11 +374,14 @@ public AccessToken refreshAccessToken() throws IOException {
       throw new IOException(METADATA_RESPONSE_EMPTY_CONTENT_ERROR_MESSAGE);
     }
     GenericData responseData = response.parseAs(GenericData.class);
+    LoggingUtils.logResponsePayload(
+        responseData, LOGGER_PROVIDER, "Response payload for access token");
     String accessToken =
         OAuth2Utils.validateString(responseData, "access_token", PARSE_ERROR_PREFIX);
     int expiresInSeconds =
         OAuth2Utils.validateInt32(responseData, "expires_in", PARSE_ERROR_PREFIX);
     long expiresAtMilliseconds = clock.currentTimeMillis() + expiresInSeconds * 1000;
+
     return new AccessToken(accessToken, new Date(expiresAtMilliseconds));
   }
 
@@ -430,6 +436,12 @@ public IdToken idTokenWithAudience(String targetAudience, List<IdTokenProvider.O
       throw new IOException(METADATA_RESPONSE_EMPTY_CONTENT_ERROR_MESSAGE);
     }
     String rawToken = response.parseAsString();
+
+    LoggingUtils.log(
+        LOGGER_PROVIDER,
+        Level.FINE,
+        ImmutableMap.of("idToken", rawToken),
+        "Response Payload for ID token");
     return IdToken.create(rawToken);
   }
 
@@ -451,7 +463,23 @@ private HttpResponse getMetadataResponse(
     request.setThrowExceptionOnExecuteError(false);
     HttpResponse response;
     try {
+      String requestMessage;
+      String responseMessage;
+      if (requestType.equals(RequestType.ID_TOKEN_REQUEST)) {
+        requestMessage = "Sending request to get ID token";
+        responseMessage = "Received response for ID token request";
+      } else if (requestType.equals(RequestType.ACCESS_TOKEN_REQUEST)) {
+        requestMessage = "Sending request to refresh access token";
+        responseMessage = "Received response for refresh access token";
+      } else {
+        // TODO: this includes get universe domain and get default sa.
+        // refactor for more clear logging message.
+        requestMessage = "Sending request for universe domain/default service account";
+        responseMessage = "Received response for universe domain/default service account";
+      }
+      LoggingUtils.logRequest(request, LOGGER_PROVIDER, requestMessage);
       response = request.execute();
+      LoggingUtils.logResponse(response, LOGGER_PROVIDER, responseMessage);
     } catch (UnknownHostException exception) {
       throw new IOException(
           "ComputeEngineCredentials cannot find the metadata server. This is"
@@ -730,6 +758,8 @@ private String getDefaultServiceAccount() throws IOException {
       throw new IOException(METADATA_RESPONSE_EMPTY_CONTENT_ERROR_MESSAGE);
     }
     GenericData responseData = response.parseAs(GenericData.class);
+    LoggingUtils.logResponsePayload(
+        responseData, LOGGER_PROVIDER, "Received default service account payload");
     Map<String, Object> defaultAccount =
         OAuth2Utils.validateMap(responseData, "default", PARSE_ERROR_ACCOUNT);
     return OAuth2Utils.validateString(defaultAccount, "email", PARSE_ERROR_ACCOUNT);

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

@@ -72,6 +72,7 @@ class IamUtils {
       "https://iamcredentials.%s/v1/projects/-/serviceAccounts/%s:signBlob";
   private static final String PARSE_ERROR_MESSAGE = "Error parsing error message response. ";
   private static final String PARSE_ERROR_SIGNATURE = "Error parsing signature response. ";
+  private static final LoggerProvider LOGGER_PROVIDER = LoggerProvider.forClazz(IamUtils.class);
 
   // Following guidance for IAM retries:
   // https://cloud.google.com/iam/docs/retry-strategy#errors-to-retry
@@ -154,7 +155,11 @@ private static String getSignature(
                     IamUtils.IAM_RETRYABLE_STATUS_CODES.contains(response.getStatusCode())));
     request.setIOExceptionHandler(new HttpBackOffIOExceptionHandler(backoff));
 
+    LoggingUtils.logRequest(
+        request, LOGGER_PROVIDER, "Sending request to get signature to sign the blob");
     HttpResponse response = request.execute();
+    LoggingUtils.logResponse(
+        response, LOGGER_PROVIDER, "Received response for signature to sign the blob");
     int statusCode = response.getStatusCode();
     if (statusCode >= 400 && statusCode < HttpStatusCodes.STATUS_CODE_SERVER_ERROR) {
       GenericData responseError = response.parseAs(GenericData.class);
@@ -181,6 +186,8 @@ private static String getSignature(
     }
 
     GenericData responseData = response.parseAs(GenericData.class);
+    LoggingUtils.logResponsePayload(
+        responseData, LOGGER_PROVIDER, "Response payload for sign blob");
     return OAuth2Utils.validateString(responseData, "signedBlob", PARSE_ERROR_SIGNATURE);
   }
 
@@ -234,7 +241,10 @@ static IdToken getIdToken(
         MetricsUtils.getGoogleCredentialsMetricsHeader(
             RequestType.ID_TOKEN_REQUEST, credentialTypeForMetrics));
 
+    LoggingUtils.logRequest(request, LOGGER_PROVIDER, "Sending request to get ID token");
     HttpResponse response = request.execute();
+
+    LoggingUtils.logResponse(response, LOGGER_PROVIDER, "Received response for ID token request");
     int statusCode = response.getStatusCode();
     if (statusCode >= 400 && statusCode < HttpStatusCodes.STATUS_CODE_SERVER_ERROR) {
       GenericData responseError = response.parseAs(GenericData.class);
@@ -259,6 +269,8 @@ static IdToken getIdToken(
     }
 
     GenericJson responseData = response.parseAs(GenericJson.class);
+    LoggingUtils.logResponsePayload(
+        responseData, LOGGER_PROVIDER, "Response payload for ID token request");
     String rawToken = OAuth2Utils.validateString(responseData, "token", PARSE_ERROR_MESSAGE);
     return IdToken.create(rawToken);
   }

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

@@ -110,6 +110,8 @@ public class ImpersonatedCredentials extends GoogleCredentials
   private int lifetime;
   private String iamEndpointOverride;
   private final String transportFactoryClassName;
+  private static final LoggerProvider LOGGER_PROVIDER =
+      LoggerProvider.forClazz(ImpersonatedCredentials.class);
 
   private transient HttpTransportFactory transportFactory;
 
@@ -553,12 +555,17 @@ public AccessToken refreshAccessToken() throws IOException {
 
     HttpResponse response = null;
     try {
+      LoggingUtils.logRequest(request, LOGGER_PROVIDER, "Sending request to refresh access token");
       response = request.execute();
+      LoggingUtils.logResponse(
+          response, LOGGER_PROVIDER, "Received response for refresh access token");
     } catch (IOException e) {
       throw new IOException("Error requesting access token", e);
     }
 
     GenericData responseData = response.parseAs(GenericData.class);
+    LoggingUtils.logResponsePayload(
+        responseData, LOGGER_PROVIDER, "Response payload for access token");
     response.disconnect();
 
     String accessToken =

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

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2025 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.oauth2;
+
+import org.slf4j.Logger;
+
+class LoggerProvider {
+
+  private Logger logger;
+  private final Class<?> clazz;
+
+  private LoggerProvider(Class<?> clazz) {
+    this.clazz = clazz;
+  }
+
+  static LoggerProvider forClazz(Class<?> clazz) {
+    return new LoggerProvider(clazz);
+  }
+
+  Logger getLogger() {
+    if (logger == null) {
+      this.logger = Slf4jUtils.getLogger(clazz);
+    }
+    return logger;
+  }
+}

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

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2025 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.oauth2;
+
+import com.google.api.client.http.HttpRequest;
+import com.google.api.client.http.HttpResponse;
+import com.google.api.client.util.GenericData;
+import java.util.Map;
+import java.util.logging.Level;
+
+class LoggingUtils {
+
+  static final String GOOGLE_SDK_JAVA_LOGGING = "GOOGLE_SDK_JAVA_LOGGING";
+  private static EnvironmentProvider environmentProvider =
+      SystemEnvironmentProvider.getInstance(); // this may be reset for testing purpose
+
+  private static boolean loggingEnabled = isLoggingEnabled();
+
+  // expose this setter only for testing purposes
+  static void setEnvironmentProvider(EnvironmentProvider provider) {
+    environmentProvider = provider;
+    // Recalculate LOGGING_ENABLED after setting the new provider
+    loggingEnabled = isLoggingEnabled();
+  }
+
+  static boolean isLoggingEnabled() {
+    String enableLogging = environmentProvider.getEnv(GOOGLE_SDK_JAVA_LOGGING);
+    return "true".equalsIgnoreCase(enableLogging);
+  }
+
+  static void logRequest(HttpRequest request, LoggerProvider loggerProvider, String message) {
+    if (loggingEnabled) {
+      Slf4jLoggingHelpers.logRequest(request, loggerProvider, message);
+    }
+  }
+
+  static void logResponse(HttpResponse response, LoggerProvider loggerProvider, String message) {
+    if (loggingEnabled) {
+      Slf4jLoggingHelpers.logResponse(response, loggerProvider, message);
+    }
+  }
+
+  static void logResponsePayload(
+      GenericData genericData, LoggerProvider loggerProvider, String message) {
+    if (loggingEnabled) {
+      Slf4jLoggingHelpers.logResponsePayload(genericData, loggerProvider, message);
+    }
+  }
+
+  // generic log method to use when not logging standard request, response and payload
+  static void log(
+      LoggerProvider loggerProvider, Level level, Map<String, Object> contextMap, String message) {
+    if (loggingEnabled) {
+      Slf4jLoggingHelpers.log(loggerProvider, level, contextMap, message);
+    }
+  }
+
+  private LoggingUtils() {}
+}