feat(oauth2): implement IAM impersonation mTLS transport pinning and 401 recovery

google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/AwsCredentials.java

@@ -120,6 +120,11 @@ public class AwsCredentials extends ExternalAccountCredentials {
 
   @Override
   public AccessToken refreshAccessToken() throws IOException {
+    return refreshAccessToken(this.transportFactory);
+  }
+
+  @Override
+  public AccessToken refreshAccessToken(HttpTransportFactory transportFactory) throws IOException {
     StsTokenExchangeRequest.Builder stsTokenExchangeRequest =
         StsTokenExchangeRequest.newBuilder(retrieveSubjectToken(), getSubjectTokenType())
             .setAudience(getAudience());
@@ -130,7 +135,8 @@ public AccessToken refreshAccessToken() throws IOException {
       stsTokenExchangeRequest.setScopes(new ArrayList<>(scopes));
     }
 
-    return exchangeExternalCredentialForAccessToken(stsTokenExchangeRequest.build());
+    return exchangeExternalCredentialForAccessToken(
+        stsTokenExchangeRequest.build(), transportFactory);
   }
 
   @Override

google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java

@@ -95,7 +95,7 @@
 
   protected transient HttpTransportFactory transportFactory;
 
-  protected @Nullable ImpersonatedCredentials impersonatedCredentials;
+  protected volatile @Nullable ImpersonatedCredentials impersonatedCredentials;
 
   private final EnvironmentProvider environmentProvider;
   private final PropertyProvider propertyProvider;
@@ -292,16 +292,19 @@
       sourceCredentials =
           AwsCredentials.newBuilder((AwsCredentials) this)
               .setServiceAccountImpersonationUrl(null)
+              .setScopes(Collections.singletonList(OAuth2Utils.CLOUD_PLATFORM_SCOPE))
               .build();
     } else if (this instanceof PluggableAuthCredentials) {
       sourceCredentials =
           PluggableAuthCredentials.newBuilder((PluggableAuthCredentials) this)
               .setServiceAccountImpersonationUrl(null)
+              .setScopes(Collections.singletonList(OAuth2Utils.CLOUD_PLATFORM_SCOPE))
               .build();
     } else {
       sourceCredentials =
           IdentityPoolCredentials.newBuilder((IdentityPoolCredentials) this)
               .setServiceAccountImpersonationUrl(null)
+              .setScopes(Collections.singletonList(OAuth2Utils.CLOUD_PLATFORM_SCOPE))
               .build();
     }
 
@@ -363,7 +366,7 @@
    * external source for authentication to Google Cloud Platform, you must validate it before
    * providing it to any Google API or library. Providing an unvalidated credential configuration to
    * Google APIs can compromise the security of your systems and data. For more information, refer
    * to {@see <a
    * href="https://cloud.google.com/docs/authentication/external/externally-sourced-credentials">documentation</a>}.
    *
    * @param credentialsStream the stream with the credential definition
@@ -384,7 +387,7 @@
    * external source for authentication to Google Cloud Platform, you must validate it before
    * providing it to any Google API or library. Providing an unvalidated credential configuration to
    * Google APIs can compromise the security of your systems and data. For more information, refer
    * to {@see <a
    * href="https://cloud.google.com/docs/authentication/external/externally-sourced-credentials">documentation</a>}.
    *
    * @param credentialsStream the stream with the credential definition
@@ -526,6 +529,19 @@
     return this.serviceAccountImpersonationUrl != null && this.impersonatedCredentials == null;
   }
 
+  /**
+   * Refreshes the access token using the specified transport factory. Default implementation
+   * delegates to {@link #refreshAccessToken()}. Subclasses should override this method if they
+   * support transport pinning per refresh cycle.
+   *
+   * @param transportFactory the HTTP transport factory to use for this refresh cycle
+   * @return the refreshed access token
+   * @throws IOException if the token refresh fails
+   */
+  public AccessToken refreshAccessToken(HttpTransportFactory transportFactory) throws IOException {
+    return refreshAccessToken();
+  }
+
   /**
    * Exchanges the external credential for a Google Cloud access token.
    *
@@ -556,7 +572,7 @@
       this.impersonatedCredentials = this.buildImpersonatedCredentials();
     }
     if (this.impersonatedCredentials != null) {
-      return this.impersonatedCredentials.refreshAccessToken();
+      return this.impersonatedCredentials.refreshAccessToken(cycleTransportFactory);
     }
 
     StsRequestHandler.Builder requestHandler =
@@ -626,6 +642,7 @@
     // Properly deserialize the transient transportFactory.
     input.defaultReadObject();
     transportFactory = newInstance(transportFactoryClassName);
+    impersonatedCredentials = null;
   }
 
   public @Nullable String getServiceAccountImpersonationUrl() {

google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/IdentityPoolCredentials.java

@@ -72,7 +72,7 @@ public class IdentityPoolCredentials extends ExternalAccountCredentials {
   private final @Nullable String actorTokenType;
   // Transient: not serialized directly. Reconstructed in readObject() from the credentialSource
   // certificate config so deserialized credentials remain usable for mTLS and refresh.
-  private transient @Nullable X509Provider x509Provider;
+  private transient volatile @Nullable X509Provider x509Provider;
   private final ExternalAccountSupplierContext supplierContext;
   private final String metricsHeaderValue;
 
@@ -115,7 +115,7 @@ public class IdentityPoolCredentials extends ExternalAccountCredentials {
               || builder.transportFactory == OAuth2Utils.HTTP_TRANSPORT_FACTORY
               || builder.transportFactory instanceof OAuth2Utils.DefaultHttpTransportFactory
               || builder.transportFactory.getClass() == MtlsHttpTransportFactory.class) {
-            this.transportFactory = new MtlsHttpTransportFactory(mtlsKeyStore);
+            this.transportFactory = createMtlsTransportFactory(mtlsKeyStore);
           } else if (!(builder.transportFactory instanceof MtlsHttpTransportFactory)) {
             LOGGER_PROVIDER
                 .getLogger()
@@ -182,7 +182,7 @@ public class IdentityPoolCredentials extends ExternalAccountCredentials {
     if (this.actorTokenSupplier != null && !isMtlsConfigured()) {
       throw new IllegalArgumentException(
           "Actor tokens are only supported for mTLS token exchanges. Please configure a certificate"
-              + " source or MtlsHttpTransportFactory.");
+              + " configuration in the credential source or provide an mTLS-enabled transport.");
     }
 
     if (this.actorTokenSupplier != null) {
@@ -228,15 +228,35 @@ private boolean isMtlsConfigured() {
             && ((MtlsHttpTransportFactory) this.transportFactory).hasKeyStore());
   }
 
+  private boolean shouldUseMtlsTransportFactory() {
+    return this.transportFactory == null
+        || this.transportFactory == OAuth2Utils.HTTP_TRANSPORT_FACTORY
+        || this.transportFactory instanceof OAuth2Utils.DefaultHttpTransportFactory
+        || this.transportFactory.getClass() == MtlsHttpTransportFactory.class;
+  }
+
   @Override
   public AccessToken refreshAccessToken() throws IOException {
     // Per-cycle cert pinning: snapshot the KeyStore at the start of each refresh cycle.
     HttpTransportFactory cycleTransportFactory = this.transportFactory;
-    if (this.x509Provider != null && this.transportFactory instanceof MtlsHttpTransportFactory) {
+    if (this.x509Provider != null && shouldUseMtlsTransportFactory()) {
       KeyStore pinnedKeyStore = this.x509Provider.getKeyStore();
-      cycleTransportFactory = new MtlsHttpTransportFactory(pinnedKeyStore);
+      cycleTransportFactory = createMtlsTransportFactory(pinnedKeyStore);
     }
+    return refreshWithRetry(cycleTransportFactory, true);
+  }
+
+  @Override
+  public AccessToken refreshAccessToken(HttpTransportFactory cycleTransportFactory)
+      throws IOException {
+    // Retry is intentionally disabled when an explicit cycleTransportFactory is supplied to
+    // ensure transport synchronization across multi-step token exchanges (e.g. STS and IAM)
+    // and prevent nested retry amplification. Outer callers manage retry coordination.
+    return refreshWithRetry(cycleTransportFactory, false);
+  }
 
+  private AccessToken refreshWithRetry(
+      HttpTransportFactory cycleTransportFactory, boolean allowRetry) throws IOException {
     // Read subject and actor tokens, atomically if from the same file supplier.
     String subjectToken;
     String actorToken = null;
@@ -270,22 +290,52 @@ public AccessToken refreshAccessToken() throws IOException {
     try {
       return exchangeExternalCredentialForAccessToken(
           stsTokenExchangeRequest.build(), cycleTransportFactory);
-    } catch (OAuthException e) {
-      if (e.getHttpStatusCode() == 401
+    } catch (Exception e) {
+      if (allowRetry
+          && OAuth2Utils.isUnauthorizedException(e)
           && this.x509Provider != null
-          && this.transportFactory instanceof MtlsHttpTransportFactory) {
+          && shouldUseMtlsTransportFactory()) {
+        KeyStore freshKeyStore;
         try {
-          // On 401, re-read from X509Provider for fresh certs and retry once.
-          KeyStore freshKeyStore = this.x509Provider.getKeyStore();
-          HttpTransportFactory retryTransportFactory = new MtlsHttpTransportFactory(freshKeyStore);
-          return exchangeExternalCredentialForAccessToken(
-              stsTokenExchangeRequest.build(), retryTransportFactory);
-        } catch (IOException retryException) {
-          retryException.addSuppressed(e);
-          throw retryException;
+          // On 401, re-read from X509Provider for fresh certs.
+          freshKeyStore = this.x509Provider.getKeyStore();
+        } catch (IOException reloadException) {
+          if (reloadException != e) {
+            reloadException.addSuppressed(e);
+          }
+          throw reloadException;
+        } catch (Exception reloadException) {
+          IOException ioException =
+              new IOException("Failed to reload certificate on retry", reloadException);
+          if (ioException != e) {
+            ioException.addSuppressed(e);
+          }
+          throw ioException;
         }
+
+        HttpTransportFactory retryTransportFactory = createMtlsTransportFactory(freshKeyStore);
+        try {
+          return refreshWithRetry(retryTransportFactory, false);
+        } catch (Exception retryException) {
+          if (retryException != e) {
+            retryException.addSuppressed(e);
+          }
+          if (retryException instanceof IOException) {
+            throw (IOException) retryException;
+          }
+          if (retryException instanceof RuntimeException) {
+            throw (RuntimeException) retryException;
+          }
+          throw new IOException(retryException);
+        }
+      }
+      if (e instanceof IOException) {
+        throw (IOException) e;
+      }
+      if (e instanceof RuntimeException) {
+        throw (RuntimeException) e;
       }
-      throw e;
+      throw new IOException(e);
     }
   }
 
@@ -324,6 +374,11 @@ HttpTransportFactory getTransportFactory() {
     return this.x509Provider;
   }
 
+  @VisibleForTesting
+  HttpTransportFactory createMtlsTransportFactory(KeyStore keyStore) {
+    return new MtlsHttpTransportFactory(keyStore);
+  }
+
   /** Clones the IdentityPoolCredentials with the specified scopes. */
   @Override
   public IdentityPoolCredentials createScoped(Collection<String> newScopes) {
@@ -353,7 +408,7 @@ private IdentityPoolSubjectTokenSupplier createCertificateSubjectTokenSupplier(
         || builder.transportFactory == OAuth2Utils.HTTP_TRANSPORT_FACTORY
         || builder.transportFactory instanceof OAuth2Utils.DefaultHttpTransportFactory
         || builder.transportFactory.getClass() == MtlsHttpTransportFactory.class) {
-      this.transportFactory = new MtlsHttpTransportFactory(mtlsKeyStore);
+      this.transportFactory = createMtlsTransportFactory(mtlsKeyStore);
     } else if (!(builder.transportFactory instanceof MtlsHttpTransportFactory)) {
       LOGGER_PROVIDER
           .getLogger()
@@ -395,7 +450,9 @@ private void readObject(ObjectInputStream input) throws IOException, ClassNotFou
           new X509Provider(getEnvironmentProvider(), getPropertyProvider(), explicitCertConfigPath);
       try {
         KeyStore mtlsKeyStore = this.x509Provider.getKeyStore();
-        this.transportFactory = new MtlsHttpTransportFactory(mtlsKeyStore);
+        if (shouldUseMtlsTransportFactory()) {
+          this.transportFactory = createMtlsTransportFactory(mtlsKeyStore);
+        }
       } catch (Exception e) {
         // Cert loading failure will be handled on refreshAccessToken()
       }
@@ -441,8 +498,11 @@ public static class Builder extends ExternalAccountCredentials.Builder {
       if (this.credentialSource == null) {
         this.subjectTokenSupplier = credentials.subjectTokenSupplier;
         this.actorTokenSupplier = credentials.actorTokenSupplier;
+      } else if (credentials.actorTokenSupplier != credentials.subjectTokenSupplier) {
+        this.actorTokenSupplier = credentials.actorTokenSupplier;
       }
-      // Note: when credentialSource is present, subjectTokenSupplier and actorTokenSupplier
+      // Note: when credentialSource is present, subjectTokenSupplier and file-based
+      // actorTokenSupplier
       // are intentionally NOT copied here. They will be reconstructed from credentialSource
       // during build(), which ensures they share the same FileIdentityPoolSubjectTokenSupplier
       // instance for atomic token reads.