feat(auth): support GKE agent identity credential bundle for bound tokens and mTLS

google-auth-library-java/oauth2_http/java/com/google/auth/mtls/DefaultMtlsProviderFactory.java

@@ -40,9 +40,10 @@ public class DefaultMtlsProviderFactory {
 
   /**
    * Creates an instance of {@link MtlsProvider}. It first attempts to create an {@link
-   * com.google.auth.mtls.X509Provider}. If the certificate source is unavailable, it falls back to
-   * creating a {@link SecureConnectProvider}. If the secure connect provider also fails, it throws
-   * a {@link com.google.auth.mtls.CertificateSourceUnavailableException}.
+   * com.google.auth.mtls.X509Provider}, which also falls back to the GKE credential bundle when no
+   * certificate configuration is present. If the certificate source is unavailable, it falls back
+   * to creating a {@link SecureConnectProvider}. If the secure connect provider also fails, it
+   * throws a {@link com.google.auth.mtls.CertificateSourceUnavailableException}.
    *
    * @return an instance of {@link MtlsProvider}.
    * @throws com.google.auth.mtls.CertificateSourceUnavailableException if neither provider can be
@@ -53,7 +54,7 @@ public static MtlsProvider create() throws IOException {
     // Note: The caller should handle CertificateSourceUnavailableException gracefully, since
     // it is an expected error case. All other IOExceptions are unexpected and should be surfaced
     // up the call stack.
-    MtlsProvider mtlsProvider = new X509Provider();
+    MtlsProvider mtlsProvider = X509Provider.createForTransport();
     if (mtlsProvider.isAvailable()) {
       return mtlsProvider;
     }

google-auth-library-java/oauth2_http/java/com/google/auth/mtls/MtlsUtils.java

@@ -33,6 +33,7 @@
 import com.google.api.core.InternalApi;
 import com.google.auth.oauth2.EnvironmentProvider;
 import com.google.auth.oauth2.PropertyProvider;
+import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Strings;
 import com.google.common.io.BaseEncoding;
 import java.io.File;
@@ -58,10 +59,68 @@ public class MtlsUtils {
   static final String WELL_KNOWN_CERTIFICATE_CONFIG_FILE = "certificate_config.json";
   static final String CLOUDSDK_CONFIG_DIRECTORY = "gcloud";
 
+  /**
+   * Well-known path of the combined certificate chain and private key bundle that GKE delivers to
+   * pods with Agent Identity (Pod Certificates). Used as a fallback client certificate source when
+   * no certificate configuration file is configured or present.
+   */
+  static final String GKE_CREDENTIAL_BUNDLE_PATH =
+      "/var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem";
+
+  private static volatile String gkeCredentialBundlePath = GKE_CREDENTIAL_BUNDLE_PATH;
+
   private MtlsUtils() {
     // Prevent instantiation for Utility class
   }
 
+  /**
+   * Returns {@code true} if a certificate configuration is configured or present: either {@code
+   * GOOGLE_API_CERTIFICATE_CONFIG} is set, or the well-known gcloud {@code certificate_config.json}
+   * file exists. When this returns {@code true}, the GKE credential bundle fallback is not used, so
+   * the certificate used for mTLS and the certificate bound to tokens always come from the same
+   * source.
+   */
+  public static boolean hasCertificateConfiguration(
+      EnvironmentProvider envProvider, PropertyProvider propProvider) {
+    if (!Strings.isNullOrEmpty(envProvider.getEnv(CERTIFICATE_CONFIGURATION_ENV_VARIABLE))) {
+      return true;
+    }
+    try {
+      return getWellKnownCertificateConfigFile(envProvider, propProvider).exists();
+    } catch (IOException e) {
+      // APPDATA missing on Windows, etc. No well-known configuration file.
+      return false;
+    }
+  }
+
+  /**
+   * Returns the GKE credential bundle path if no certificate configuration is configured or present
+   * (see {@link #hasCertificateConfiguration}) and the bundle exists and is readable; otherwise
+   * returns {@code null}.
+   */
+  static @Nullable String getGkeCredentialBundlePath(
+      EnvironmentProvider envProvider, PropertyProvider propProvider) {
+    if (hasCertificateConfiguration(envProvider, propProvider)) {
+      return null;
+    }
+    return findGkeCredentialBundle();
+  }
+
+  /**
+   * Returns the GKE credential bundle path if it is a readable, non-empty regular file, otherwise
+   * null.
+   */
+  private static @Nullable String findGkeCredentialBundle() {
+    File bundle = new File(gkeCredentialBundlePath);
+    return bundle.isFile() && bundle.canRead() && bundle.length() > 0 ? bundle.getPath() : null;
+  }
+
+  /** Overrides the GKE credential bundle path for testing; {@code null} restores the default. */
+  @VisibleForTesting
+  static void setGkeCredentialBundlePathForTesting(@Nullable String path) {
+    gkeCredentialBundlePath = path != null ? path : GKE_CREDENTIAL_BUNDLE_PATH;
+  }
+
   /**
    * Returns if mutual TLS client certificate should be used. Returns true if valid workload
    * certificates are configured or if GOOGLE_API_USE_CLIENT_CERTIFICATE is explicitly set to true
@@ -89,16 +148,20 @@ public static boolean useMtlsClientCertificate(
    * <ol>
    *   <li><b>Non-null {@link String} (Valid happy path):</b> A valid workload certificate
    *       configuration was found and both the certificate and private key files exist and are
-   *       readable.
+   *       readable; or no certificate configuration is set or present and the GKE credential bundle
+   *       ({@code /var/run/secrets/workload-spiffe-credentials/
+   *       x509.credential-bundle.private-key.pem}) exists and is readable, in which case the bundle
+   *       path is returned.
    *   <li><b>{@link IllegalStateException} (Invalid state - fail closed):</b> An explicit {@code
    *       GOOGLE_API_CERTIFICATE_CONFIG} path or an existing default well-known certificate
    *       configuration file is missing, unreadable, malformed, or references missing/unreadable
    *       certificate or private key files. This is treated as an unrecoverable misconfiguration.
    *   <li><b>{@code null} (Safe fallback / fail open):</b> Client certificates are explicitly
    *       disabled via {@code GOOGLE_API_USE_CLIENT_CERTIFICATE=false}, no explicit configuration
-   *       is set and the default well-known configuration file does not exist on disk, or the
-   *       configuration specifies an non-workload source (e.g., ECP/PKCS11 without a {@code
-   *       workload} section). Callers can proceed without workload certificate file polling.
+   *       is set and neither the default well-known configuration file nor a readable GKE
+   *       credential bundle exists on disk, or the configuration specifies an non-workload source
+   *       (e.g., ECP/PKCS11 without a {@code workload} section). Callers can proceed without
+   *       workload certificate file polling.
    * </ol>
    */
   public static @Nullable String getWorkloadCertPath(
@@ -175,9 +238,14 @@ public static boolean useMtlsClientCertificate(
         checkCertAndKeyFilesReadable(config, defaultConfigFile.getAbsolutePath(), true);
         return config.getCertPath();
       }
+      // A default configuration file exists without a workload section (e.g. ECP); it takes
+      // precedence over the GKE credential bundle.
+      return null;
     }
 
-    return null;
+    // 3. GKE credential bundle (Pod Certificates), used only when no certificate configuration
+    // file is configured or present. The combined bundle serves as both certificate and key.
+    return findGkeCredentialBundle();
   }
 
   private static void checkCertAndKeyFilesReadable(

google-auth-library-java/oauth2_http/java/com/google/auth/mtls/X509Provider.java

@@ -38,6 +38,7 @@
 import com.google.auth.oauth2.SystemPropertyProvider;
 import java.io.File;
 import java.io.FileInputStream;
+import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.SequenceInputStream;
@@ -54,7 +55,8 @@
 public class X509Provider implements MtlsProvider {
   private final EnvironmentProvider envProvider;
   private final PropertyProvider propProvider;
-  private final String certConfigPathOverride;
+  private final @Nullable String certConfigPathOverride;
+  private final boolean allowGkeCredentialBundle;
 
   /**
    * Creates an X509 provider with an override path for the certificate configuration, bypassing the
@@ -70,9 +72,39 @@ public X509Provider(
       EnvironmentProvider envProvider,
       PropertyProvider propProvider,
       String certConfigPathOverride) {
+    this(envProvider, propProvider, certConfigPathOverride, false);
+  }
+
+  /**
+   * Creates an X509 provider that optionally falls back to the GKE credential bundle when no
+   * certificate configuration is present.
+   *
+   * @param envProvider environment provider used for environment variables
+   * @param propProvider property provider used for system properties
+   * @param certConfigPathOverride the path to read the certificate configuration from.
+   * @param allowGkeCredentialBundle whether to fall back to the GKE credential bundle when no
+   *     certificate configuration is present and {@code certConfigPathOverride} is null.
+   */
+  X509Provider(
+      EnvironmentProvider envProvider,
+      PropertyProvider propProvider,
+      @Nullable String certConfigPathOverride,
+      boolean allowGkeCredentialBundle) {
     this.envProvider = envProvider;
     this.propProvider = propProvider;
     this.certConfigPathOverride = certConfigPathOverride;
+    this.allowGkeCredentialBundle = allowGkeCredentialBundle;
+  }
+
+  /**
+   * Creates an X.509 provider for the client transport layer. In addition to the locations checked
+   * by {@link #X509Provider()}, it falls back to the GKE credential bundle when no certificate
+   * configuration is present, so that the transport uses the same certificate that {@link
+   * MtlsUtils#getWorkloadCertPath} reports for certificate-bound tokens.
+   */
+  static X509Provider createForTransport() {
+    return new X509Provider(
+        SystemEnvironmentProvider.getInstance(), SystemPropertyProvider.getInstance(), null, true);
   }
 
   /**
@@ -105,6 +137,10 @@ public X509Provider() {
    *   <li>The certificate config override path, if set.
    *   <li>The path pointed to by the "GOOGLE_API_CERTIFICATE_CONFIG" environment variable
    *   <li>The well known gcloud location for the certificate configuration file.
+   *   <li>If none of the above is configured or present, and this provider was created with {@link
+   *       #createForTransport()}, the GKE credential bundle at {@code
+   *       /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem},
+   *       which contains both the certificate chain and the private key.
    * </ul>
    *
    * @return a KeyStore containing the X.509 certificate specified by the certificate configuration.
@@ -114,6 +150,23 @@ public X509Provider() {
    */
   @Override
   public KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOException {
+    if (allowGkeCredentialBundle && certConfigPathOverride == null) {
+      String gkeCredentialBundlePath =
+          MtlsUtils.getGkeCredentialBundlePath(envProvider, propProvider);
+      if (gkeCredentialBundlePath != null) {
+        try (InputStream bundleStream = new FileInputStream(new File(gkeCredentialBundlePath))) {
+          return SecurityUtils.createMtlsKeyStore(bundleStream);
+        } catch (FileNotFoundException e) {
+          // The bundle was removed (e.g. mid-rotation) after the availability check.
+          throw new CertificateSourceUnavailableException(
+              "GKE credential bundle is no longer available: " + gkeCredentialBundlePath, e);
+        } catch (Exception e) {
+          throw new IOException(
+              "X509Provider: Unable to load GKE credential bundle: " + gkeCredentialBundlePath, e);
+        }
+      }
+    }
+
     WorkloadCertificateConfiguration workloadCertConfig =
         MtlsUtils.getWorkloadCertificateConfiguration(
             envProvider, propProvider, certConfigPathOverride);